Add clean command

docs/cli.md

@@ -24,6 +24,7 @@ Implemented commands:
 - `session init`: create local or remote `session.yml`.
 - `artifacts list`: list effective artifact source IDs.
 - `locks`: list, add, and remove archive promotion locks.
+- `clean`: remove local workspace/spool state for one session or all local sessions.
 
 Unknown commands print usage and exit non-zero.
 
@@ -94,6 +95,17 @@ Valid stage names:
 - `--force`: overwrite local conflicting files with remote archive files.
 - `--include-audio`: include durable archived `audio/**` files in restore scope.
 
+### `clean`
+
+- `--session-id <value>`: required for session cleanup unless `--all` is set.
+- `--config <path>`
+- `--campaign <path>`
+- `--session <path>`
+- `--previous-session-id <value>`
+- `--all`: clean all local session work/spool state using pipeline config only.
+- `--dry-run`: print cleanup targets without deleting.
+- `--clear-cache`: also remove matching S3 audio cache entries.
+
 ### `status`
 
 - `--manifest <path>`: inspect one manifest file.
@@ -378,6 +390,38 @@ Common failure cases:
 
 When `--include-audio` is set, S3 audio files are restored through the shared audio cache. Cache hits avoid re-downloading large audio objects.
 
+### `clean`
+
+Purpose:
+- Remove local Narratio work/spool state for testing, reruns, or recovery from corrupted local files.
+- Preserve durable S3 audio cache state unless `--clear-cache` is passed.
+
+Syntax:
+
+```bash
+narratio clean --session-id <id> [--config <pipeline.yml>] [--campaign <campaign.yml>] [--session <session.yml>] [--previous-session-id <id>] [--dry-run] [--clear-cache]
+narratio clean --all [--config <pipeline.yml>] [--dry-run] [--clear-cache]
+```
+
+Session cleanup deletes:
+- `{workspace.root}/work/{campaign}/{session_id}`
+- `{spool.root}/{campaign}/{session_id}`
+
+All-session cleanup deletes:
+- `{workspace.root}/work`
+- the contents of `{spool.root}`, while preserving the spool root directory itself.
+
+Cache behavior:
+- cache is preserved by default.
+- `--clear-cache` in session mode removes cached S3 audio files for the resolved session.
+- `--all --clear-cache` removes the configured Narratio S3 audio cache namespace for the configured bucket/root prefix.
+- `--clear-cache` does not delete arbitrary files under `pipeline.cache.root`.
+
+Common failure cases:
+- missing `--session-id` when `--all` is not set.
+- combining `--all` with `--campaign`, `--session`, `--session-id`, or `--previous-session-id`.
+- unsafe cleanup target, such as a symlink, a non-directory session target, a configured root directory, or a path outside the configured root.
+
 ## Common Workflows
 
 Default-discovery run:
