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

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.