Implemented shared S3 audio caching for prepare and restore --include-audio

docs/cli.md

@@ -376,6 +376,8 @@ Common failure cases:
 - local conflicts without `--force`.
 - session lock conflict.
 
+When `--include-audio` is set, S3 audio files are restored through the shared audio cache. Cache hits avoid re-downloading large audio objects.
+
 ## Common Workflows
 
 Default-discovery run:

docs/config.md

@@ -165,6 +165,10 @@ spool:
   root: /var/spool/narratio
   delete_audio_after_archive: true
 
+cache:
+  root: /var/cache/narratio
+  s3_audio: true
+
 archive:
   enabled: true
   upload_run: true
@@ -261,6 +265,8 @@ Operational notes:
 | `pipeline.storage.s3.secret_access_key_env` | string | No | `OBJECT_STORAGE_KEY` |
 | `pipeline.spool.root` | string | No | `/var/spool/narratio` |
 | `pipeline.spool.delete_audio_after_archive` | bool | No | `false` |
+| `pipeline.cache.root` | string | No | `/var/cache/narratio` |
+| `pipeline.cache.s3_audio` | bool | No | `true` |
 | `pipeline.archive.enabled` | bool | No | `true` |
 | `pipeline.archive.upload_run` | bool | No | `true` |
 | `pipeline.archive.promote_artifacts[]` | list | No | trimmed transcript rule |
@@ -401,6 +407,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.
 
 ## 7. Full campaign reference
 

docs/internal/command-restore.md

@@ -34,6 +34,8 @@ Does not own:
 - `pipeline.workspace.root` (local restore target root).
 - `pipeline.storage.*` (remote backend + archive identity derivation).
 - `pipeline.storage.s3.*` identity components used by archive prefix helpers.
+- `pipeline.spool.root` for active audio downloads.
+- `pipeline.cache.root` and `pipeline.cache.s3_audio` for reusable S3 audio cache.
 - `session.session_id`
 - `session.campaign`
 
@@ -48,6 +50,7 @@ Does not own:
   - `current/run_id.txt` must exist and be non-empty.
   - `current/manifest.json` must decode and match requested session/campaign.
 - Non-dry-run writes restore files to canonical session paths.
+- With `--include-audio`, restore uses the shared S3 audio cache for `audio/**` objects. Cache hits avoid object downloads; cache misses download through spool, install the work file, and populate cache.
 - Manifest install behavior:
   - validated before replacement.
   - installed last among download actions.
@@ -72,6 +75,7 @@ Restore path scope:
 ## Skip and resume behavior
 - Restore does not participate in stage skip/resume decisions.
 - Restore provides durable local state so subsequent stage commands can resume or rerun based on restored manifest state.
+- Audio cache is outside the workspace and is reused across restore and prepare invocations.
 - Dry-run is read-only and returns plan output only.
 
 ## Failure behavior

docs/internal/stage-prepare.md

@@ -55,6 +55,8 @@ Does not own:
 - `session.inputs.audio_s3.prefix`
 - `pipeline.workspace.root`
 - `pipeline.spool.root`
+- `pipeline.cache.root`
+- `pipeline.cache.s3_audio`
 - `pipeline.storage.s3.bucket`
 - `pipeline.storage.s3.root_prefix`
 - `pipeline.scriptorium.artifacts.<name>.enabled`
@@ -73,6 +75,7 @@ Does not own:
 ## State and manifest behavior
 - Ensures workspace layout exists.
 - Materializes canonical input files and audio files.
+- For S3 audio, uses run-scoped spool for active downloads and durable cache for reusable audio files; cache hits copy directly to work audio without downloading the object again.
 - Records `inputs/session.yml` provenance as local `session_config` or remote `session_config.s3`.
 - Resolves campaign-provided stable input paths relative to `campaign.yml`.
 - Resolves session-provided stable input overrides relative to `session.yml`.
@@ -86,6 +89,7 @@ Does not own:
   - records hydrated previous inputs in `manifest.Inputs` with source `previous_session_archive.current`.
 - If no canonical previous-session requirements exist, prepare does not manage `previous/`.
 - `manifest.Inputs` is sorted deterministically by `(kind, path)`.
+- S3 audio `manifest.Inputs` retain S3 provenance and include `cache_path`; `spool_path` is present only when the current prepare invocation downloaded the file.
 
 ## Required and optional previous-session behavior
 - `previous_session_id` unset:

docs/internal/workspace.md

@@ -32,6 +32,8 @@ Does not own:
 - `pipeline.workspace.cleanup_after_archive`
 - `pipeline.spool.root`
 - `pipeline.spool.delete_audio_after_archive`
+- `pipeline.cache.root`
+- `pipeline.cache.s3_audio`
 - `session.campaign`
 - `session.session_id`
 
@@ -43,7 +45,8 @@ None directly in this subsystem. Stages may use object storage adapters and then
 - Invocation history is persisted per run in run manifests under `runs/{run_id}/manifest.json`.
 - 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 spool/work paths and S3 provenance in `manifest.Inputs`.
+- 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.
 
 ## Skip and Resume Behavior
 - Skip/resume decisions are made in `internal/app` (`run_control.go`, `resume.go`) using stage status in the session manifest.

docs/operations.md

@@ -189,6 +189,8 @@ 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.
+
 Cleanup eligibility gates:
 - archive enabled
 - archive run upload enabled