@@ -423,6 +467,20 @@ Rehydrate canonical previous-session inputs after artifact-input changes:
 narratio run-stage --session-id 2026-04-04 --force prepare
 ```
 
+Reset local state before testing restore:
+
+```bash
+narratio clean --session-id 2026-04-04 --dry-run
+narratio clean --session-id 2026-04-04
+narratio restore --session-id 2026-04-04 --include-audio
+```
+
+Clean all local sessions while keeping cached S3 audio:
+
+```bash
+narratio clean --all
+```
+
 ## Diagnostic / Recovery Commands
 
 Inspect stage status:

docs/config.md

@@ -245,6 +245,7 @@ Operational notes:
 - operator-created mutable locks are stored at `{root_prefix}/campaigns/{campaign}/sessions/{session_id}/locks.yml` and are merged with static locks.
 - Narratio does not auto-promote all generated analyze artifacts.
 - `restore` reads the same config/campaign/session inputs and restore scope is bounded by committed archive current state.
+- `clean` removes workspace/spool state by default and preserves `pipeline.cache.root` unless `--clear-cache` is passed.
 
 ## 6. Full pipeline reference
 
@@ -408,6 +409,7 @@ Restore-related implications:
 - restore remote identity requires archive S3 identity to resolve (`pipeline.storage.s3.bucket` and session prefix derivation inputs).
 - restore scope considers committed current state and durable paths (`manifest.json`, `transcripts/**`, `artifacts/**`, `previous/**`, optional `audio/**`).
 - S3 audio downloads use `pipeline.spool.root` for active downloads and `pipeline.cache.root` for reusable cached audio when `pipeline.cache.s3_audio` is true.
+- `pipeline.cache.root` is durable local cache state. It is not workspace state and is preserved by default by `narratio clean`.
 
 ## 7. Full campaign reference
 

docs/internal/workspace.md

@@ -46,7 +46,10 @@ None directly in this subsystem. Stages may use object storage adapters and then
 - During each run, stage outputs are often written run-local first (`runs/{run_id}/{stage}/outputs/...`) and promoted to canonical session paths after stage success.
 - `manifest.Artifacts` entries record `ProducerRunID` for durable outputs.
 - For S3 audio sessions, `prepare` records work/cache paths, S3 provenance, and spool path when the invocation downloaded the object.
-- Durable cache state under `pipeline.cache.root` is not workspace state and is not part of session cleanup semantics.
+- Durable cache state under `pipeline.cache.root` is not workspace state and is preserved by default by `narratio clean`.
+- `narratio clean --session-id <id>` removes the session work root and session spool root.
+- `narratio clean --all` removes all local session work under `workspace.root/work` and spool children under `spool.root`.
+- `narratio clean --clear-cache` is the explicit opt-in for deleting matching S3 audio cache entries.
 
 ## Skip and Resume Behavior
 - Skip/resume decisions are made in `internal/app` (`run_control.go`, `resume.go`) using stage status in the session manifest.
@@ -70,4 +73,5 @@ None directly in this subsystem. Stages may use object storage adapters and then
 - Run roots are always nested: `runs/{run_id}` under the session root.
 - Run-local output promotion must end in canonical session paths.
 - `previous/**` is session-durable state and must not be treated as run-local output scratch state.
-- Cleanup only targets run-scoped directories and must never delete configured root directories.
+- Automatic post-archive cleanup only targets run-scoped directories and must never delete configured root directories.
+- Manual `clean` may delete session-scoped directories or the `workspace.root/work` directory, but it must preserve configured root directories and reject unsafe targets.

docs/operations.md

@@ -68,6 +68,16 @@ Restore default scope:
 - includes `audio/**` only with `--include-audio`
 - excludes `runs/**`, `logs/**`, `reports/**`, `config/**`, `inputs/**`, and `current/**` (except remote `current/manifest.json` as source)
 
+Reset local state before restore testing:
+
+```bash
+narratio clean --session-id 2026-04-04 --dry-run
+narratio clean --session-id 2026-04-04
+narratio restore --session-id 2026-04-04 --include-audio
+```
+
+`clean` removes the local session work directory and session spool directory. It preserves the durable S3 audio cache by default, so repeated restore or forced prepare tests do not re-download large audio files.
+
 ## Local filesystem layout and state artifacts
 
 Session root:
@@ -183,13 +193,19 @@ Safe rerun pattern:
 
 ## Cleanup behavior
 
-Cleanup is considered only when archive stage executed and succeeded.
+Automatic post-archive cleanup is considered only when archive stage executed and succeeded.
 
-Cleanup toggles:
+Automatic cleanup toggles:
 - `pipeline.spool.delete_audio_after_archive=true` deletes run-scoped spool audio.
 - `pipeline.workspace.cleanup_after_archive=true` deletes run-scoped local run directory.
 
-The S3 audio cache under `pipeline.cache.root` is durable input cache state, not workspace or spool state. Cleanup does not delete it.
+Manual cleanup:
+- `narratio clean --session-id <id>` deletes `{workspace.root}/work/{campaign}/{session_id}` and `{spool.root}/{campaign}/{session_id}`.
+- `narratio clean --all` deletes all local session work under `{workspace.root}/work` and all spool children under `{spool.root}`.
+- `--dry-run` prints targets without deleting.
+- `--clear-cache` also removes matching S3 audio cache files. Without it, cache is preserved.
+
+The S3 audio cache under `pipeline.cache.root` is durable input cache state, not workspace or spool state. Automatic cleanup and default manual cleanup do not delete it.
 
 Cleanup eligibility gates:
 - archive enabled