Close out the completed audit

.woodpecker/release.yml

@@ -2,8 +2,33 @@ when:
   - event: tag
 
 steps:
-  - name: build-release-assets
+  validate:
     image: golang:1.25
+    commands:
+      - go test ./...
+      - go test -race ./...
+      - go vet ./...
+      - go build ./...
+      - go test ./internal/doccheck
+      - go test ./internal/config -run '^TestExamplesLoadAndValidate$'
+
+  cross-build:
+    image: golang:1.25
+    depends_on: validate
+    commands:
+      - |
+        set -eu
+        output_dir="$(mktemp -d)"
+        trap 'rm -rf "$output_dir"' EXIT
+        for target in linux/amd64 linux/arm64 darwin/amd64 darwin/arm64 windows/amd64 windows/arm64; do
+          goos="${target%/*}"
+          goarch="${target#*/}"
+          CGO_ENABLED=0 GOOS="$goos" GOARCH="$goarch" go build -o "$output_dir/narratio-$goos-$goarch" ./cmd/narratio
+        done
+
+  build-release-assets:
+    image: golang:1.25
+    depends_on: [validate, cross-build]
     commands:
       - |
         set -eu
@@ -33,7 +58,7 @@ steps:
         build_binary windows amd64 ".exe"
         build_binary windows arm64 ".exe"
 
-  - name: publish-release
+  publish-release:
     image: woodpeckerci/plugin-release
     depends_on:
       - build-release-assets

.woodpecker/shuffle.yml

@@ -0,0 +1,8 @@
+when:
+  - event: cron
+
+steps:
+  shuffled-race-tests:
+    image: golang:1.25
+    commands:
+      - go test -race -shuffle=on -count=3 ./...

.woodpecker/verify.yml

@@ -0,0 +1,47 @@
+when:
+  - event: [push, pull_request]
+
+steps:
+  tests:
+    image: golang:1.25
+    commands:
+      - go test ./...
+
+  race-tests:
+    image: golang:1.25
+    depends_on: tests
+    commands:
+      - go test -race ./...
+
+  static-analysis:
+    image: golang:1.25
+    depends_on: tests
+    commands:
+      - go vet ./...
+
+  build:
+    image: golang:1.25
+    depends_on: tests
+    commands:
+      - go build ./...
+
+  documentation-and-examples:
+    image: golang:1.25
+    depends_on: tests
+    commands:
+      - go test ./internal/doccheck
+      - go test ./internal/config -run '^TestExamplesLoadAndValidate$'
+
+  cross-build:
+    image: golang:1.25
+    depends_on: [race-tests, static-analysis, build, documentation-and-examples]
+    commands:
+      - |
+        set -eu
+        output_dir="$(mktemp -d)"
+        trap 'rm -rf "$output_dir"' EXIT
+        for target in linux/amd64 linux/arm64 darwin/amd64 darwin/arm64 windows/amd64 windows/arm64; do
+          goos="${target%/*}"
+          goarch="${target#*/}"
+          CGO_ENABLED=0 GOOS="$goos" GOARCH="$goarch" go build -o "$output_dir/narratio-$goos-$goarch" ./cmd/narratio
+        done

docs/cli.md

@@ -47,7 +47,11 @@ Rules:
 - `--campaign` and `--campaign-file` are mutually exclusive.
 - `--session` is not used by `session init`.
 - if both positional `<session_id>` and `--session-id` are provided, values must match.
+- `--previous-session-id` is a strict expectation: the selected session file
+  must contain the same `previous_session_id`.
 - `clean --all` cannot be combined with campaign/session selectors.
+- notification delivery is currently limited to the configured `noop` mode; see
+  the [configuration reference](./config.md#notifications).
 
 ## Session ID Input Rules
 
@@ -168,7 +172,8 @@ Read-only preflight checks for config validity, required inputs, audio mode, pre
 narratio session status <session_id> [...common config flags]
 ```
 
-Prints local manifest state and, when storage is available, remote current-state and published-output status.
+Prints local manifest state and, when storage is available, status for the
+pointer-selected remote commit and its declared published outputs.
 
 ### `session init`
 
@@ -211,7 +216,8 @@ Behavior:
 - discovers committed remote current state;
 - plans local restores;
 - writes an execution report;
-- blocks conflicting overwrites unless `--force` is set.
+- blocks unresolved conflicts. `--force` permits replacement only of eligible
+  regular files.
 
 See [Operations: Restore Workflow](./operations.md#restore-workflow) for the
 default restore scope, report location, and conflict-handling workflow.

docs/config.md

@@ -38,9 +38,25 @@ If local session discovery fails and a `session_id` is known, Narratio attempts
 
 using configured object storage.
 
+The downloaded remote session file is command-scoped: Narratio removes it after
+the command finishes and records only the remote object provenance alongside
+the durable copied session input.
+
+### Identity segments
+
+Campaign IDs (`campaign_id` and `default_campaign_id`), session IDs, previous
+session IDs, and Narratio run IDs are opaque portable segments. They must use
+only ASCII letters, digits, `.`, `_`, and `-`; empty values, `.`/`..`, path
+separators, drive forms, whitespace, control characters, and non-ASCII text are
+rejected. Narratio does not trim or rewrite these values. Existing manifests or
+remote state with an unsafe legacy identity must be migrated before use.
+
 ## Validation and Merge Rules
 
-- YAML decode is strict (`KnownFields(true)`): unknown fields fail load.
+- YAML decode is strict (`KnownFields(true)`) and accepts exactly one document:
+  unknown fields or trailing documents fail load.
+- Configured timeout and retry-delay durations must be positive. An omitted
+  artifact timeout continues to inherit its configured Scriptorium timeout.
 - Session files must be concrete; unresolved `{{ ... }}` placeholders fail load.
 - Pipeline defaults are applied before validation.
 - Campaign and session identities must agree.
@@ -85,7 +101,13 @@ inputs:
 
 - Do not place raw secrets in YAML.
 - Use env var names in config (for example `pipeline.audita.llm_api_key_env`).
-- Optionally load env files from `pipeline.secrets.env_dir`.
+- Optionally load credential files from `pipeline.secrets.env_dir`. Each valid
+  environment-variable filename supplies one value; trailing CR/LF is removed.
+- An existing process environment value takes precedence over a credential file.
+- Credential directories and files must not be symlinks and must be regular,
+  bounded files (at most 8 KiB per value). On POSIX, provision the directory
+  with no group/other access (normally `0700`) and files with no group/other
+  access (normally `0600`).
 - Commands that need storage/auth load filesystem secrets before constructing adapters.
 
 ## Publish Configuration Summary
@@ -135,8 +157,8 @@ Rules:
 | `pipeline.campaigns.root` | string | No | `/usr/local/share/narratio/campaigns` |
 | `pipeline.campaigns.default_campaign_id` | string | No | empty |
 | `pipeline.secrets.env_dir` | string | No | empty |
-| `pipeline.storage.backend` | string | No | empty |
-| `pipeline.storage.s3.bucket` | string | Conditional | required for S3 session-audio and for publish upload when backend is `s3` |
+| `pipeline.storage.backend` | string | No | `local`; supported values are `local` and `s3` (case-insensitive) |
+| `pipeline.storage.s3.bucket` | string | Conditional | required when backend is `s3` and S3 session-audio or publish upload is enabled |
 | `pipeline.storage.s3.root_prefix` | string | No | `dnd` |
 | `pipeline.storage.s3.region` | string | No | empty |
 | `pipeline.storage.s3.endpoint` | string | No | empty |
@@ -156,7 +178,7 @@ Rules:
 | `pipeline.publish.locks[]` | list | No | empty |
 | `pipeline.publish.locks[].source` | string | Yes (per lock) | must reference supported publish source |
 | `pipeline.publish.locks[].reason` | string | No | empty |
-| `pipeline.whisperx.transcribe_url` | string | Yes | valid URL |
+| `pipeline.whisperx.transcribe_url` | string | Yes | absolute `http` or `https` URL |
 | `pipeline.whisperx.language` | string | No | `en` |
 | `pipeline.whisperx.timeout` | duration | No | `30m` |
 | `pipeline.whisperx.retries` | int | No | `3` |
@@ -217,9 +239,7 @@ Rules:
 | `pipeline.scriptorium.timeout` | duration | No | `10m` |
 | `pipeline.scriptorium.render_debug` | bool | No | `false` |
 | `pipeline.scriptorium.artifacts` | map | No | empty |
-| `pipeline.notification.backend` | string | No | empty |
-| `pipeline.notification.recipient` | string | No | empty |
-| `pipeline.notification.timeout` | duration | No | empty |
+| `pipeline.notification.mode` | string | No | `noop`; the only supported notification mode until a provider is implemented |
 
 ### Notarius Output Entries
 
@@ -259,20 +279,39 @@ For each `pipeline.scriptorium.artifacts.<name>`:
 
 Narratio adds `session_id=narratio-session-<session_id>` to every Scriptorium request for sticky upstream LLM routing. If an artifact config sets `vars.session_id`, Narratio replaces that value before invoking Scriptorium. Use a different variable name if a prompt needs the raw Narratio session ID as content.
 
+Without `--artifacts`, analyze executes enabled configured artifacts. With an
+explicit `--artifacts` list, the exact named configured artifacts are the
+one-invocation execution set even if their `enabled` values are false; the list
+does not automatically include dependencies. Named artifacts must therefore be
+configured with valid executable fields, and their configured dependencies must
+already be available to analyze. This override affects analyze planning only;
+publish uses the list only to filter configured
+`narratio.artifact.<name>` output rules.
+
 For each artifact input `pipeline.scriptorium.artifacts.<name>.inputs.<input_name>`:
 
 | Field | Type | Required | Rule |
 | --- | --- | --- | --- |
 | `source` | string | Yes | built-in runtime source, prepared input source, `narratio.extraction.<name>`, `narratio.artifact.<name>`, or `narratio.previous_session.artifact.<name>` |
-| `artifact` | string | No | optional passthrough adapter field |
-| `path` | string | No | optional passthrough adapter field |
 | `required` | bool | No | optional input requirement |
 
+`artifact` and `path` are obsolete and rejected by strict configuration
+loading. Use the canonical `source` identifier to select the input; Narratio
+does not provide adapter-specific input passthrough fields.
+
+### Notifications
+
+Narratio currently supports only `notification.mode: noop`, which is also the
+default when the section is omitted. The notify stage performs no delivery in
+this mode. Backend, recipient, timeout, and other provider settings are
+rejected by strict configuration loading until Narratio has a provider
+integration.
+
 ### Campaign
 
 | Field | Type | Required | Notes |
 | --- | --- | --- | --- |
-| `campaign_id` | string | Yes | canonical campaign identity |
+| `campaign_id` | string | Yes | canonical opaque campaign identity |
 | `session_template_file` | string | No | used by `session init` when set |
 | `inputs.speakers_file` | string | Yes | stable input default |
 | `inputs.autocorrect_file` | string | Yes | stable input default |
@@ -284,9 +323,9 @@ For each artifact input `pipeline.scriptorium.artifacts.<name>.inputs.<input_nam
 
 | Field | Type | Required in session file | Notes |
 | --- | --- | --- | --- |
-| `session_id` | string | Yes | must match CLI session target when provided |
-| `previous_session_id` | string | No | must not equal `session_id` |
-| `campaign` | string | No | filled from `campaign_id` during resolve if omitted |
+| `session_id` | string | Yes | opaque identity; must match CLI session target when provided |
+| `previous_session_id` | string | No | opaque identity; must not equal `session_id` |
+| `campaign` | string | No | opaque identity; filled from `campaign_id` during resolve if omitted |
 | `date` | string | No | metadata |
 | `title` | string | No | metadata |
 | `inputs.speakers_file` | string | No | overrides campaign stable input |
@@ -301,6 +340,20 @@ For each artifact input `pipeline.scriptorium.artifacts.<name>.inputs.<input_nam
 Audio rules:
 
 - configure local mode (`audio_dir` or `audio_files`) or S3 mode (`audio_s3.prefix`), not both.
+- `audio_s3` requires `pipeline.storage.backend: s3` and a configured S3 bucket.
+
+### Storage backend selection
+
+`local` is the default and disables remote object-store operations. Configure
+`s3` explicitly before supplying `storage.s3`; a populated S3 block does not
+select a backend on its own. Unknown backend names and an S3 block paired with
+`local` are rejected during configuration validation.
+
+### Previous-session expectation
+
+`previous_session_id` is optional in a session file. When a command supplies
+`--previous-session-id`, however, the session file must contain the same value;
+an omitted or different value is rejected before the command performs work.
 
 ## Maintained Examples
 

docs/development.md

@@ -25,19 +25,34 @@ polished transcripts and generated artifacts. Start with the
 | Adapters or external tool contracts | [Adapter Internals](internal/adapters.md) and [Integration Contracts](integrations/README.md) | The internal guide owns adapter composition and mechanics; integration documents own external formats and protocols. |
 | Manifests, artifacts, workspace paths, or publish behavior | [Manifest Internals](internal/manifest.md), [Artifact Internals](internal/artifacts.md), [Workspace Internals](internal/workspace.md), [Publish Internals](internal/stage-publish.md), and [Operations](operations.md) | These separate implementation state and resolution from operator-visible layout and lifecycle. |
 | Maintained configuration or input examples | [Configuration](config.md) and [Examples](../examples/README.md) | The reference owns field meanings; the examples directory owns complete copyable files. |
-| Proposed or unimplemented behavior | [Roadmap](roadmap/) | Future work belongs only in roadmap documentation until implemented. |
+| Proposed or unimplemented behavior | `docs/roadmap/` | Future work belongs only in roadmap documentation until implemented. |
 
 For an existing subsystem, also inspect its focused tests and package-level
 contracts before changing behavior.
 
 ## Validation
 
-Use focused package tests while iterating. Run the repository-wide checks when a
-change affects shared contracts, application behavior, or maintained
-documentation examples:
+Use focused package tests while iterating. Every pull request and push runs the
+following repository-wide checks before it can be accepted:
 
 ```sh
 go test ./...
+go test -race ./...
 go vet ./...
-go build ./cmd/narratio
+go build ./...
+go test ./internal/doccheck
+go test ./internal/config -run '^TestExamplesLoadAndValidate$'
 ```
+
+The documentation check verifies local Markdown links and the dependency graph
+of the Woodpecker workflows. The configuration check loads every maintained
+pipeline and session example. Release automation repeats these checks and
+cross-compiles the CLI before it builds release assets; publishing depends on
+that validation path, so a failure cannot publish a release.
+
+Woodpecker also runs `go test -race -shuffle=on -count=3 ./...` on its scheduled
+job to expose ordering and repeatability defects. Current runners cross-compile
+for macOS and Windows, but do not provide native macOS or Windows execution.
+Those cross-builds establish compilation only, not platform-equivalent runtime
+evidence. Add native checks only when official runner labels and successful
+native-run evidence are available.

docs/integrations/audita.md

@@ -15,7 +15,12 @@ runner composition is documented in
 - required transcript/glossary/output/work-dir paths;
 - optional report path (required when report mode is enabled);
 - generated config and stdout/stderr log paths;
-- optional module/model/base-url/config/output-schema/concurrency settings.
+- optional per-invocation module override.
+
+The constructed runner owns static Audita settings: binary, timeout,
+credentials, default modules, model and endpoint settings, validation and output
+settings, report mode, and concurrency. The `polish` stage supplies only
+invocation-specific paths and may override modules for that invocation.
 
 ## Result Contract
 `PolishResult` returns:
@@ -41,6 +46,9 @@ Run fails for:
 - invalid processed transcript JSON (`segments` array required);
 - invalid report JSON when reporting is enabled.
 
+Processed transcript JSON is limited to 64 MiB and optional report JSON to 16
+MiB. Both must be regular files without symlinked path components.
+
 Failure results still include output/log/config/exit metadata for diagnostics.
 
 ## Deterministic Behavior

docs/integrations/notarius.md

@@ -33,8 +33,8 @@ Standard output is reserved for the JSON receipt. Standard error is captured
 separately as diagnostic output. Narratio applies the configured timeout and
 does not interpret stdout as a receipt unless the subprocess exits successfully.
 It does not pass a Narratio session ID or run `notarius config validate`
-automatically; the configured working directory and inherited environment
-apply to the subprocess.
+automatically; the configured working directory and Narratio's minimal child
+environment apply to the subprocess.
 
 ## Accepted Result
 

docs/integrations/scriptorium.md

@@ -46,6 +46,9 @@ Run behavior:
 - `run` exit code `2` is mapped to `ValidationFailed=true`;
 - successful subprocess still fails if output file is missing or empty.
 
+Each artifact result is limited to 64 MiB and must be a regular file without
+symlinked path components.
+
 Render behavior:
 - subprocess errors propagate;
 - output file must exist and be non-empty.

docs/integrations/seriatim.md

@@ -41,6 +41,8 @@ Invocation fails on:
 - empty render output files.
 
 When report paths are provided/enabled, report files must parse as JSON.
+Each Seriatim JSON or rendered-text result is limited to 64 MiB and must be a
+regular file without symlinked path components.
 
 ## Deterministic Behavior
 - argument ordering is deterministic per command construction.

docs/integrations/whisperx.md

@@ -17,6 +17,11 @@ Narratio sends an HTTP `POST` to the configured transcription URL using
 The server must return a `2xx` response whose body is valid JSON. Narratio does
 not currently require a more specific response schema at this boundary.
 
+The transcription URL must be an absolute `http` or `https` URL. The audio body
+is streamed through a fresh multipart writer for every attempt, so its memory
+use is bounded by the transport buffer rather than by the complete audio file.
+WhisperX response acquisition is capped at 10 MiB.
+
 ## Request And Result Contract
 
 Each adapter request identifies a speaker, a readable audio file, and the
@@ -40,7 +45,7 @@ transcript output.
 
 ## Validation And Failure Semantics
 
-Client construction rejects a missing or invalid absolute transcription URL,
+Client construction rejects a missing or non-HTTP(S) absolute transcription URL,
 a missing language, a non-positive timeout, negative retries, or a negative
 retry delay. A request fails before transmission when its audio or output path
 is missing.

docs/internal/adapters.md

@@ -56,6 +56,18 @@ configured filesystem secrets before adapter initialization.
 - Constructor errors fail stage execution setup early.
 - Runtime adapter errors propagate to stage code and then manifest failure handling.
 - Subprocess adapters persist stage logs/generated configs through stage-managed paths.
+- Shared subprocess execution starts an owned process group on Linux/macOS or a
+  kill-on-close job object on Windows. Every terminal path disposes of that
+  owned tree before returning. After a natural leader exit, Unix checks for
+  remaining group members and uses bounded graceful then forceful termination;
+  Windows closes the job so kill-on-close applies. Cancellation, deadlines, and
+  diagnostic limits use the same terminal disposal path without losing their
+  original result classification. Child environments contain only the execution
+  baseline and adapter-specified values; configured credentials are explicit
+  sensitive values. Stdout and stderr are redacted while streaming into separate
+  8 MiB diagnostic captures; a bounded wait closes a stream retained by a
+  departed leader's descendant. Unsupported platforms reject owned command
+  execution.
 
 ## Implementation And Tests
 

docs/internal/artifacts.md

@@ -30,19 +30,30 @@ and content validator. The focused stage documents own their input/output flow;
 - extraction source ID format: `narratio.extraction.<output_key>`
 - previous-session source ID format: `narratio.previous_session.artifact.<artifact_key>`
 
-All formats are validated by strict source-policy rules. Extraction sources are
-registered only from `pipeline.notarius.outputs`; the Notarius index has no
-selectable source ID.
+All formats are validated by strict source-policy rules. Configured artifact and
+extraction keys use `^[a-z][a-z0-9_]*$`; source parsers never normalize an
+unrecognized token into a valid source. Extraction sources are registered only
+from `pipeline.notarius.outputs`; the Notarius index has no selectable source
+ID.
 
 ## Runtime Catalog
 
 `ArtifactCatalog` tracks:
 
 - `planned`: source registered for run context;
-- `executable`: selected and enabled for analyze execution;
+- `executable`: included in the effective analyze artifact set;
 - `available`: local file exists and validates;
 - `provenance`: availability source.
 
+Configured definitions are always registered. Without an explicit selection,
+the effective analyze set contains enabled definitions. With `--artifacts`, the
+exact named configured definitions become the effective set for that invocation,
+regardless of their `enabled` value; dependencies are not added implicitly.
+Availability is separate from executability: a non-executable configured output
+may be reused from a canonical non-empty file, while an executable definition
+is generated by analyze. Extraction entries are registered from configuration
+and become available only after compatible extraction evidence is hydrated.
+
 Current provenance values:
 
 - `generated.current_analyze_run`
@@ -63,11 +74,14 @@ Configured sources (`narratio.artifact.*`):
 
 Extraction sources (`narratio.extraction.*`):
 
-- use the shared registration and manifest hydration path in
-  `extraction_catalog.go`;
+- use the shared typed bundle evidence inspection in `extraction_evidence.go`;
 - require a current successful extract record with the exact configured source,
   compatible contract and Notarius provenance, a confined regular durable
-  payload, and matching checksum; and
+  payload, matching checksum, and the current resolved trimmed-transcript
+  identity;
+- remain unavailable unless catalog hydration receives valid evidence. Resume
+  treats absent or obsolete evidence as a rerun decision and unsafe evidence as
+  an error; and
 - are never inferred by scanning the Notarius bundle directory.
 
 Previous-session sources (`narratio.previous_session.artifact.*`):
@@ -76,6 +90,10 @@ Previous-session sources (`narratio.previous_session.artifact.*`):
 - prefer manifest-backed previous-input paths;
 - fallback to existing previous-cache filesystem paths.
 
+Source absence is evaluated by the consuming artifact input. An optional input
+is omitted from that invocation; a required input fails resolution. This is
+separate from a stage's lifecycle outcome.
+
 Validation by content type:
 
 - transcript JSON built-ins: JSON with top-level `segments` array;
@@ -87,7 +105,7 @@ Validation by content type:
 
 `CollectPreviousArtifactRequirements`:
 
-- scans enabled configured artifacts only;
+- scans the effective configured artifact set;
 - extracts only canonical previous-session sources;
 - deduplicates by artifact key;
 - merges required and optional references (required wins);
@@ -98,12 +116,31 @@ Validation by content type:
 Artifacts package owns shared remote current-state loading mechanics used by
 restore, status and validation checks, and previous-cache planning.
 
+For a new-protocol current state, the pointer-selected immutable commit is the
+complete restore authority. Callers receive its declared object identities and
+must not supplement them by listing mutable session prefixes. The legacy reader
+is intentionally separate and remains migration-only support.
+
+The reader opens each small control object directly and enforces owner-specific
+limits before decoding: 64 KiB for the mutable commit pointer, 4 MiB for the
+immutable commit manifest, and 8 MiB for the selected session manifest. Legacy
+compatibility applies a 4 KiB limit to `current/run_id.txt` and the same 8 MiB
+manifest limit to `current/manifest.json`. These are exposed as
+`MaxCurrentCommitPointerBytes`, `MaxRemoteCommitManifestBytes`,
+`MaxRemoteSessionManifestBytes`, `MaxLegacyCurrentRunPointerBytes`, and
+`MaxLegacyCurrentManifestBytes`.
+
+Each read uses the generation and size metadata returned with its opened body.
+Actual bytes remain subject to a limit-plus-one read even if size metadata is
+absent or inaccurate. Immutable selections then retain their declared-size,
+checksum, generation, and identity checks. No current-state control object is
+downloaded through a temporary file.
+
 Core helpers:
 
-- `LoadCurrentRunPointer`
-- `LoadCurrentManifest`
 - `LoadCurrentState`
 - `ValidateCurrentStateIdentity`
+- `RemoteCommitManifest` and `CurrentCommitPointer`
 
 Typed missing-state errors:
 
@@ -131,6 +168,18 @@ Caller policy is intentionally outside artifacts helpers:
 - spool/cache paths;
 - S3 session/run/current-state key layout.
 
+New publication creates run-scoped immutable objects, including
+`runs/{run_id}/commit.json` and `runs/{run_id}/session-manifest.json`. The sole
+mutable selector is `current/commit-pointer.json`; readers verify its selected
+commit and declared object generations/checksums. Legacy current-pair loading
+is confined to `current_state_legacy.go` for migration only.
+
+Campaign, session, and Narratio run IDs are validated as portable opaque
+segments at configuration and artifact boundaries before they can be used in a
+workspace or S3 namespace. Previous-artifact destinations remain typed,
+multi-segment relative paths and are confined beneath `previous/artifacts`; they
+are not treated as opaque identifiers.
+
 See [Workspace Internals](workspace.md) for how callers consume local helpers
 and [Operations](../operations.md#local-state-layout) for the authoritative
 physical layout.
@@ -148,8 +197,12 @@ physical layout.
 
 - Registry and resolution: `internal/artifacts/artifact_resolver.go`,
   `internal/artifacts/catalog.go`, `internal/artifacts/transcripts.go`,
-  `internal/artifacts/extraction_catalog.go`
-- Current state: `internal/artifacts/current_state.go`
+  `internal/artifacts/extraction_catalog.go`,
+  `internal/artifacts/extraction_evidence.go`,
+  `internal/artifacts/extraction_input.go`
+- Current state: `internal/artifacts/current_state.go`,
+  `internal/artifacts/current_state_commit.go`,
+  `internal/artifacts/current_state_legacy.go`
 - Paths and keys: `internal/artifacts/paths.go`,
   `internal/artifacts/s3_keys.go`
 - Previous requirements: `internal/artifacts/previous_requirements.go`

docs/internal/command-restore.md

@@ -8,8 +8,8 @@ reporting flow in `internal/app`. User invocation belongs in
 physical restore scope belong in
 [Operations](../operations.md#restore-workflow).
 
-Restore is split into explicit phases so remote authority, local conflict
-policy, and filesystem mutation can be tested independently.
+Restore separates remote authority, local conflict policy, and filesystem
+mutation so each remains testable independently.
 
 ## Discovery Contract
 
@@ -18,6 +18,7 @@ Discovery delegates current-state pointer and manifest loading to
 
 - campaign must match;
 - session ID must match.
+- run ID must match the pointer-selected committed run.
 
 Restore treats any missing or invalid remote current state as a command error.
 
@@ -31,13 +32,20 @@ Restore planner action kinds:
 
 Planner behavior:
 
-- remote list scope is the resolved session prefix;
+- a new-protocol restore uses only the selected commit's declared artifact set;
+  each action carries that artifact's immutable key, checksum, size, and
+  generation. Coherent legacy state remains on the isolated compatibility path;
 - remote-to-local mapping is traversal-safe;
 - actions are sorted by local relative path and then remote key;
-- force converts differing local targets from conflicts to downloads.
+- force converts differing eligible regular files from conflicts to downloads;
+  directories and other non-regular targets remain conflicts.
 
-Previous-cache files are planned separately through `previouscache.BuildPlan`
-when configured previous-session requirements exist.
+For a non-dry-run restore, planning/classification happens only after acquiring
+the session lock. Runner manifest/reuse checks acquire that same lock first.
+
+Previous-cache readiness is resolved through `previouscache.Resolve` for restore,
+prepare, status, and validation. A committed source is selected only by its
+exact source identity; legacy fallback remains isolated and rejects ambiguity.
 
 ## Execution Contract
 
@@ -47,17 +55,32 @@ Execution order and safety:
 - `manifest.json` installs last;
 - downloads use sibling temp files plus atomic rename;
 - manifest replacement is validated before rename;
+- each committed object is verified against its declared checksum, size, and
+  generation before installation;
+- a committed manifest already verified during discovery is retained for the
+  matching restore action and revalidated before installation, avoiding a
+  second body transfer;
 - failed installs do not roll back files already written in the same execution.
+- a durable `.restore-incomplete.json` marker is written before installation.
+  It blocks runners until a restore retry completes all verified installs and
+  the local manifest replacement, at which point it is removed.
+- restored manifest local references are rebased beneath the selected local
+  session root. Unsafe relative references and producer-machine absolute paths
+  outside the manifest's producer session root are rejected; producer-local
+  spool/cache and cleanup locations are not restored as authority.
 
 Audio restore path:
 
 - uses `audio.MaterializeS3Audio`;
 - integrates spool and S3 audio cache paths;
-- supports cache-hit reuse without object redownload.
+- reuses cached audio only when its no-follow regular file, content digest, and
+  identity sidecar all match the selected remote object version; otherwise it
+  refreshes through the durable download path.
 
 ## Reporting Contract
 
-- dry-run mode prints a summary and performs no local writes;
+- dry-run mode prints a summary, performs no durable session writes, and may
+  read remote current-state or object-identity data to produce that summary;
 - execution mode persists the canonical restore report described in
   [Operations](../operations.md#restore-workflow);
 - report includes plan counts, per-action status, and execution failures.
@@ -65,7 +88,13 @@ Audio restore path:
 ## Invariants
 
 - restore uses committed remote current state as authority;
-- `current/run_id.txt` is the remote publish commit marker;
+- one restore or status inspection observes the single pointer-selected commit
+  loaded at discovery; later pointer changes cannot add objects or substitute a
+  different run into its plan;
+- a verified `current/commit-pointer.json` and its selected immutable commit
+  establish new-protocol remote commitment; coherent legacy
+  `current/run_id.txt` plus `current/manifest.json` remains read-only migration
+  support;
 - restore does not execute pipeline stages.
 
 ## Implementation And Tests

docs/internal/fileops.md

@@ -0,0 +1,71 @@
+# Internal: File Operations
+
+`internal/fileops` owns the narrow mechanics for durable replacement of one
+byte file. Callers keep ownership of serialization, validation, cancellation,
+and destination-directory policy.
+
+## Destination Confinement
+
+Before it creates, replaces, or installs a destination file, `fileops` opens
+each ancestor from the filesystem root and rejects symbolic links or components
+that change during traversal. The resulting parent-directory handle is retained
+for sibling temporary-file creation and rename, so a later pathname swap cannot
+redirect the replacement. Existing destination symlinks are replaced as leaf
+entries; their targets are never followed.
+
+Remote object acquisition uses a writer supplied by the storage owner. The
+writer receives a `fileops`-owned, already-open sibling temporary file rather
+than a mutable destination path. Callers still own remote object selection,
+validation, conflict handling, and final mode.
+
+Directory promotion keeps the verified destination parent open while it creates
+the temporary tree, copies regular source entries, and performs the platform
+no-replace rename. Platforms without a verified handle-relative atomic
+no-replace primitive reject promotion before writing a temporary tree.
+
+## Cleanup Contract
+
+`RemoveAllUnderRoot` accepts an explicit root and a proper descendant. It opens
+the root and each target ancestor without following symlinks, then removes the
+tree through those directory handles. It rejects root deletion and any symlink
+encountered in the target path or tree; repeated removal of a missing target is
+successful. Command and post-publish policy remains owned by `internal/app`.
+
+## Confined Reads
+
+`ReadRegularFileUnderRoot` is the no-follow, bounded read primitive for a
+caller-selected root and relative file path; `ReadRegularFile` is its
+path-based convenience wrapper. They verify every ancestor through directory
+handles and admit only a stable regular-file handle. Callers enforce their own
+byte limits and access policy. Credential mode policy and environment
+precedence remain owned by `internal/app`.
+
+## Replacement Contract
+
+`ReplaceFileAtomic` requires an existing destination directory. It creates a
+sibling temporary file, writes the complete byte sequence, applies the
+caller-supplied mode, syncs and closes the file, runs an optional pre-rename
+check, replaces the destination with a rename, then syncs the containing
+directory.
+
+The pre-rename check is the last point at which a caller can cancel without
+installing a new destination. A failure before the rename leaves the old
+destination unchanged and removes the temporary file; any cleanup failure is
+returned alongside the primary failure. A failure after the rename may leave
+the new file visible, but it is not reported as crash-durable.
+
+Replacement follows the operating system's same-filesystem rename semantics.
+If a platform cannot replace an existing destination, the operation returns an
+error and never removes the old file as an emulation step.
+
+## Directory-Sync Support
+
+Linux and macOS attempt to sync the destination directory. Windows opens the
+directory with backup semantics and flushes its buffers. If either operation
+is unavailable for the platform, directory handle, or filesystem,
+`ErrDirectorySyncUnsupported` is returned. Narratio does not treat that result
+as successful crash-durable replacement.
+
+`WriteFileAtomic`, copy helpers, and downloaded temporary-file installation
+retain their compatibility behavior of creating the destination parent with
+the repository's workspace permissions before using this contract.

docs/internal/manifest.md

@@ -16,6 +16,14 @@ Explain the session-progress and invocation-audit models implemented by
 - `inputs` records
 - durable `artifacts` records
 - per-stage `stages` map
+- an optional `post_publish_cleanup` obligation, which binds a committed run,
+  remote commit identity, and each exact root-confined local target to its
+  completion evidence
+
+Session, campaign, and run identities in local and downloaded manifests must be
+portable opaque segments. Unsafe legacy identities are rejected with migration
+guidance rather than being normalized into a different workspace or remote
+namespace.
 
 The model admits these stage states:
 
@@ -37,15 +45,40 @@ The model admits these stage states:
 - per-stage status
 - overall run status (`running`, `succeeded`, `failed`)
 
+## Remote Commit Manifest
+
+`artifacts.RemoteCommitManifest` is a separate, versioned remote snapshot
+contract. It is not a serialized session manifest and contains no local
+post-publication assertion such as `current_pointer_written`. A remote commit
+identifies one campaign, session, and run and declares its immutable artifact
+set. Each artifact has a typed source, immutable destination key, SHA-256
+checksum, size, and storage generation.
+
+`current/commit-pointer.json` is the sole mutable selector for the new
+contract. It identifies exactly one run-scoped `runs/{run_id}/commit.json` and
+binds that object by checksum, size, and generation. Readers strictly reject
+unknown fields, version mismatches, pointer/commit identity mismatches, and
+objects that do not match their declaration.
+
+The reader retains a temporary, clearly isolated compatibility path for a
+coherent legacy `current/manifest.json` plus `current/run_id.txt` pair. That
+path is removable after migration and is never used to write new state.
+
 ## Persistence Semantics
 
 `manifest.LocalStore`:
 
 - validates loaded documents;
 - normalizes missing maps/stage records;
-- writes atomically via temp file + rename;
+- writes through a sibling temporary file, syncing the completed file and
+  destination directory after atomic replacement;
 - updates `updated_at` on save.
 
+If the operating system or filesystem cannot sync a directory, save returns an
+explicit error instead of claiming crash-durable replacement. A returned error
+after the rename can therefore leave the new manifest visible but not confirmed
+durable; callers must reload it before retrying.
+
 ## Execution Semantics
 
 The application runner marks an executing stage running and then succeeded or
@@ -81,6 +114,25 @@ runner marks it stale and executes it.
 Session manifest is the authoritative stage-progress ledger across invocations.
 Run manifest is invocation-scoped audit state.
 
+After a publish commits remotely, any configured local cleanup is first recorded
+as a session-manifest obligation before deletion begins. Each target becomes
+complete only after its confined deletion (or safe absence check) and a
+successful manifest save. An incomplete obligation is retried on later
+invocations independently of their selected stages and retains the committed
+run and remote identity that authorized it.
+
+Each invocation derives campaign, session, run, local-path, and remote-prefix
+metadata from the validated resolved configuration as one projection. A persisted
+session manifest must agree on campaign and session identity before execution;
+the current projection is refreshed for every invocation while stage progress,
+inputs, and durable artifacts remain session history.
+
+For handled failures after an invocation record is created, the runner records
+the failure on the session ledger and persists it before persisting the failed
+run audit record. This preserves the resume authority while making a partial
+persistence disagreement visible. Abrupt process death remains an accepted case
+where a durable running record can require operator interpretation.
+
 ## Invariants
 
 - stage resume/skip decisions are session-manifest driven.
@@ -89,11 +141,16 @@ Run manifest is invocation-scoped audit state.
 - stale stages retain prior details until replacement execution starts.
 - force reruns stale downstream succeeded stages.
 - run manifest does not replace session manifest as progress authority.
+- remote commitment is established by a verified current pointer and remote
+  commit relationship, never by a mutable session-manifest boolean.
 
 ## Implementation And Tests
 
 - Models and transitions: `internal/manifest/manifest.go`,
   `internal/manifest/run_manifest.go`
+- Remote commit model and readers: `internal/artifacts/remote_commit.go`,
+  `internal/artifacts/current_state_commit.go`,
+  `internal/artifacts/current_state_legacy.go`
 - Persistence and validation: `internal/manifest/store.go`
 - Package tests: `internal/manifest/*_test.go`
 - Assembled execution behavior: `internal/app/runner_test.go`,

docs/internal/overview.md

@@ -35,7 +35,7 @@ progress and artifact services resolve durable inputs and outputs.
 | Artifacts and paths | `internal/artifacts`, `internal/pathsafe` | Artifact identities and resolution, local and remote path/key models, current-state discovery, and confined relative destinations. |
 | Previous-session cache | `internal/previouscache` | Deterministic planning and materialization requirements for configured previous-session inputs. |
 | Artifact policy | `internal/artifactpolicy` | Source and destination policy, configured artifact identity validation, and publish destination safety. |
-| Shared models and file operations | `internal/artifactmodel`, `internal/contracts`, `internal/fileops` | Transcript and artifact data contracts plus narrow atomic filesystem helpers. |
+| Shared models and file operations | `internal/artifactmodel`, `internal/contracts`, [`internal/fileops`](fileops.md) | Transcript and artifact data contracts plus durable single-file replacement helpers; unsupported directory syncing is reported explicitly. |
 | Logging | `internal/logging` | Application logger construction and shared structured logging behavior. |
 
 The application boundary composes concrete implementations. Stages depend on
@@ -57,11 +57,11 @@ The implemented canonical order is:
 8. [`render`](stage-render.md)
 9. [`analyze`](stage-analyze.md)
 10. [`publish`](stage-publish.md)
-11. `notify` (placeholder)
+11. `notify` (no-op)
 
-`notify` currently has optional notifier call behavior and no persisted pipeline
-outputs; its default collaborator is a no-op sender. The focused stage
-documents own implementation mechanics. The
+`notify` currently has no persisted pipeline outputs and uses the explicit
+`noop` notification mode. The focused stage documents own implementation
+mechanics. The
 [CLI](../cli.md) and [Operations](../operations.md) own user-visible invocation
 and execution semantics.
 

docs/internal/stage-analyze.md

@@ -8,13 +8,15 @@ Execute selected configured Scriptorium artifacts in dependency order and materi
 
 - configured artifacts from `pipeline.scriptorium.artifacts`
 - optional selected artifact keys supplied through the stage environment
-- built-in/configured/previous-session source references in artifact inputs
+- built-in, configured, extraction, and previous-session source references in
+  artifact inputs
 
 Supported source families:
 - built-ins: `narratio.transcript.*`, `narratio.bounds.session`
 - prepared stable inputs: `narratio.input.players`, `narratio.input.party`,
   `narratio.input.glossary`
 - configured artifacts: `narratio.artifact.<key>`
+- extraction lanes: `narratio.extraction.<key>`
 - previous-session cache: `narratio.previous_session.artifact.<key>`
 
 ## Outputs
@@ -24,11 +26,22 @@ Supported source families:
 
 ## Key Behavior
 
-- skips with metadata when Scriptorium config is missing or no executable artifacts remain.
-- builds runtime artifact catalog (built-ins + configured artifacts).
+- when Scriptorium is absent or no configured artifact is executable, completes
+  successfully with no outputs and records explanatory metadata. This is not an
+  explicit self-skip: both manifests record success, satisfy publish's
+  prerequisite, and an ordinary later run reuses the result until forced.
+- builds a runtime artifact catalog containing built-ins, configured artifacts,
+  and configured extraction lanes. Extraction availability is hydrated only
+  from compatible successful extraction evidence.
+- uses enabled configured artifacts by default. An explicit `--artifacts`
+  selection is a one-invocation override: it makes exactly the named configured
+  artifacts executable even when disabled, and does not automatically include
+  dependencies. A selected artifact's dependencies must instead already be
+  available to the catalog.
 - marks non-executable configured artifacts as reusable when output files already exist.
 - validates selected artifact dependency order (cycle-safe topo ordering).
 - resolves required/optional inputs per artifact source definition.
+- omits an unavailable optional input; an unavailable required input fails.
 - resolves prepared stable input sources from `inputs/*.yml` materialized by `prepare`.
 - resolves previous-session sources from local `previous/` cache only.
 - runs optional render-debug, then artifact execution.

docs/internal/stage-extract.md

@@ -31,7 +31,10 @@ procedures belong in [Operations](../operations.md).
 Lane records retain checksum, contract, producer run ID, and Notarius system,
 run, pipeline, and lane provenance. Stage metadata retains the durable bundle
 root, receipt, diagnostic paths, rejection/warning summaries, producing
-Narratio run ID, and invocation fingerprint. Validation completes before
+Narratio run ID, the resolved trimmed-input identity, and invocation
+fingerprint. The input identity binds the exact transcript bytes, canonical
+source ID, producer stage/output/run identity, and resolution provenance.
+Validation completes before
 promotion, so a rejected result cannot expose a partial durable bundle.
 
 Any executed extraction outcome that replaces a different effective outcome
@@ -43,7 +46,10 @@ with no outputs is stable and does not repeatedly invalidate downstream stages.
 `internal/stage/extract_resume.go` permits a skip only when the existing stage
 record succeeded and still matches the current invocation fingerprint. The
 fingerprint covers the resolved executable and config paths, pipeline ID,
-timeout, working directory, and sorted configured output contracts.
+timeout, working directory, sorted configured output contracts, and the current
+direct trimmed-transcript identity. The same identity is resolved again for
+artifact evidence, so changing the current transcript bytes or producer
+identity makes the prior extraction obsolete.
 
 The validator then checks the producing run identity, canonical immutable
 bundle root, path confinement and absence of symlink components, receipt

docs/internal/stage-polish.md

@@ -17,7 +17,8 @@ Run Audita polishing on base transcript and produce polished transcript.
 ## Key Behavior
 
 - resolves base transcript from merge outputs/canonical fallback.
-- invokes Audita with configured model/module/runtime options.
+- invokes an Audita runner configured with static model/runtime options; the
+  invocation supplies paths and modules.
 - validates processed transcript structure (`segments` array required).
 - validates optional report JSON.
 - materializes canonical outputs; records logs/generated config and adapter metadata.

docs/internal/stage-prepare.md

@@ -30,21 +30,26 @@ Materialize canonical current-session inputs before processing stages.
 
 - validates required config/store state.
 - enforces local audio vs S3 audio mutual exclusivity.
+- rejects duplicate explicit local audio sources after resolution.
+- gives distinct local source paths with the same basename deterministic unique
+  prepared filenames so neither source is overwritten.
 - materializes S3 audio through spool/cache-aware logic.
 - scans enabled configured artifact inputs for `narratio.previous_session.artifact.*` requirements.
-- when previous requirements exist:
-  - clears managed `previous/` state;
-  - builds previous-cache remote plan;
+- clears managed `previous/` state on every invocation, then, when requirements exist:
+  - resolves the pointer-selected previous source through the shared resolver;
   - downloads previous manifest/artifacts;
   - records previous inputs in `manifest.inputs`.
 
-Required previous-session inputs fail when unavailable; optional missing inputs are skipped.
+Required previous-session inputs fail when unavailable; optional missing inputs
+are typed skipped results. Committed sources use their exact source-to-destination
+mapping, while the isolated legacy reader rejects ambiguous fallback matches.
 
 ## Invariants
 
 - only `prepare` hydrates canonical `previous/` cache state.
 - managed previous artifacts are stored under `previous/artifacts/**` without
   duplicate `artifacts/artifacts/` nesting.
+- managed `previous/` state represents only the current requirement set.
 - `manifest.inputs` ordering is deterministic (`kind`, `path`).
 
 ## Related Contracts And Tests

docs/internal/stage-publish.md

@@ -9,34 +9,52 @@ Upload run/session outputs to object storage and atomically advance remote curre
 - successful preceding stages from the [canonical stage set](overview.md#pipeline-stage-set)
 - invocation-scoped run files
 - resolved publish output rules
-- effective publish locks (static + remote merged lock set)
+- effective publish locks (static + remote merged lock set), revalidated at the
+  remote commit boundary
 - durable previous-session cache files when present
 
 ## Outputs
 
 - uploaded invocation record and selected publish outputs;
 - uploaded durable previous-session cache files when present;
-- updated remote current manifest; and
-- remote current-run commit marker, written last.
+- immutable run-scoped commit manifest; and
+- current commit pointer, written last.
 
 Exact remote placement and the operator workflow belong in
 [Operations](../operations.md#publish-workflow).
 
 ## Key Behavior
 
-- stage can self-skip when publish disabled or run upload disabled.
+- when publishing or run upload is disabled, completes successfully with no
+  outputs and records explanatory metadata. This is not an explicit self-skip:
+  both manifests record success, and an ordinary later run reuses that result
+  until publish is forced.
 - validates prerequisite stage success and object-store availability.
-- collects a deterministic run file list plus run `manifest.json`, excluding
-  `audio/**` and the run-local `extract/notarius-output/**` staging bundle.
-- keeps run-local Notarius receipt and stderr diagnostics eligible for the run
-  archive.
+- derives a deterministic run-archive allowlist from the validated run
+  `manifest.json`: declared run-local outputs, logs, generated configs, and the
+  manifest itself. Unlisted workspace files are not archive candidates.
+- opens each archive candidate beneath its archive root without following
+  symlinked ancestors or leaf entries, verifies that it is a regular file and
+  checks a declared checksum when present, then streams the opened descriptor.
+- derives the durable previous-cache archive from its validated manifest using
+  the same confinement and regular-file checks.
 - resolves publish output sources through runtime artifact catalog and manifest-aware resolution.
 - publishes extraction lanes only through explicit configured output rules;
   neither run-local nor durable Notarius bundles are scanned or uploaded wholesale.
 - selected artifact filter applies to configured artifact sources only.
 - locked outputs are skipped intentionally (including required ones).
 - optional missing outputs are skipped; required missing unlocked outputs fail.
-- writes remote current manifest before current run pointer.
+- creates one complete immutable source-to-destination mapping before upload;
+- uploads and verifies every declared immutable object and the commit manifest;
+- updates `current/commit-pointer.json` exactly once, last; and
+- does not write the legacy `current/manifest.json` or `current/run_id.txt` pair.
+- rechecks remote lock state immediately before the pointer update. A newly
+  committed lock aborts selection, leaving any uploaded immutable attempt
+  unselected.
+- reads the mutable remote lock document through a direct limit-plus-one read
+  capped by `MaxRemoteLockStoreBytes` (1 MiB), retaining the generation returned
+  with the opened body for conditional updates. Oversized lock documents fail
+  before YAML decoding; published artifact payloads do not use this limit.
 
 ## Metadata Signals
 
@@ -47,16 +65,23 @@ Includes counts/lists for:
 - skipped optional outputs
 - skipped unselected outputs
 - locked outputs
-- current-state key paths
-- `current_pointer_written`
+- remote commit and current-pointer key paths
+- the run identifier selected by the commit
 
 ## Invariants
 
-- `current/run_id.txt` is the remote commit marker and is written last.
-- run upload excludes `audio/**` and `extract/notarius-output/**`.
-- `extract/notarius.receipt.json` and `extract/notarius.stderr.log` remain
-  eligible run-record diagnostics.
-- publish locks are not overridden by `--force`.
+- `current/commit-pointer.json` is the remote commit marker and is written last.
+- run files, selected outputs, previous-cache files, and the committed session
+  manifest are all declared by an immutable commit under the run prefix.
+- run and previous uploads contain only manifest-declared regular files opened
+  from verified descriptors; symlinks, special files, replacement races, and
+  undeclared entries are rejected or ignored before uploads begin.
+- run-local diagnostics, including Notarius receipt and stderr files, are
+  archived only when recorded by the run manifest.
+- publish locks are not overridden by `--force`; remote locks are revalidated
+  immediately before current-state selection.
+- post-commit local cleanup is authorized by the committed publish metadata and
+  is durably recorded by the application lifecycle before any local deletion.
 
 The commit boundary and cleanup gate are normative architecture invariants; see
 [Architecture](../policy/architecture.md#publish-commit-boundary).

docs/internal/stage-render.md

@@ -20,7 +20,9 @@ Render Markdown transcript artifacts from normalized JSON transcripts via Seriat
 - resolves inputs manifest-first, then canonical fallback.
 - writes run-local outputs first, then materializes canonical session outputs.
 - records input provenance, output paths, adapter metadata, logs, and generated config refs.
-- skips with stage metadata when `pipeline.render.enabled=false`.
+- when `pipeline.render.enabled=false`, completes successfully with no outputs
+  and records explanatory metadata. This is not an explicit self-skip: both
+  manifests record success, and enabling render later requires a forced run.
 
 ## Failure Semantics
 

docs/internal/stage-transcribe.md

@@ -15,16 +15,21 @@ Generate raw per-speaker transcripts from prepared audio using WhisperX.
 ## Key Behavior
 
 - discovers prepared audio from manifest inputs or canonical audio directory.
-- derives speaker ID from `.flac` basename.
+- derives the transcript identity from the prepared `.flac` filename.
 - dispatches WhisperX requests through a bounded worker pool.
 - validates each output as JSON.
-- writes run-local outputs then materializes canonical transcript outputs.
+- writes run-local outputs then materializes canonical transcript outputs only
+  after every planned request succeeds.
 
 ## Invariants
 
-- speaker basenames must be unique.
+- prepared audio identities must be unique; prepare disambiguates distinct
+  source paths that share a basename.
 - output path returned by adapter must match requested output path.
-- each successful output is validated before stage success.
+- an empty adapter result path means the requested path; adapters cannot select
+  an alternate destination.
+- each successful output is validated before stage success, and cancellation or
+  incomplete dispatch cannot be reported as a successful result.
 
 ## Related Contracts And Tests
 

docs/internal/storage.md

@@ -12,14 +12,23 @@ operator-selected storage fields and credential mechanisms belong in
 `storage.ObjectStore` interface:
 
 - `List(ctx, prefix)`
+- `Read(ctx, key)` returns an object body and the generation observed with it
 - `Download(ctx, key, localPath)`
 - `Upload(ctx, localPath, key, opts)`
+- `UploadConditional(ctx, source, key, opts, condition)`
 - `Exists(ctx, key)`
 
 Key invariant:
 - callers pass full bucket-relative keys;
 - storage implementations do not infer campaign/session/run prefixes.
 
+`ReadObjectBounded` is the shared mechanism for small control objects. It opens
+one object version, returns the metadata observed with that body, rejects an
+oversized known size before transfer, and still performs a context-aware
+limit-plus-one read. It closes the body on every exit. Callers own the policy
+limit and add the control-object category to errors; this helper is not used for
+large artifact payloads.
+
 ## Composition
 
 `NewObjectStoreFromConfig` constructs the S3-backed implementation from
@@ -31,13 +40,20 @@ not own discovery, defaults, or configuration validation.
 
 - normalizes object keys.
 - `List` paginates and returns normalized `ObjectInfo`.
+- A truncated S3 listing must supply a new, non-empty continuation token;
+  otherwise listing fails with bucket and prefix context instead of looping.
 - `Download` writes local files with parent directory creation.
 - `Upload` streams local file and returns remote metadata.
+- `Read` binds a returned body to its S3 ETag. `UploadConditional` maps an ETag
+  match or absence precondition directly to the provider request and reports a
+  failed precondition without performing a local check-then-write replacement.
 - `Exists` maps not-found responses to `false`.
 
 ## Invariants
 
 - storage layer is stateless regarding manifest/stage progression.
+- bounded reads never retain more than the caller's limit plus one byte and do
+  not replace owner-specific size policy.
 - publish ordering semantics are owned by stage/app code, not storage adapters.
 
 ## Implementation And Tests

docs/internal/workspace.md

@@ -13,8 +13,16 @@ previous-cache path construction. `SessionPathsFor` provides the session-scoped
 path model, and layout creation goes through `EnsureLayoutFor`. Callers should
 consume those helpers instead of rebuilding relative paths.
 
-`internal/pathsafe` and application cleanup helpers enforce confinement for
-relative destinations and deletion targets.
+`internal/pathsafe` validates relative destinations. `internal/fileops` opens
+cleanup roots and their descendants through no-follow directory handles before
+removing them.
+
+`internal/fileops` owns the ordinary workspace mode contract. On POSIX,
+`WorkspaceDirectoryMode` is setgid `02775` and `WorkspaceFileMode` is `0664`.
+`EnsureWorkspaceDirectory` reapplies the directory mode after creation so a
+restrictive umask cannot remove group access, while retaining existing ownership
+and group. Credential paths are outside this contract; the platform-specific
+operational requirements are in [Operations](../operations.md#workspace-permissions).
 
 ## Run-Local Stage Layout
 
@@ -36,21 +44,30 @@ existing destination. Exact physical paths belong in
 
 ## Locking
 
-`artifacts.LocalStore` enforces the single-writer session lock via `.lock`
-(`ErrLockConflict` on contention).
+`artifacts.LocalStore` enforces the single-writer session lock via an
+operating-system lock held on `.lock` (`ErrLockConflict` on contention). The
+file retains owner metadata after release or process death; its existence is
+not evidence that a lock is active. Command and restore flows wait for this
+lock only while their context remains active, and report a release failure.
 
 ## Cleanup Semantics
 
 Automatic post-publish cleanup:
 
-- only runs when publish actually executed and succeeded;
-- requires `uploaded=true` and `current_pointer_written=true` metadata;
+- is created only after a successful publish commit with complete publish
+  metadata, then is persisted before any deletion;
+- requires `uploaded=true`, a remote commit key, and a current commit-pointer
+  key in publish metadata;
 - consumes the resolved cleanup policy described in
   [Configuration](../config.md);
-- refuses unsafe deletes (root delete, out-of-root delete, symlink paths).
+- refuses unsafe deletes (root delete, out-of-root delete, and symlinked
+  ancestors or entries);
+- retries any recorded incomplete target on later invocations even when no
+  publish work is selected. Missing targets are a successful, idempotent
+  cleanup result only after the completion evidence is saved.
 
-Manual cleanup uses the same scoped-target checks. Invocation syntax and exact
-deletion scope belong in [CLI](../cli.md#clean) and
+Manual cleanup uses the same root-confined deletion mechanism. Invocation
+syntax and exact deletion scope belong in [CLI](../cli.md#clean) and
 [Operations](../operations.md#cleanup).
 
 ## Invariants
@@ -58,6 +75,8 @@ deletion scope belong in [CLI](../cli.md#clean) and
 - campaign-aware session root is mandatory.
 - manifest-driven stage state is durable across runs.
 - cleanup guardrails prevent destructive root/out-of-scope deletion.
+- ordinary workspace paths retain group-writable directory and file modes across
+  nested creation, replacement, and Notarius promotion.
 
 ## Implementation And Tests
 
@@ -65,10 +84,11 @@ deletion scope belong in [CLI](../cli.md#clean) and
   `internal/artifacts/local.go`
 - Run-local materialization: `internal/stage/run_local.go`
 - Immutable bundle promotion: `internal/fileops/directory.go`
-- Cleanup confinement: `internal/app/cleanup_targets.go`,
-  `internal/app/post_publish_cleanup.go`
+- Workspace modes: `internal/fileops/modes.go`
+- Cleanup confinement: `internal/fileops/cleanup.go`,
+  `internal/app/cleanup_targets.go`, `internal/app/post_publish_cleanup.go`
 - Tests: `internal/artifacts/paths_model_test.go`,
   `internal/artifacts/local_test.go`, `internal/stage/run_local_test.go`,
-  `internal/fileops/directory_test.go`,
-  `internal/app/cleanup_targets_test.go`,
+  `internal/fileops/directory_test.go`, `internal/fileops/modes_posix_test.go`,
+  `internal/fileops/cleanup_test.go`, `internal/app/cleanup_targets_test.go`,
   `internal/app/post_publish_cleanup_test.go`

docs/operations.md

@@ -92,6 +92,14 @@ Execution rules:
   repeated self-skip with the same reason and no outputs is stable and does not
   perpetually rerun downstream work.
 
+An explicit self-skip is a durable `skipped` stage outcome that later runs
+reconsider. It differs from successful no-output execution: disabled `render`
+and `publish`, and absent or no-executable `analyze`, record `succeeded` with
+metadata and no outputs. Ordinary later runs reuse those successful results;
+force the affected stage after enabling or configuring it. Optional artifact
+inputs are omitted only from the consuming artifact invocation and do not make
+the stage self-skip.
+
 Single-stage execution:
 
 ```bash
@@ -133,23 +141,39 @@ record does not fall back to the earlier outputs. The earlier run manifest and
 immutable bundle remain available for inspection, but downstream resolution
 requires a new current successful extraction record.
 
-Atomic Notarius bundle promotion is supported on Linux, macOS, and Windows.
-On other operating systems, extraction fails before copying the bundle into a
+Atomic Notarius bundle promotion is supported on Linux and macOS. On Windows
+and other operating systems, extraction fails before copying the bundle into a
 temporary promotion tree because Narratio has no verified atomic no-replace
 directory primitive there. This is an extraction limitation, not a broader
 platform-support guarantee for every Narratio workflow.
 
+## External Command Lifecycle
+
+When an external command is cancelled or times out, Narratio terminates its
+owned descendants as well as the command itself. Cancellation first requests
+termination where the platform supports it, then force terminates after a
+bounded wait. A command is not considered finished until its leader has been
+reaped, and descendants that keep standard output or error open cannot keep
+the invocation blocked. Other operating systems fail closed rather than launch
+a command without tree ownership.
+
+Subprocess stdout and stderr diagnostics are separately redacted and capped at
+8 MiB per invocation. Narratio does not retain configured credential values in
+these logs or their error tails; reaching a capture limit terminates the command
+tree and reports which stream exceeded the limit.
+
 Run-local diagnostics are:
 
 - `runs/{run_id}/extract/notarius.receipt.json`
 - `runs/{run_id}/extract/notarius.stderr.log`
 - `runs/{run_id}/extract/notarius-output/` before durable promotion
 
-The run-record upload excludes the complete
-`extract/notarius-output/**` subtree. The receipt and stderr files remain
-eligible run-record diagnostics. The durable bundle is never scanned for
-implicit publication; only lanes named by explicit `pipeline.publish.outputs`
-rules are uploaded.
+The run-record upload is an allowlist derived from the validated run manifest,
+not a workspace scan. Each declared source is opened without following
+symlinked ancestors or the leaf, verified as a regular file, and streamed from
+that verified descriptor. Unlisted files and unsafe entries are never uploaded.
+The durable bundle is never scanned for implicit publication; only lanes named
+by explicit `pipeline.publish.outputs` rules are uploaded.
 
 To intentionally replace the current extraction result, run:
 
@@ -184,13 +208,29 @@ Publish commit model:
 
 - uploads eligible run files under `{session_prefix}/runs/{run_id}/`, excluding
   audio and the run-local Notarius staging bundle;
-- uploads configured published outputs, including only explicitly configured
-  extraction lanes;
-- uploads `previous/**` cache files when present;
-- writes `current/manifest.json`;
-- writes `current/run_id.txt` last.
+- uploads configured published outputs and `previous/**` cache files into the
+  same immutable run scope, including only explicitly configured extraction
+  lanes;
+- writes `{session_prefix}/runs/{run_id}/commit.json` after all declared
+  immutable objects are uploaded and verified; and
+- writes `{session_prefix}/current/commit-pointer.json` once, last.
 
-`current/run_id.txt` is the remote current-state commit marker.
+`current/commit-pointer.json` is the remote current-state commit marker. It
+selects exactly one immutable commit, which declares the complete object set.
+
+## Remote Commit Migration
+
+The immutable remote commit contract uses
+`runs/{run_id}/commit.json` to declare a run's complete object set and a small
+`current/commit-pointer.json` to select it. The pointer binds the selected
+commit by version, checksum, size, and storage generation; committed artifacts
+are also checksum- and generation-bound. Readers accept this contract now and
+strictly reject mismatched or unknown data.
+
+Legacy reads are limited to a coherent `current/manifest.json` and
+`current/run_id.txt` pair; a torn pair is rejected. New publication does not
+write that pair and remote commit state does not carry local
+`current_pointer_written` metadata.
 
 ## Publish Locks
 
@@ -204,7 +244,14 @@ Effective lock rules:
 - static and remote locks are merged;
 - static locks win on source collisions;
 - locked outputs are intentional skips;
-- lock add/remove commands mutate only remote lock state.
+- lock add/remove commands mutate only remote lock state through generation-bound
+  conditional writes. A command retries a bounded number of concurrent
+  conflicts while its invocation context remains active, so it never replaces a
+  different lock-document generation; and
+- a publish re-reads remote locks immediately before it writes the current
+  commit pointer. A lock committed before that recheck prevents selecting the
+  new snapshot, even though its already-uploaded immutable objects may remain
+  available for a later retry.
 
 Examples:
 
@@ -230,20 +277,30 @@ Apply:
 narratio session restore 2026-04-04
 ```
 
+`--dry-run` does not write durable session files. It still reads the selected
+remote current state and may read object identity/content needed to classify the
+plan, so it is not a network-free operation.
+
 Default restore scope:
 
-- `manifest.json`
-- `transcripts/**`
-- `artifacts/**`
+- the committed session manifest and the committed transcript/artifact objects
+  declared by the selected remote commit
 - `previous/**` when needed by configured previous-session artifact inputs
 
 Optional:
 
 - `--include-audio` to include `audio/**`
-- `--force` to overwrite local conflicts
+- `--force` to overwrite eligible conflicting regular files; it never replaces
+  directories or other non-regular local targets
 
 Restore writes an execution report at `reports/restore-latest.json`.
 
+If restore fails after beginning installation, it leaves a durable
+`.restore-incomplete.json` marker in the session root. Pipeline runs will stop
+until you rerun the same restore command and it completes. Restore intentionally
+does not try to roll back files already installed; retrying the selected remote
+snapshot is the recovery procedure.
+
 ## Local State Layout
 
 Session root:
@@ -284,6 +341,38 @@ Cache layout (durable S3 audio cache):
 
 - `{cache.root}/s3/{bucket}/...`
 
+Each cached audio file has an adjacent managed identity record. It binds the
+file to its remote object version and verified digest; deleting or altering the
+record simply causes Narratio to download and verify the object again.
+
+### Workspace Permissions
+
+Ordinary Narratio workspace content is intentionally shareable with the
+workspace group. On POSIX systems, Narratio-created workspace, spool, and cache
+directories converge on setgid `02775`; ordinary files, including manifests,
+transcripts, generated configuration, logs, reports, and Notarius artifacts,
+converge on `0664`. Narratio explicitly applies these modes so a restrictive
+caller umask does not remove group write or setgid. It does not change file or
+directory ownership: the configured workspace's existing group is inherited.
+
+Windows does not implement POSIX mode bits or setgid semantics. Configure the
+workspace, spool, and cache locations with an ACL that grants the collaborating
+group read/write access, and configure credential locations with an ACL limited
+to the intended credential owner. Do not use POSIX mode displays as evidence of
+Windows access control.
+
+API keys are credentials, not ordinary workspace data. Store them outside the
+shared workspace or in a separately restricted credential location; ordinary
+workspace group access must never be treated as authorization to read keys.
+On POSIX, provision a credential directory as `0700` and credential files as
+`0600`; Narratio rejects group- or other-readable configured credential paths.
+On Windows, restrict the directory and files with ACLs to the credential owner.
+
+External adapter results are individually bounded before Narratio validates or
+materializes them. These per-file limits do not reserve disk space: prevent hard
+disk exhaustion with filesystem, service, container, or volume quotas sized for
+the session workload.
+
 ## Cleanup
 
 Session-scoped cleanup:
@@ -309,9 +398,14 @@ Rules:
 
 - `clean` deletes work/spool session state;
 - cache is preserved unless `--clear-cache` is set;
+- each deletion is confined beneath its configured workspace, spool, or cache
+  root and refuses symlinked paths;
 - automatic post-publish cleanup is gated by successful publish commit plus:
   - `pipeline.spool.delete_audio_after_publish=true`
   - `pipeline.workspace.cleanup_after_publish=true`
+  - Narratio first records the exact run-scoped cleanup obligation. If cleanup
+    reports incomplete, the remote committed snapshot remains current; rerun
+    Narratio to retry only the outstanding confined local cleanup.
 
 ## Operational Caveats
 

docs/policy/architecture.md

@@ -119,6 +119,17 @@ install the validated session manifest after other restored durable files. The
 physical workflow and recovery procedures belong in
 [Operations](../operations.md).
 
+Restore and runner transitions for one session use the same local lock. A
+durable incomplete-restore marker blocks runner reuse after a partial restore;
+safe retry, rather than rollback of arbitrary local effects, is the recovery
+mechanism. Restored manifest-local references must be confined to the selected
+local session root, never trusted as producer-machine absolute paths.
+
+For the immutable remote-commit protocol, a restore or status operation binds
+to one pointer-selected commit and only its declared object identities. A force
+flag may replace an eligible regular managed file, but never turns a directory
+or other non-regular conflict into a successful restore.
+
 ## Configuration
 
 Configuration is strict, explicit, centralized, and operator-oriented.
@@ -146,6 +157,10 @@ Canonical helpers own workspace, spool, cache, session, run, input, transcript,
 artifact, log, report, configuration, and publish-current paths. Callers must
 not reconstruct canonical paths through scattered string concatenation.
 
+Reusable audio cache entries require a typed record that binds a confined,
+no-follow regular file and its digest to the selected remote object identity.
+Size alone and unqualified multipart ETags are not content-integrity evidence.
+
 Artifact resolution is deterministic and manifest-aware. Producers materialize
 canonical outputs before reporting success, and consumers resolve declared
 artifact identities rather than infer files from unrelated directory contents.
@@ -167,22 +182,38 @@ contracts belong under [Integrations](../integrations/).
 ## Publish Commit Boundary
 
 Publish has one explicit remote commit boundary. A remote run becomes current
-only after Narratio has successfully uploaded the run record, required published
-outputs, `current/manifest.json`, and finally `current/run_id.txt`.
+only after Narratio has successfully uploaded its immutable run-scoped objects,
+the immutable commit manifest, and finally the current commit pointer.
 
-`current/run_id.txt` is the commit marker and must be written last. Failed,
-incomplete, skipped, or uncommitted publish attempts must not be presented as
-current remote state. Publish locks remain authoritative and are not bypassed by
-a forced run.
+`current/commit-pointer.json` is the sole mutable selector and must be written
+exactly once, last. Failed, incomplete, skipped, or uncommitted publish attempts
+must not be presented as current remote state. Publish locks remain authoritative
+and are not bypassed by a forced run. Mutable remote locks use provider-enforced
+generation preconditions and are revalidated immediately before pointer
+selection; loss of that check leaves the prior committed snapshot current.
 
 Automatic local cleanup is permitted only after a successful publish commit,
 only when explicitly configured, and only through the path-safety guardrails.
+It is a durable local obligation bound to that committed run and its exact
+targets, not an inferred side effect of the current stage list. A cleanup
+failure makes the invocation incomplete while leaving the committed remote
+snapshot authoritative; later invocations resume the recorded obligation.
 
 ## Security, Privacy, And Diagnostics
 
-Narratio handles private campaign material. Transcripts, prompts, generated
-artifacts, reports, logs, manifests, and diagnostic files are potentially
-sensitive.
+Narratio distinguishes ordinary workspace data from credentials. Campaign and
+session material—including manifests, transcripts, prompts, generated
+configuration, logs, reports, diagnostics, and Notarius artifacts—is
+intentionally shareable with the configured workspace group. API-key material
+is sensitive and is not covered by the ordinary workspace-sharing policy.
+
+On POSIX systems, Narratio-created ordinary workspace directories converge on
+setgid `02775` and ordinary workspace files on `0664`, even when the caller's
+umask is restrictive. This preserves the existing workspace group for nested
+creation and atomic replacements without changing ownership. API-key storage
+uses a separate restrictive contract. On Windows, POSIX mode bits and setgid
+are not authoritative; operators must provide the equivalent shared-group and
+credential-restricted ACLs described in [Operations](../operations.md#workspace-permissions).
 
 Raw secrets must not be stored in pipeline, campaign, or session YAML or written
 to manifests, logs, generated configuration, reports, publish metadata,

docs/roadmap/audit-plan.md

@@ -1,332 +0,0 @@
-# Codebase Audit Plan
-
-Status: proposed
-
-## Purpose
-
-This audit will evaluate Narratio for correctness, efficiency, maintainability,
-and test-suite value. It will identify defects and credible risks, duplicated or
-near-duplicated behavior, code that can be made smaller or more idiomatic, and
-complex code whose remaining invariants need focused explanation.
-
-The audit is investigative. It should produce evidence-backed findings and a
-prioritized remediation backlog, not make opportunistic production changes as
-it proceeds. The [Audit Sequence](audit-sequence.md) assigns this scope to
-concrete execution stages.
-
-## Authoritative Baseline
-
-Review implemented behavior against its canonical owner rather than treating
-the current implementation or tests as the specification:
-
-- [Architecture](../policy/architecture.md) for system boundaries, dependency
-  direction, state and path ownership, safety properties, and pipeline
-  invariants;
-- [Internal Overview](../internal/overview.md) and its focused internal
-  documents for implemented ownership and mechanics;
-- [Testing Policy](../policy/testing.md) for risk-based sufficiency, durable
-  boundaries, test-double guidance, and test lifecycle decisions;
-- the [CLI](../cli.md), [Configuration](../config.md),
-  [Operations](../operations.md), and [integration contracts](../integrations/)
-  for externally observable behavior; and
-- the [Documentation Policy](../policy/documentation.md) for canonical ownership
-  and the distinction between current and proposed behavior.
-
-Where code, tests, and documentation disagree, record the disagreement. Do not
-assume which one is wrong until the canonical contract and caller expectations
-have been traced.
-
-## Audit Principles
-
-1. Review correctness before cleanup. A shorter implementation is not an
-   improvement if it weakens a state transition, safety check, or external
-   contract.
-2. Trace behavior across boundaries. Narratio's most important properties often
-   emerge from the interaction of application orchestration, stages, manifests,
-   artifact resolution, filesystem operations, and adapters.
-3. Distinguish repeated syntax from repeated policy. Extract a helper only when
-   the behavior has one stable owner and the shared abstraction makes that
-   ownership clearer. Similar stage code may be intentionally explicit.
-4. Prefer narrow, idiomatic Go over generic frameworks. In particular, proposed
-   refactors must preserve the explicit canonical stage sequence and must not
-   turn Narratio into a workflow engine or a second configuration system for
-   downstream tools.
-5. Optimize credible work. Flag repeated I/O, hashing, serialization, remote
-   calls, subprocess work, allocation, or poor asymptotic behavior when the
-   relevant path can matter. Require a benchmark or workload argument for
-   performance changes whose benefit is not evident.
-6. Treat comments as explanations of intent. Recommend comments for invariants,
-   ordering constraints, non-obvious failure policy, or security reasoning—not
-   as narration of ordinary Go or a substitute for simplifying code.
-7. Judge tests as a suite. A test can be locally reasonable and still add no
-   marginal protection, while a compact test can be inadequate for a
-   consequential cross-component failure.
-
-## Evidence And Finding Standard
-
-Begin from a cleanly identified revision and record toolchain and platform
-assumptions. Use the code knowledge graph to find ownership, callers, callees,
-similarity candidates, high-complexity functions, and weakly protected
-boundaries. Confirm every candidate by reading the implementation, its focused
-tests, and the applicable contract. Text search and static analysis supplement
-the graph for literals, configuration, generated files, and patterns that are
-not modeled reliably.
-
-Each finding should record:
-
-- category: correctness defect, correctness risk, duplication, simplification,
-  efficiency, architectural boundary, comment/clarity, or test-suite issue;
-- source locations and the affected contract or invariant;
-- concrete evidence and a realistic failure or maintenance scenario;
-- impact, likelihood, confidence, and estimated remediation scope separately;
-- the smallest plausible improvement and its intended owner;
-- tests that already protect the behavior, tests that should change or be
-  added, and tests that may become redundant; and
-- dependencies on, or conflicts with, other findings.
-
-Do not report a metric alone as a finding. Complexity, similarity, coverage,
-fan-in, file size, and test count are prioritization signals that require manual
-confirmation. Consolidate findings that share one root cause.
-
-## Cross-Cutting Review Lenses
-
-### Correctness And Pipeline Semantics
-
-Construct an explicit lifecycle matrix for every stage outcome: first run,
-already-succeeded skip, self-skip, failure, interruption, forced replacement,
-non-resumable result, and successful rerun. Trace how each outcome changes the
-session manifest, invocation manifest, downstream stage state, artifacts,
-diagnostics, and cleanup eligibility.
-
-Across the pipeline, verify:
-
-- the registry exposes one deterministic canonical order;
-- each stage's declared inputs, outputs, configuration, adapters, and manifest
-  effects agree with its implementation and focused documentation;
-- inputs are resolved through manifest and artifact contracts rather than
-  incidental directory contents;
-- run-local outputs are fully validated before canonical materialization;
-- failure, cancellation, or process interruption cannot advertise partial work
-  as successful;
-- force and changed outcomes invalidate exactly the intended succeeded
-  downstream work;
-- repeated execution is idempotent where promised, and ordering is stable
-  wherever maps, directory reads, remote listings, or dependency graphs are
-  involved;
-- session, campaign, run, source, checksum, contract, and external provenance
-  identities cannot be confused across runs; and
-- errors preserve useful causes and do not expose secrets or private content.
-
-Use fault-oriented reasoning at durability boundaries: fail immediately before
-and after manifest saves, canonical renames, external process completion,
-uploads, current-manifest publication, the current-run commit marker, restore
-manifest installation, and cleanup. Determine which state is authoritative and
-whether the next invocation recovers safely.
-
-### Duplication And Helper Ownership
-
-Search for exact and semantic duplication in production and tests, including:
-
-- repeated stage setup, input resolution, output validation, run-local
-  materialization, metadata construction, and error adaptation;
-- repeated manifest create/load/save and session/run transition handling;
-- repeated adapter construction, timeout parsing, command execution, generated
-  configuration, log handling, and output checks;
-- repeated source-ID, destination, remote-key, and path validation policy;
-- repeated sorting, deduplication, checksum, copy, and atomic-write mechanics;
-  and
-- repeated test fixtures and assertions that encode the same policy at several
-  layers.
-
-For each candidate, decide whether it is coincidental similarity, a repeated
-mechanism, or duplicated policy. Recommend extraction only when the helper can
-have a clear package owner, a narrow contract, and callers that become easier
-to understand. Prefer an unexported local helper when sharing is package-local.
-Do not create a broad utility package, force unlike stage results into one data
-model, or move policy into storage/file-operation helpers.
-
-Initial similarity and complexity signals should seed, but not predetermine,
-inspection of the single-stage command wrappers, session/run manifest
-persistence pairs, adapter constructors, Scriptorium operations, stage fakes,
-and common stage materialization paths.
-
-### Simplification, Go Idioms, And Efficiency
-
-Review long or branch-heavy functions for separable decisions, state
-transitions, or data transformations. Pay particular attention to orchestration,
-configuration validation, artifact dependency resolution, resume verification,
-restore/previous-cache planning, and analyze/publish selection logic. A useful
-refactor should reduce cognitive load while leaving the important ordering
-visible.
-
-Check for:
-
-- unnecessary nesting, defensive branches made unreachable by earlier
-  validation, repeated normalization, and overly wide parameter lists;
-- interfaces defined for hypothetical extensibility rather than a demonstrated
-  consumer boundary;
-- manual slice, map, string, error, and filesystem logic with a clearer standard
-  library form;
-- incorrect or inconsistent `errors.Is`/`errors.As`, wrapping, context
-  propagation, deferred cleanup, response-body closure, process waiting, and
-  goroutine/channel ownership;
-- redundant filesystem scans, `stat`/checksum passes, whole-file buffering,
-  copying, YAML/JSON round trips, sorting, remote listings, downloads, uploads,
-  or adapter initialization;
-- linear searches nested in loops and repeated dependency or artifact lookup
-  that should use an indexed map or a single planning pass;
-- unbounded concurrency, leaked work after cancellation, serialized independent
-  work, and nondeterministic result collection; and
-- obsolete dependencies, portability assumptions, and platform-sensitive path
-  or atomic-rename behavior.
-
-Keep correctness and diagnosability ahead of micro-optimization. When a simpler
-algorithm changes performance characteristics, specify the representative
-input size and validation method.
-
-### Comments And Local Explanation
-
-Review high fan-in, high-complexity, security-sensitive, and commit-boundary
-code after likely simplifications have been identified. Add a comment
-recommendation when a maintainer needs to know why:
-
-- state transitions or persistence operations occur in a specific order;
-- a stale record intentionally retains data while another transition clears it;
-- a path is checked more than once to resist traversal, symlink replacement, or
-  time-of-check/time-of-use hazards;
-- an artifact is accepted only with particular manifest, checksum, contract, or
-  provenance evidence;
-- a partial operation is intentionally not rolled back;
-- a remote pointer or local manifest must be installed last; or
-- concurrency, cancellation, compatibility, or downstream-tool behavior makes
-  an apparently simpler approach unsafe.
-
-Prefer a named helper, typed state, or smaller control flow when that removes the
-need for explanation. Check existing comments for stale claims as well as
-missing rationale.
-
-### Test Suite Against The Canonical Policy
-
-Build a risk-to-test matrix rather than auditing tests file by file in
-isolation. For each important behavior, identify its proper owner—parser,
-validator, domain package, adapter, orchestrator, CLI, integration, or end to
-end—and identify all tests that claim to protect it.
-
-Evaluate:
-
-- protection of data integrity, destructive operations, compatibility,
-  security, concurrency, idempotency, recovery, and partial failure;
-- manifest transitions, force/invalidation, resume validation, atomic
-  materialization, publish commit order, restore install order, and cleanup
-  gates as assembled behaviors;
-- realistic HTTP, subprocess, filesystem, and object-store boundary behavior,
-  including cancellation and malformed responses;
-- whether higher-level tests intentionally sample lower-level behavior or
-  redundantly reproduce its full policy;
-- whether tests assert durable outcomes or private constants, exact error text,
-  incidental paths, call choreography, or oversized snapshots;
-- whether real fast collaborators could replace elaborate doubles, and whether
-  stateful fakes are realistic enough for the risk they protect;
-- fixture/helper duplication, oversized test cases, and setup that obscures the
-  behavior under test without introducing a heavyweight test framework;
-- deterministic, offline, credential-free, order-independent execution and
-  safe handling of environment and process-global state;
-- focused fuzz candidates in parsing, normalization, source IDs, remote/local
-  path mapping, manifest decoding, and configuration boundaries; and
-- the presence and value of a small number of representative assembled
-  workflows.
-
-Use coverage only to locate unexpectedly weak consequential branches. Also
-inspect packages with extensive coverage for redundant tests and refactoring
-friction. For every proposed addition, deletion, or consolidation, state the
-realistic defect and marginal confidence involved.
-
-The audit baseline should include the repository's canonical commands plus
-targeted diagnostic runs where supported:
-
-```sh
-go test ./...
-go test -race ./...
-go vet ./...
-go build ./cmd/narratio
-```
-
-Use focused repeated or shuffled runs to investigate state leakage and
-flakiness, and collect package/branch coverage for diagnosis. Review continuous
-integration to determine whether the appropriate offline validation is enforced;
-do not turn coverage percentage into a gate merely for this audit.
-
-## Area-By-Area Inspection Map
-
-| Area | Primary locations | What to inspect |
-| --- | --- | --- |
-| Process and application boundary | `cmd/narratio`, `internal/app` | Command dispatch, configuration selection, production composition, secret loading, lock lifetime, object-store initialization, context/error propagation, and separation of CLI reporting from orchestration policy. Review operator commands for consistent current-state authority and shared read-only mechanics. |
-| Stage registry and runner | `internal/stage/placeholders.go`, `internal/stage/stage.go`, `internal/app/planner.go`, `internal/app/runner.go`, `internal/app/run_stage.go` | Canonical order, action decisions, resume/force/self-skip/failure transitions, downstream invalidation, session/run manifest consistency, resource lifecycle, cleanup triggering, and opportunities to decompose the runner without hiding its state machine. |
-| Configuration | `internal/config` | Strict decoding, discovery and precedence, centralized defaults, normalization, templating, validation order, unknown fields, empty-value behavior, secret references, cross-field constraints, path confinement, deterministic errors, duplicated validator policy, and compatibility with maintained examples. |
-| Prepare and audio | `internal/stage/prepare.go`, `internal/audio`, `internal/previouscache` | Local/S3 exclusivity, cache and spool identity, partial downloads, checksum/reuse policy, previous-session required/optional planning, deterministic input records, clearing semantics, traversal safety, and avoiding repeated remote or filesystem work. |
-| Transcript stages | `internal/stage/transcribe.go`, `merge.go`, `polish.go`, `normalize.go`, `trim.go`, `render.go` | Contract parity across similar stages, bounded concurrency and cancellation, deterministic speaker/input ordering, run-local validation and canonical promotion, report/diagnostic classification, disabled behavior, and narrow opportunities for shared mechanics. |
-| Extraction | `internal/stage/extract.go`, `extract_resume.go`, `internal/adapters/notarius`, `internal/fileops/directory.go` | External receipt and lane validation, configuration fingerprint limits, immutable promotion, symlink/root replacement defenses, provenance and checksum checks, immediate and cross-invocation reuse, obsolete versus unsafe outcomes, failure residue, and whether dense verification logic can be clarified without weakening it. |
-| Analyze and artifact dependencies | `internal/stage/analyze.go`, `internal/artifacts`, `internal/artifactpolicy` | Source-family validation, runtime catalog state, enabled/selected/reused distinctions, topological ordering and cycle handling, required/optional inputs, local-only previous sources, deterministic metadata, repeated lookup/scanning, and ownership shared with config and publish. |
-| Publish and cleanup | `internal/stage/publish.go`, `internal/app/post_publish_cleanup.go`, `internal/app/cleanup_targets.go` | Prerequisite success, output selection, locks, required/optional behavior, exclusion rules, deterministic upload set, retry/idempotency implications, current-manifest then commit-marker ordering, metadata gates, and destructive path confinement. |
-| Manifest state | `internal/manifest` | Validation and backward compatibility, atomic persistence, timestamps, session/run identity, transition truth table, clearing versus retaining payload, create/load/save duplication, failure during dual-manifest updates, and whether state mutation has a single owner. |
-| Artifacts, paths, and policy | `internal/artifacts`, `internal/artifactpolicy`, `internal/pathsafe` | Canonical helper coverage, ad hoc reconstruction by callers, source-ID ownership, manifest-first resolution, extraction/current-state identity, destination normalization, stable ordering, typed missing-state errors, symlink/traversal defenses, and duplicate policy across config/stages/app. |
-| Restore | `internal/app/restore*.go`, `internal/previouscache`, `internal/audio` | Remote authority, confined mapping, deterministic plan actions, local conflict and force behavior, dry-run purity, temp-file installation, manifest-last ordering, partial failure/retry behavior, report accuracy, cache reuse, and shared current-state mechanics. |
-| File operations | `internal/fileops`, `internal/pathsafe`, local-store code in `internal/artifacts` | Atomic-write and promotion guarantees, permissions, close/sync/rename error handling, temp cleanup, same-filesystem assumptions, replacement policy, regular-file-only traversal, symlink and root-swap resistance, lock cleanup, and portability. |
-| External adapters and storage | `internal/adapters`, `internal/audio` | Transport isolation, shared subprocess mechanics versus adapter-specific policy, command/config duplication, quoting and working directories, timeouts/cancellation, stdout/stderr separation, HTTP body and retry behavior, S3 pagination/streaming/not-found mapping, credential independence, and external error adaptation. |
-| Shared models and diagnostics | `internal/artifactmodel`, `internal/contracts`, `internal/logging` | Serialization and validation invariants, unnecessary conversions, ownership of shared types, stable diagnostic structure, redaction, and whether small shared packages remain cohesive. |
-| Tests, examples, and automation | all `*_test.go`, `examples/`, `.woodpecker/` | Risk ownership, semantic duplication, fixture cost, policy-coupled assertions, realistic boundary tests, end-to-end sufficiency, default-suite isolation, example validation, diagnostic coverage, flakiness, runtime cost, and enforcement of canonical validation. |
-
-## Narratio-Specific Cross-Boundary Scenarios
-
-In addition to package-local review, trace these complete scenarios because a
-modular pipeline can look correct within every package while violating an
-end-to-end invariant:
-
-1. A stage succeeds, its result becomes non-resumable, the rerun fails, and a
-   later invocation decides what remains usable.
-2. An upstream forced or changed outcome interacts with already-succeeded,
-   self-skipped, and disabled downstream stages.
-3. Extraction produces a valid immutable bundle, then configuration or
-   transitive Notarius inputs change before analyze or publish.
-4. Previous-session state is published, restored or prepared into the local
-   cache, and consumed by analyze without an unintended remote read.
-5. Publish fails at each upload boundary, especially between current manifest
-   and current-run pointer, followed by status, restore, and retry.
-6. Restore encounters identical files, conflicting files, unsafe remote keys,
-   cache hits, and a failure immediately before manifest installation.
-7. Automatic or manual cleanup is requested after skipped, failed, locked,
-   partially uploaded, and fully committed publish outcomes.
-8. Cancellation reaches bounded transcription work, HTTP requests,
-   subprocesses, object storage, and manifest reporting without leaks or false
-   success.
-9. A configured artifact is disabled, unselected, reused, generated from
-   another artifact, sourced from extraction, or sourced from a previous
-   session, then filtered for publish.
-10. The same session is invoked concurrently, including lock contention and
-    cleanup/release failures.
-
-## Completion Criteria
-
-The audit is complete when:
-
-- every area in the inspection map has been reviewed against its canonical
-  contracts and focused tests;
-- the stage lifecycle matrix and cross-boundary scenarios have explicit
-  conclusions;
-- duplication candidates have been classified rather than merely counted;
-- simplification and performance recommendations explain their correctness
-  constraints and expected benefit;
-- comment recommendations identify the non-obvious rationale to preserve;
-- the test suite has a risk-based sufficiency assessment, including gaps,
-  redundancy, durability, execution properties, and automation;
-- findings are deduplicated, evidence-backed, and ranked by risk and dependency;
-  and
-- unresolved questions and intentionally accepted risks are recorded rather
-  than silently omitted.
-
-## Execution
-
-The [Audit Sequence](audit-sequence.md) is the canonical owner of execution
-order, stage boundaries, checkpoints, validation, and audit deliverables. This
-document remains the canonical owner of audit scope, review criteria, and the
-finding standard.

docs/roadmap/audit-sequence.md

@@ -1,734 +0,0 @@
-# Codebase Audit Sequence
-
-Status: proposed
-
-## Purpose And Relationship To The Audit Plan
-
-This document turns the [Codebase Audit Plan](audit-plan.md) into a bounded,
-execution-ready sequence. The plan owns scope, review criteria, and the finding
-standard. This document owns ordering, dependencies, working records,
-validation, and exit gates.
-
-The sequence is for investigation only. Do not mix production refactors or bug
-fixes into the audit. A confirmed urgent defect may justify stopping to request
-a separate remediation change, but its fix is not part of this sequence.
-
-## Audit Run Records
-
-Create `docs/roadmap/audit-findings.md` when the audit begins. It is the single
-working ledger and final audit report. Initialize it with:
-
-- the audited revision, branch/worktree state, Go version, platform, and audit
-  date;
-- baseline command results and timings;
-- an area coverage ledger;
-- the stage lifecycle matrix;
-- the cross-boundary scenario matrix from the audit plan;
-- a risk-to-test matrix;
-- candidate and confirmed finding registers; and
-- unresolved questions, accepted risks, and final conclusions.
-
-Track each execution stage in the coverage ledger with one of `not_started`,
-`in_progress`, `complete`, or `blocked`. For a completed stage, record:
-
-- contracts, packages, files, and important symbols reviewed;
-- graph traces, commands, tests, or other evidence used;
-- finding and candidate IDs produced;
-- explicit no-finding conclusions for reviewed high-risk behavior; and
-- follow-up questions assigned to later stages.
-
-Use stable finding IDs with these prefixes:
-
-| Prefix | Category |
-| --- | --- |
-| `COR` | Confirmed correctness defect |
-| `RSK` | Correctness or operational risk |
-| `ARC` | Ownership or architectural-boundary issue |
-| `DUP` | Duplicated mechanism or policy |
-| `SIM` | Simplification or idiomatic-Go opportunity |
-| `EFF` | Efficiency or resource-use issue |
-| `COM` | Missing, misleading, or stale explanatory comment |
-| `TST` | Test-suite gap, redundancy, brittleness, or execution issue |
-
-Candidate IDs remain candidates until manual inspection confirms the behavior,
-contract, realistic scenario, and affected callers. Rejected candidates remain
-in a short classification log so later stages do not reopen them without new
-evidence.
-
-## Execution Rules
-
-1. Pin the audit to the revision recorded in Stage 0. If the worktree or HEAD
-   changes, record the change and rerun every affected stage; do not silently
-   combine evidence from different implementations.
-2. Use codebase graph search and call/data-flow traces before broad source
-   search. Read the exact implementation, focused tests, and canonical contract
-   before confirming a finding.
-3. Record test-policy observations during every behavior pass. Stage 12 owns the
-   suite-wide conclusion but must not rediscover the suite from scratch.
-4. Record cross-area observations as candidates for the stage that owns the
-   conclusion. Avoid producing duplicate findings from several review passes.
-5. Treat baseline failures as evidence, not automatic blockers. Continue when
-   read-only inspection remains sound, and state the limitation. Stop only when
-   the repository cannot be identified, required sources are unavailable, or a
-   failure makes later evidence unreliable.
-6. Do not exercise a suspected destructive, credentialed, paid, or live-service
-   path merely to prove a defect. Use source reasoning, existing safe fakes, or
-   a narrowly controlled offline reproduction.
-7. Escalate a credible active data-loss, secret-exposure, or unsafe-cleanup
-   defect immediately. Preserve the evidence and do not wait for final
-   synthesis before reporting it.
-8. A stage is complete only when its exit gate is met. A package test passing is
-   evidence, not proof that the review is complete.
-
-## Sequence Overview
-
-| Stage | Focus | Depends on | Primary result |
-| --- | --- | --- | --- |
-| 0 | Pin revision and establish baseline | None | Reproducible audit record |
-| 1 | Contract, boundary, and lifecycle map | 0 | Review matrices and ownership map |
-| 2 | Runner and manifest state machine | 1 | Lifecycle and dual-ledger conclusions |
-| 3 | Paths, artifacts, and filesystem safety | 1-2 | State/path authority and mutation conclusions |
-| 4 | Publish, remote commit, and cleanup | 2-3 | Commit-boundary and destructive-operation conclusions |
-| 5 | Restore and remote/previous state | 2-4 | Restore authority and recovery conclusions |
-| 6 | Configuration and application composition | 1-5 | Validation and wiring conclusions |
-| 7 | External adapters and shared support | 3, 6 | Boundary, cancellation, and resource conclusions |
-| 8 | Prepare and transcript-processing stages | 2-3, 6-7 | Ordinary stage-contract conclusions |
-| 9 | Extraction vertical slice | 2-3, 6-7 | Promotion, provenance, and resume conclusions |
-| 10 | Analyze and artifact dependency slice | 3, 6, 8-9 | Dependency and source-resolution conclusions |
-| 11 | Cross-codebase duplication, simplicity, efficiency, and comments | 2-10 | Classified maintainability candidates |
-| 12 | Test-suite policy audit | 2-11 | Risk-based suite sufficiency assessment |
-| 13 | Synthesis and audit closeout | 0-12 | Final deduplicated audit report |
-
-Stages are intentionally ordered. Later stages may resolve candidates raised by
-earlier ones, but they must not invalidate an earlier stage silently. Return to
-the owning stage, update its coverage record, and note the new evidence.
-
-## Stage 0: Pin Revision And Establish Baseline
-
-### Entry
-
-- Repository root and `docs/development.md` are available.
-- The audit plan and canonical policy documents can be read.
-
-### Execute
-
-1. Record `git rev-parse HEAD`, branch/detached state, `git status --short`,
-   `go version`, `go env GOOS GOARCH`, and the current date.
-2. Confirm that the code knowledge graph represents the recorded repository and
-   revision; refresh the index if it is missing or stale.
-3. Capture the package/file/test inventory, entry points, architecture
-   boundaries, high fan-in symbols, complexity signals, and similarity signals.
-4. Run the default offline baseline and record wall time and failures:
-
-   ```sh
-   go test -count=1 ./...
-   go test -race -count=1 ./...
-   go vet ./...
-   ```
-
-5. Build into an external temporary directory so validation does not add a
-   workspace binary:
-
-   ```sh
-   audit_build_dir="$(mktemp -d)"
-   go build -o "$audit_build_dir/narratio" ./cmd/narratio
-   go test -coverprofile="$audit_build_dir/coverage.out" ./...
-   ```
-
-6. Inventory the repository's CI/release validation, maintained examples, fuzz
-   tests, golden data, opt-in tests, and generated-test update mechanisms.
-
-### Output
-
-- Baseline and inventory sections in `audit-findings.md`.
-- Initial coverage ledger containing Stages 0-13.
-- Unconfirmed metric-driven candidates, clearly labeled as such.
-
-### Exit Gate
-
-- Revision and environment are reproducible.
-- Every baseline command has a recorded result.
-- Graph freshness is known.
-- Any limitation that affects later stages has an owner and disposition.
-
-## Stage 1: Build The Contract, Boundary, And Lifecycle Map
-
-### Entry
-
-- Stage 0 is complete.
-
-### Execute
-
-1. Read the architecture, internal overview, testing policy, focused internal
-   documents, and the relevant CLI/configuration/operations/integration
-   contracts using the development guide's routing rules.
-2. Map each package and important interface to its owned policy. Mark every
-   cross-package dependency that appears to reverse or blur the intended
-   direction for later confirmation.
-3. Build a stage-contract matrix with canonical order, declared inputs,
-   outputs, configuration, adapters, skip behavior, resume validation,
-   materialization boundary, manifest effects, and downstream invalidation.
-4. Build the lifecycle matrix required by the audit plan: first run,
-   already-succeeded skip, self-skip, failure, interruption, forced replacement,
-   non-resumable result, and successful rerun.
-5. Assign each of the ten cross-boundary scenarios in the audit plan to its
-   primary execution stage and list supporting packages/tests.
-6. Seed the risk-to-test matrix with the intended test owner for each
-   architectural invariant. Do not judge sufficiency yet.
-
-### Output
-
-- Package ownership, stage-contract, lifecycle, scenario, and preliminary
-  risk-to-test matrices.
-- `ARC` and `RSK` candidates for apparent disagreements, without deciding from
-  documentation alone which artifact is wrong.
-
-### Exit Gate
-
-- Every area in the audit plan's inspection map has an assigned stage.
-- Every architectural invariant has an implementation owner and intended test
-  owner.
-- Unknown or contradictory contracts are explicitly recorded.
-
-## Stage 2: Audit The Runner And Manifest State Machine
-
-### Entry
-
-- Stage 1 matrices are complete.
-
-### Execute
-
-1. Trace the entry paths into full-run and single-stage execution through
-   `internal/app/planner.go`, `runner.go`, `run_stage.go`, and related helpers.
-2. Inspect `internal/manifest` models, validation, session/run creation,
-   loading, normalization, atomic saves, and all transition methods.
-3. Walk every lifecycle-matrix cell through both manifests. Verify clearing
-   versus retention of outputs, diagnostics, generated configuration, metadata,
-   errors, actions, timestamps, and downstream state.
-4. Reason about failures before and after each session-manifest and run-manifest
-   save. Determine which disagreement states are possible and how a later
-   invocation interprets them.
-5. Review force, changed-result, self-skip, failed-result, and non-resumable
-   invalidation separately. Confirm behavior at the first and last canonical
-   stage.
-6. Review session lock acquisition/release and concurrent invocation behavior,
-   while leaving path implementation details to Stage 3.
-7. Classify the runner's complexity and repeated session/run persistence paths:
-   state-machine clarity, justified explicitness, candidate local helpers, and
-   comments that preserve ordering rationale.
-8. Review focused app/manifest tests against the matrix and add observations to
-   the risk-to-test ledger.
-
-### Validation
-
-```sh
-go test -count=1 ./internal/app ./internal/manifest
-go test -race -count=1 ./internal/app ./internal/manifest
-```
-
-### Exit Gate
-
-- Every lifecycle cell has a source-backed conclusion for both manifests.
-- Cross-boundary scenarios 1, 2, and the lock portion of 10 are resolved or
-  carry explicit questions.
-- All runner/manifest candidates are confirmed, rejected, or assigned to a
-  named later stage.
-
-## Stage 3: Audit Paths, Artifacts, And Filesystem Safety
-
-### Entry
-
-- Stages 1-2 are complete.
-
-### Execute
-
-1. Review `internal/artifacts`, `internal/artifactpolicy`, `internal/pathsafe`,
-   `internal/fileops`, and local-store filesystem code.
-2. Inventory canonical path and key helpers, then search callers for ad hoc
-   reconstruction, double normalization, mixed slash/filesystem semantics, or
-   policy implemented outside its owner.
-3. Trace built-in, configured, extraction, previous-session, and current-state
-   artifact resolution. Verify identity, checksum, contract, provenance,
-   deterministic ordering, and typed missing-state behavior.
-4. Review atomic file writes, copies, directory promotion, temp cleanup,
-   permission preservation, close/sync/rename errors, existing-destination
-   behavior, same-filesystem assumptions, and platform sensitivity.
-5. Walk traversal, absolute path, broad root, symlink component, inspected-root
-   replacement, non-regular file, and time-of-check/time-of-use scenarios.
-6. Confirm that low-level file/storage helpers receive explicit destinations
-   and do not infer stage, campaign, session, run, or publish policy.
-7. Inspect lock-file implementation and cleanup errors to finish scenario 10.
-8. Record focused test ownership and gaps without duplicating Stage 2's state
-   conclusions.
-
-### Validation
-
-```sh
-go test -count=1 ./internal/artifacts ./internal/artifactpolicy ./internal/pathsafe ./internal/fileops
-go test -race -count=1 ./internal/artifacts ./internal/fileops
-```
-
-### Exit Gate
-
-- Every canonical path/key family has one identified owner.
-- Every material filesystem mutation has documented confinement and atomicity
-  conclusions.
-- Scenario 10 is resolved.
-- Safety checks that appear repetitive are classified before any simplification
-  recommendation is made.
-
-## Stage 4: Audit Publish, Remote Commit, And Cleanup
-
-### Entry
-
-- Stages 2-3 are complete.
-
-### Execute
-
-1. Trace publish from stage selection through object-store calls, manifest
-   metadata, commit-marker publication, run completion, and post-publish
-   cleanup.
-2. Verify prerequisite stage-state checks, selected/configured/extraction
-   output resolution, required versus optional outputs, static and remote
-   locks, run-file exclusions, previous-cache inclusion, and deterministic
-   upload order.
-3. Enumerate failures before and after every upload. Prove that
-   `current/run_id.txt` is written last and is the only remote-current commit
-   point.
-4. Review retry/idempotency behavior, existing remote objects, partial uploads,
-   pointer/manifest disagreement, and status/restore interpretation after each
-   partial outcome.
-5. Trace automatic and manual cleanup gates. Confirm publish execution,
-   `uploaded`, `current_pointer_written`, explicit policy, and confined targets
-   are all required at the correct boundary.
-6. Confirm that `--force` cannot override publish locks or cleanup safety.
-7. Review duplication between publish planning, artifact destination policy,
-   operator views, and cleanup metadata only after ownership is established.
-
-### Validation
-
-```sh
-go test -count=1 ./internal/stage ./internal/app ./internal/artifacts ./internal/adapters/storage
-```
-
-### Exit Gate
-
-- Cross-boundary scenarios 5 and 7 are resolved for every relevant failure
-  boundary.
-- Remote-current authority and local-cleanup eligibility have explicit truth
-  tables.
-- Publish findings distinguish stage policy from storage mechanics.
-
-## Stage 5: Audit Restore And Remote/Previous State
-
-### Entry
-
-- Stages 2-4 are complete.
-
-### Execute
-
-1. Trace restore discovery, planning, execution, reporting, audio
-   materialization, and previous-cache planning through `internal/app`,
-   `internal/artifacts`, `internal/previouscache`, `internal/audio`, and storage.
-2. Confirm remote pointer/manifest identity and campaign/session/run authority,
-   including missing and inconsistent current state.
-3. Verify remote-to-local confinement, deterministic action ordering,
-   `download`/`skip_same`/`conflict` decisions, force semantics, and dry-run
-   purity.
-4. Walk failures during download, checksum or manifest validation, atomic
-   install, report persistence, and the manifest-last boundary. Record the
-   intentional lack of rollback and retry consequences.
-5. Review audio spool/cache identity, cache-hit verification, partial download
-   behavior, and duplicate remote/filesystem work.
-6. Review previous-session requirement planning, required/optional behavior,
-   identity checks, published-path fallback, and deterministic local mapping.
-7. Confirm which mechanics are shared with status/validate/operator commands
-   and which caller-specific missing-state policies must remain separate.
-
-### Validation
-
-```sh
-go test -count=1 ./internal/app ./internal/previouscache ./internal/audio ./internal/artifacts ./internal/adapters/storage
-```
-
-### Exit Gate
-
-- Cross-boundary scenarios 4 and 6 are resolved through retry/recovery.
-- Restore authority, manifest-last installation, and partial-write behavior are
-  explicit.
-- Previous-cache conclusions are ready for the prepare and analyze passes.
-
-## Stage 6: Audit Configuration And Application Composition
-
-### Entry
-
-- Stage 1 is complete and Stages 2-5 have identified the policies that
-  configuration and composition must supply.
-
-### Execute
-
-1. Review `internal/config`, `cmd/narratio`, application command dispatch,
-   configuration selection, secret-file environment loading, and production
-   collaborator construction.
-2. Trace discovery, precedence, strict YAML decoding, defaults, empty values,
-   normalization, session templating, and validation order across pipeline,
-   campaign, and session configuration.
-3. Verify cross-field constraints for stage enablement, paths, timeouts,
-   concurrency, artifacts, Notarius, Scriptorium, publish, storage, cleanup,
-   audio, and previous-session behavior.
-4. Compare validation logic with maintained examples and the public
-   configuration contract. Record contract drift rather than silently choosing
-   code or docs.
-5. Check that filesystem secrets are loaded before the boundary that consumes
-   them and are excluded from logs, manifests, reports, generated files, and
-   errors.
-6. Review conditional construction of expensive/external collaborators and
-   cleanup of anything with a lifecycle. Confirm test injection cannot create a
-   behavior different from production composition.
-7. Classify repeated validators, path checks, timeout parsing, constructor
-   wrappers, and single-stage command wrappers by policy owner.
-
-### Validation
-
-```sh
-go test -count=1 ./internal/config ./internal/app ./cmd/narratio
-go vet ./...
-```
-
-### Exit Gate
-
-- Every operator-visible field used by audited behavior has a traced default,
-  normalization, validation, and consumer.
-- Composition conclusions cover enabled and disabled stages without requiring
-  live services or credentials.
-- Maintained examples have an explicit validity conclusion.
-
-## Stage 7: Audit External Adapters And Shared Support
-
-### Entry
-
-- Stages 3 and 6 are complete.
-
-### Execute
-
-1. Review `internal/adapters`, `internal/audio`, `internal/logging`,
-   `internal/contracts`, and `internal/artifactmodel` at their public package
-   boundaries.
-2. For each HTTP, subprocess, notification, and object-storage adapter, compare
-   implementation with its integration contract and trace all production
-   callers.
-3. Verify context cancellation, timeout ownership, process termination and
-   waiting, goroutine/channel closure, HTTP response-body closure, retries,
-   malformed responses, streaming, pagination, not-found mapping, and local
-   file cleanup.
-4. Confirm command argument construction, working directory, environment,
-   generated configuration, stdout/stderr separation, output validation, and
-   external error adaptation stay inside the owning adapter.
-5. Compare subprocess implementations to the shared subprocess package. Classify
-   repeated constructor/config/log/output mechanics separately from
-   adapter-specific protocol policy.
-6. Review fakes for realistic state and concurrency behavior, but defer their
-   suite-wide value judgment to Stage 12.
-7. Check shared models for avoidable conversions, stable serialization,
-   validation ownership, and redaction-sensitive diagnostic fields.
-
-### Validation
-
-```sh
-go test -count=1 ./internal/adapters/... ./internal/audio ./internal/logging ./internal/contracts ./internal/artifactmodel
-go test -race -count=1 ./internal/adapters/... ./internal/audio
-```
-
-### Exit Gate
-
-- Every external resource has an explicit acquisition, cancellation, and
-  release conclusion.
-- Transport types and protocol policy have not leaked into stages.
-- Adapter duplication candidates identify the correct shared or specific
-  owner.
-
-## Stage 8: Audit Prepare And Transcript-Processing Stages
-
-### Entry
-
-- Stages 2-3 and 6-7 are complete.
-
-### Execute
-
-1. Review `prepare`, `transcribe`, `merge`, `polish`, `normalize`, `trim`, and
-   `render` as vertical slices from resolved configuration and manifest input
-   through adapter call, run-local output, validation, canonical
-   materialization, and recorded result.
-2. Verify each implementation against the Stage 1 contract matrix and focused
-   internal document. Record any undeclared input, output, diagnostic, config,
-   adapter, or skip/failure behavior.
-3. For prepare, confirm local/S3 exclusivity, stable input copying,
-   previous-cache clearing/hydration, and deterministic manifest input records.
-4. For transcribe, confirm unique speaker identities, bounded runtime
-   concurrency, cancellation, deterministic result ordering, adapter-returned
-   path identity, and partial failure behavior.
-5. For transformation/render stages, confirm manifest-first resolution,
-   run-local paths, schema/report validation, disabled/default behavior,
-   canonical promotion, and diagnostic-versus-artifact classification.
-6. Compare similar stage implementations for shared mechanisms only after
-   listing meaningful differences. Avoid a generic stage framework.
-7. Add stage-focused test ownership, gaps, and redundancy candidates to the
-   risk-to-test matrix.
-
-### Validation
-
-```sh
-go test -count=1 ./internal/stage ./internal/audio ./internal/previouscache ./internal/adapters/whisperx ./internal/adapters/seriatim ./internal/adapters/audita ./internal/adapters/scriptorium
-go test -race -count=1 ./internal/stage ./internal/audio
-```
-
-### Exit Gate
-
-- Every reviewed stage has a completed contract-matrix row.
-- Cross-boundary scenario 8 is resolved for transcription and subprocess-backed
-  transformation stages.
-- Similarity candidates are classified as intentional explicitness, local
-  helper candidates, or shared-owner findings.
-
-## Stage 9: Audit The Extraction Vertical Slice
-
-### Entry
-
-- Stages 2-3 and 6-7 are complete.
-
-### Execute
-
-1. Trace extraction from configuration validation and composition through
-   transcript resolution, invocation fingerprint, Notarius execution, receipt
-   and lane validation, directory promotion, manifest recording, catalog
-   hydration, resume validation, analyze, and publish consumers.
-2. Verify run-local isolation, regular-file and confined-index requirements,
-   required-lane policy, contract/provenance construction, checksum timing,
-   immutable destination identity, and no-replacement promotion.
-3. Enumerate failures before and after subprocess completion, receipt parsing,
-   payload inspection, promotion, and manifest persistence. Determine what
-   remains diagnostic, durable, advertised, and reusable.
-4. Walk every resume validation branch. Distinguish obsolete/missing outcomes
-   that trigger rerun from unsafe conditions that must stop execution.
-5. Evaluate the fingerprint's intentionally observable and unobservable inputs
-   against documentation and force guidance.
-6. Review the dense validation code for named sub-decisions and comments while
-   preserving the visible security proof and check ordering.
-7. Confirm focused tests cover immediate reuse, cross-invocation reuse,
-   configuration change, payload tampering, provenance mismatch, symlinks/root
-   replacement, failure residue, and downstream invalidation at the correct
-   layers.
-
-### Validation
-
-```sh
-go test -count=1 ./internal/stage ./internal/artifacts ./internal/fileops ./internal/adapters/notarius ./internal/app
-```
-
-### Exit Gate
-
-- Cross-boundary scenario 3 is resolved, including transitive-input limits.
-- Promotion, advertisement, and resume each have a distinct authority and
-  failure conclusion.
-- Every proposed simplification states which security or compatibility checks
-  it preserves.
-
-## Stage 10: Audit Analyze And Artifact Dependencies
-
-### Entry
-
-- Stages 3, 6, 8, and 9 are complete.
-
-### Execute
-
-1. Trace all analyze source families from configuration validation through
-   runtime catalog registration, availability, resolution, Scriptorium
-   execution/reuse, materialization, metadata, and publish selection.
-2. Verify enabled, selected, executable, reused, generated, and unavailable
-   states are distinct and deterministic.
-3. Review configured-artifact dependency validation and runtime topological
-   ordering for cycles, missing dependencies, stable ordering, and consistency
-   between configuration and execution.
-4. Confirm required/optional behavior and guidance for built-in transcripts,
-   prepared stable inputs, configured artifacts, extraction sources, and
-   previous-session sources.
-5. Prove previous-session resolution is local-only during analyze and that
-   disabled artifacts are reused only under the documented conditions.
-6. Inspect repeated resolution branches, parameter width, nested lookup, and
-   ordering work for a smaller representation or indexed plan without merging
-   distinct source policies.
-7. Review tests for each state transition and source family at the narrowest
-   stable owner, noting semantic duplication across config, artifacts, stage,
-   publish, and assembled runner tests.
-
-### Validation
-
-```sh
-go test -count=1 ./internal/stage ./internal/artifacts ./internal/artifactpolicy ./internal/config ./internal/adapters/scriptorium ./internal/app
-```
-
-### Exit Gate
-
-- Cross-boundary scenario 9 is resolved for every source family and selection
-  state.
-- Dependency ordering and source availability have explicit determinism and
-  complexity conclusions.
-- Config, artifact-policy, catalog, stage, and publish ownership is unambiguous
-  or represented by an `ARC` finding.
-
-## Stage 11: Audit Duplication, Simplicity, Efficiency, And Comments
-
-### Entry
-
-- Behavior stages 2-10 are complete, so structural candidates can be judged
-  against known contracts.
-
-### Execute
-
-1. Rerun graph similarity, complexity, fan-in/fan-out, call-path, loop-depth,
-   scan-in-loop, and change-coupling analyses on production code. Add targeted
-   text/static searches for patterns the graph cannot represent.
-2. Revisit all `DUP`, `SIM`, `EFF`, and `COM` candidates collected earlier.
-   Search for additional occurrences and trace all callers before assigning an
-   owner.
-3. For duplication, classify coincidental syntax, shared mechanism, duplicated
-   policy, or deliberately explicit security/state logic. Propose only the
-   narrowest helper that improves ownership and comprehension.
-4. For complexity, sketch the smaller control flow or data model and verify it
-   leaves state transitions, validation order, and commit boundaries visible.
-5. For efficiency, state the input scale or call frequency, current and proposed
-   complexity/I/O behavior, expected benefit, and benchmark or measurement
-   needed. Reject micro-optimizations without a credible workload.
-6. Review standard-library usage, errors, slices/maps, allocations, copying,
-   sorting, serialization, filesystem passes, adapter initialization, remote
-   calls, goroutines/channels, and interface breadth across the complete codebase.
-7. Review comments only after simplification decisions. Recommend why-comments
-   for remaining invariants, compatibility limits, safety checks, partial
-   failure, and ordering; flag comments that restate code or no longer match it.
-8. Check dependencies and platform assumptions for clear correctness,
-   portability, complexity, or maintenance consequences.
-
-### Validation
-
-- Run focused package tests for any behavior used to disprove or confirm a
-  candidate.
-- Run existing benchmarks where relevant. Propose a benchmark rather than
-  inventing performance claims when representative measurement is absent.
-
-### Exit Gate
-
-- Every structural candidate is confirmed, rejected with a reason, or merged
-  into a stronger root-cause finding.
-- No helper recommendation creates a generic workflow abstraction or moves
-  policy into a low-level utility.
-- Every efficiency finding has a credible workload and validation method.
-- Every comment finding states the non-obvious rationale that should be
-  preserved.
-
-## Stage 12: Audit The Test Suite Against Policy
-
-### Entry
-
-- Stages 2-11 have populated the risk-to-test matrix and test observations.
-
-### Execute
-
-1. Complete the risk-to-test matrix. For every consequential invariant, list
-   the current tests, proper owner, protected defect, missing failure modes, and
-   overlap with other layers.
-2. Review tests by behavior cluster rather than filename: parsing/validation,
-   domain/state, filesystem, adapters, orchestration, CLI, integration, and
-   representative assembled workflows.
-3. Classify gaps for data integrity, destructive operations, compatibility,
-   security, concurrency, idempotency, recovery, cancellation, and partial
-   success. Confirm the gap is not credibly protected elsewhere.
-4. Classify redundancy and brittleness: private constants/defaults, exact error
-   wording, incidental formatting/paths, mock choreography, oversized
-   snapshots, helper-level duplication, and the same policy repeated across
-   layers.
-5. Review doubles using the policy order: real deterministic collaborator,
-   stateful fake, stub, then mock when interaction is contractual. Check that
-   fakes model the failure and state semantics used by the tests.
-6. Inspect test helpers and large test functions for simplification and
-   meaningful table-driven boundaries without creating a fixture framework
-   whose maintenance cost exceeds its value.
-7. Review determinism and isolation: credentials, network access, paid APIs,
-   environment, working directory, clocks, randomness, ports, temp paths,
-   process-global state, ordering, cleanup, and parallel execution.
-8. Use coverage to investigate consequential weak branches, not as a score.
-   Review heavily covered behavior for marginal-value duplication as well.
-9. Identify focused fuzz opportunities for parsers, YAML/JSON normalization,
-   source IDs, confined paths, remote/local mapping, and manifest decoding.
-10. Compare local requirements with `.woodpecker/` and other automation. Record
-    missing enforcement as a risk/cost decision, not an assumption that every
-    diagnostic command belongs in CI.
-11. Investigate order dependence and flakiness with bounded runs, recording
-    runtime and any reproducible seed:
-
-    ```sh
-    go test -shuffle=on -count=3 ./...
-    go test -race -shuffle=on -count=1 ./...
-    ```
-
-### Exit Gate
-
-- Every important risk has a sufficiency conclusion and one intended test
-  owner.
-- Every proposed test addition names the realistic defect and marginal value.
-- Every deletion/consolidation names the stronger remaining protection.
-- Default-suite determinism, offline behavior, runtime, flakiness, and CI
-  enforcement have explicit conclusions.
-
-## Stage 13: Synthesize And Close The Audit
-
-### Entry
-
-- Stages 0-12 meet their exit gates or have explicitly accepted limitations.
-
-### Execute
-
-1. Reconcile candidates and findings across stages. Merge shared root causes and
-   remove repeated symptoms while retaining all affected locations and
-   contracts.
-2. Recheck every confirmed finding against current source, callers, tests, and
-   canonical documentation. Downgrade or reject anything supported only by a
-   metric or hypothetical preference.
-3. Rank impact, likelihood, confidence, and remediation scope separately. Order
-   the recommended backlog by dependency: correctness/data safety first,
-   architectural ownership next, then simplification/duplication, tests,
-   efficiency, and comments where they remain necessary.
-4. Record positive conclusions for high-risk areas where the current design and
-   tests are sufficient. The report should not imply that only defective areas
-   were reviewed.
-5. Reconcile the area coverage ledger, lifecycle matrix, cross-boundary scenario
-   matrix, and risk-to-test matrix with the audit plan's completion criteria.
-6. Record any accepted risks, ambiguous contracts, environmental limitations,
-   and deferred investigations with an explicit rationale and owner.
-7. Check whether HEAD or the worktree changed since Stage 0. Rerun affected
-   stages or clearly pin the report to the original revision.
-8. Validate the report and roadmap document links and run `git diff --check`.
-   If implementation changed during the audit, rerun the full Stage 0 validation
-   baseline against the final audited revision.
-
-### Final Deliverable
-
-`docs/roadmap/audit-findings.md` must contain:
-
-- an executive assessment without unsupported quality scores;
-- the audited revision and validation baseline;
-- coverage and scenario completion summaries;
-- confirmed findings ordered by dependency and risk;
-- rejected candidate themes where their recurrence would otherwise waste work;
-- the test-suite sufficiency assessment;
-- positive conclusions and accepted risks; and
-- a recommended remediation order, without implementing the remediation.
-
-### Exit Gate
-
-- Every completion criterion in the audit plan is satisfied or explicitly
-  marked limited with rationale.
-- Every finding is evidence-backed, deduplicated, actionable, and assigned a
-  stable ID.
-- No production change is included in the audit output.
-- The report is sufficient to prepare a separate remediation sequence without
-  repeating discovery.

docs/roadmap/audit.md

@@ -1,104 +0,0 @@
-# Implementation Plan Summary
-
-This is a concise, plain-language summary of
-[`implementation.md`](implementation.md). It describes the intended real-world
-outcome of each stage without reproducing its implementation details.
-
-1. **Stage 1 — Collaborative workspace permissions:** Treat ordinary Narratio and
-   Notarius data as shareable and make managed workspaces group-writable, while
-   retaining private handling for API keys.
-2. **Stage 2 — Safe identifiers:** Reject campaign, session, run, artifact, and
-   source identifiers that could escape their intended filesystem namespace, and
-   use fuzz tests to cover platform-specific path tricks.
-3. **Stage 3 — Durable file replacement:** Consolidate duplicated atomic-write
-   functions into one shared mechanism that fully persists a replacement before
-   reporting success.
-4. **Stage 4 — Confined writes and downloads:** Rewrite destination mutations so
-   symlinks or concurrent directory replacement cannot redirect writes,
-   promotions, or downloads outside the intended root.
-5. **Stage 5 — Safe deletion and crash-recoverable locks:** Confine recursive
-   cleanup to its authorized root and replace stale lock-file existence checks
-   with operating-system locks released automatically after process death.
-6. **Stage 6 — Protected API-key reads:** Read API keys only from private,
-   bounded, regular files without following symlinks or exposing key material in
-   errors.
-7. **Stage 7 — Bounded external results:** Prevent external adapters from causing
-   memory or disk exhaustion by validating regular result files and enforcing
-   generous, clearly reported per-adapter size limits.
-8. **Stage 8 — Complete subprocess termination:** Ensure cancellation, timeout,
-   or a safety-limit failure terminates and reaps an external command's entire
-   process tree rather than only its parent process.
-9. **Stage 9 — Safe subprocess diagnostics:** Redact known credentials from
-   stdout/stderr, cap persisted diagnostics, and terminate runaway producers when
-   those caps are reached.
-10. **Stage 10 — Safe publish inputs:** Ensure publishing reads and uploads only
-    verified regular files declared within the selected run, even during
-    filesystem races.
-11. **Stage 11 — Consistent run identity:** Resolve one campaign/session/run
-    identity for an invocation, reject conflicting authorities, and prevent stale
-    identity fields from leaking into a later run.
-12. **Stage 12 — Reliable failure recording:** Consolidate terminal-failure
-    persistence so handled errors reliably update authoritative session state and
-    preserve any secondary persistence failures.
-13. **Stage 13 — Immutable remote-state model:** Define a versioned immutable
-    remote snapshot selected by a small pointer, while isolating old-format read
-    compatibility so it can be removed after migration.
-14. **Stage 14 — Transactional publication:** Upload and verify a complete
-    immutable snapshot before one final pointer change makes it current, using an
-    exact source-to-destination mapping instead of basename guesses.
-15. **Stage 15 — Safe remote locking and pagination:** Use provider-enforced
-    conditional writes so publishers cannot overwrite another owner's lock, and
-    fail instead of looping when object-store pagination stops making progress.
-16. **Stage 16 — Retryable cleanup:** Persist post-publication cleanup as a
-    durable obligation so interrupted or failed deletion is retried and never
-    mistaken for completed cleanup.
-17. **Stage 17 — Snapshot-consistent restore:** Make restore and status use one
-    selected immutable snapshot throughout the operation, and prevent `--force`
-    from overwriting unsafe directory or non-file conflicts.
-18. **Stage 18 — Race-safe, portable restore:** Serialize restore against runner
-    reuse, leave durable evidence of incomplete restores, and replace unsafe
-    producer-machine absolute paths with validated local references.
-19. **Stage 19 — Correct audio-cache reuse:** Reuse downloaded audio only when its
-    local bytes and recorded metadata match the selected remote object version.
-20. **Stage 20 — One previous-session resolver:** Give restore, prepare, run, and
-    dry-run one consistent view of required and optional previous-session inputs,
-    while avoiding ambiguous matches and duplicate downloads.
-21. **Stage 21 — Strict configuration:** Reject multiple YAML documents, invalid
-    durations, implicit storage backends, and unmet previous-session expectations,
-    while separating configuration tests by responsibility.
-22. **Stage 22 — Truthful product settings and temp-file ownership:** Remove
-    configuration fields that do nothing, reject unsupported notification
-    settings, and guarantee cleanup of remote-configuration temporary files.
-23. **Stage 23 — Streaming WhisperX transport:** Stream uploads instead of
-    buffering entire audio files, reject unsupported endpoint schemes, and make
-    retries, cancellation, fake-server recording, and race tests reliable.
-24. **Stage 24 — Correct prepare/transcribe transitions:** Prevent stale previous
-    data, cancelled or partial transcription work, and duplicate source identity
-    from being recorded as successful current output.
-25. **Stage 25 — Authoritative output paths:** Require adapters to honor the
-    stage-requested output destination and consolidate duplicate singleton
-    transcript resolution without confusing it with multi-source discovery.
-26. **Stage 26 — Shared extraction evidence:** Consolidate duplicated
-    extraction-bundle validation into one typed proof while allowing resume and
-    catalog consumers to apply their distinct policies.
-27. **Stage 27 — Transcript-aware extraction reuse:** Include the direct
-    transcript's identity in extraction freshness checks so changed input cannot
-    reuse stale structured artifacts.
-28. **Stage 28 — One effective artifact selection:** Resolve configured and
-    explicitly selected artifacts once, then use that same typed set for
-    prerequisites, extraction catalogs, analyze inputs, and execution planning.
-29. **Stage 29 — Predictable analyze planning:** Represent optional and required
-    analyze inputs explicitly, produce deterministic dependency errors, and give
-    operators correct remediation commands.
-30. **Stage 30 — Contract cleanup:** Remove dead or misleading interfaces and
-    helpers, move static Audita configuration to its proper owner, and correct
-    stale contract comments.
-31. **Stage 31 — Enforced automated validation:** Require tests, race checks, vet,
-    builds, and example validation for changes and releases, while consolidating
-    redundant broad tests without losing focused coverage.
-32. **Stage 32 — Documentation and closure:** Reconcile normative documentation
-    with the completed behavior and verify that every planned remediation has one
-    completed, traceable implementation stage.
-
-Every stage's purpose was readily determinable from the implementation plan; no
-stage required an uncertainty note.

docs/troubleshooting.md

@@ -299,7 +299,7 @@ Symptom:
 Likely causes:
 
 - another process is running for the same session;
-- stale lock left by interrupted process.
+- a process still holds the operating-system lock while it is shutting down.
 
 Diagnostics:
 
@@ -311,7 +311,8 @@ ps aux | grep narratio
 Safe fix:
 
 - wait for active process completion;
-- remove stale lock only after confirming no live process owns it.
+- retry after an interrupted holder has exited; the kernel releases its lock
+  even though the `.lock` metadata file remains for inspection.
 
 Relevant reference: [Operations: Local State Layout](./operations.md#local-state-layout).
 
@@ -435,7 +436,7 @@ Diagnostics:
 
 ```bash
 ls -la /path/to/secrets_dir
-env | grep -E 'OBJECT_STORAGE|AWS|AUDITA|SCRIPTORIUM'
+env | sed 's/=.*//' | grep -E 'OBJECT_STORAGE|AWS|AUDITA|SCRIPTORIUM'
 ```
 
 Safe fix:

examples/pipeline.full.annotated.yml

@@ -12,7 +12,7 @@ workspace:
 #   env_dir: ./secrets
 
 storage:
-  # Optional storage backend selector; use "s3" for publish + S3 audio workflows.
+  # Defaults to "local". Use "s3" explicitly for publish + S3 audio workflows.
   backend: s3
   s3:
     # Required when using S3 audio or S3 publish uploads.
@@ -260,7 +260,5 @@ scriptorium:
         output_kind: player_handout
 
 notification:
-  # Optional notification settings.
-  backend: ""
-  recipient: ""
-  timeout: 30s
+  # No delivery provider is currently implemented.
+  mode: noop

examples/pipeline.production.yml

@@ -125,4 +125,4 @@ scriptorium:
         output_kind: player_handout
 
 notification:
-  timeout: 30s
+  mode: noop

internal/adapters/audita/fake.go

@@ -4,10 +4,10 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
-	"os"
 	"path/filepath"
 
 	"gitea.maximumdirect.net/eric/narratio/internal/adapters/subprocess"
+	"gitea.maximumdirect.net/eric/narratio/internal/fileops"
 )
 
 // NoopRunner is a deterministic no-op audita adapter.
@@ -84,17 +84,17 @@ func materializePlaceholders(req PolishRequest) error {
 			"merged_transcript_path": req.MergedTranscriptPath,
 			"output_path":            req.OutputProcessedPath,
 		}
-		if err := subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, 0o644); err != nil {
+		if err := subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write generated config %q: %w", req.GeneratedConfigPath, err)
 		}
 	}
 	if req.StdoutLogPath != "" {
-		if err := subprocess.WriteFileAtomic(req.StdoutLogPath, []byte("audita noop/fake stdout placeholder\n"), 0o644); err != nil {
+		if err := subprocess.WriteFileAtomic(req.StdoutLogPath, []byte("audita noop/fake stdout placeholder\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write stdout log %q: %w", req.StdoutLogPath, err)
 		}
 	}
 	if req.StderrLogPath != "" {
-		if err := subprocess.WriteFileAtomic(req.StderrLogPath, []byte("audita noop/fake stderr placeholder\n"), 0o644); err != nil {
+		if err := subprocess.WriteFileAtomic(req.StderrLogPath, []byte("audita noop/fake stderr placeholder\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write stderr log %q: %w", req.StderrLogPath, err)
 		}
 	}
@@ -117,14 +117,14 @@ func writeJSONIfRequested(path string, payload any) error {
 	if path == "" {
 		return nil
 	}
-	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+	if err := fileops.EnsureWorkspaceDirectory(filepath.Dir(path)); err != nil {
 		return fmt.Errorf("create parent directory %q: %w", filepath.Dir(path), err)
 	}
 	data, err := json.Marshal(payload)
 	if err != nil {
 		return fmt.Errorf("marshal placeholder json for %q: %w", path, err)
 	}
-	if err := subprocess.WriteFileAtomic(path, data, 0o644); err != nil {
+	if err := subprocess.WriteFileAtomic(path, data, fileops.WorkspaceFileMode); err != nil {
 		return fmt.Errorf("write placeholder json %q: %w", path, err)
 	}
 	return nil

internal/adapters/audita/runner.go

@@ -6,8 +6,6 @@ import (
 	"time"
 )
 
-// TODO: implement a real Audita subprocess/service adapter.
-
 // Runner is the adapter boundary for audita polish invocations.
 type Runner interface {
 	Run(ctx context.Context, req PolishRequest) (PolishResult, error)
@@ -15,25 +13,15 @@ type Runner interface {
 
 // PolishRequest describes an audita invocation.
 type PolishRequest struct {
-	GeneratedConfigPath      string
-	MergedTranscriptPath     string
-	OutputProcessedPath      string
-	GlossaryPath             string
-	ReportPath               string
-	WorkDir                  string
-	Modules                  []string
-	BaseURL                  string
-	Model                    string
-	TranscriptDescription    string
-	ConfigPath               string
-	OutputSchema             string
-	WorkDirRetention         string
-	TotalLLMConcurrency      *int
-	ProposalLLMConcurrency   *int
-	ValidationModel          string
-	ValidationLLMConcurrency *int
-	StdoutLogPath            string
-	StderrLogPath            string
+	GeneratedConfigPath  string
+	MergedTranscriptPath string
+	OutputProcessedPath  string
+	GlossaryPath         string
+	ReportPath           string
+	WorkDir              string
+	Modules              []string
+	StdoutLogPath        string
+	StderrLogPath        string
 }
 
 // PolishResult describes a polish output.

internal/adapters/audita/subprocess.go

@@ -11,8 +11,15 @@ import (
 	"time"
 
 	"gitea.maximumdirect.net/eric/narratio/internal/adapters/subprocess"
+	"gitea.maximumdirect.net/eric/narratio/internal/fileops"
 )
 
+// MaxProcessedOutputBytes bounds Audita's processed-transcript JSON result.
+const MaxProcessedOutputBytes int64 = 64 * 1024 * 1024
+
+// MaxReportOutputBytes bounds Audita's optional report JSON result.
+const MaxReportOutputBytes int64 = 16 * 1024 * 1024
+
 // SubprocessRunnerConfig defines deterministic settings for Audita CLI execution.
 type SubprocessRunnerConfig struct {
 	Binary                   string
@@ -207,12 +214,13 @@ func (r *SubprocessRunner) Run(ctx context.Context, req PolishRequest) (PolishRe
 	}
 
 	runRes, err := subprocess.Run(ctx, subprocess.RunRequest{
-		Executable:    r.binary,
-		Args:          args,
-		Timeout:       r.timeout,
-		EnvOverrides:  env,
-		StdoutLogPath: req.StdoutLogPath,
-		StderrLogPath: req.StderrLogPath,
+		Executable:      r.binary,
+		Args:            args,
+		Timeout:         r.timeout,
+		EnvOverrides:    env,
+		DiagnosticOwner: "audita",
+		StdoutLogPath:   req.StdoutLogPath,
+		StderrLogPath:   req.StderrLogPath,
 	})
 	if err != nil {
 		wrappedMessage := fmt.Sprintf(
@@ -370,13 +378,13 @@ func (r *SubprocessRunner) writeInvocationConfig(req PolishRequest, args []strin
 		"credential_env_var":         r.llmAPIKeyEnv,
 		"credential_present":         credentialPresent,
 	}
-	return subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, 0o644)
+	return subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, fileops.WorkspaceFileMode)
 }
 
 func validateProcessedOutput(path string) error {
-	data, err := os.ReadFile(path)
+	data, err := readAuditaResult(path, MaxProcessedOutputBytes, "processed transcript")
 	if err != nil {
-		return fmt.Errorf("read file: %w", err)
+		return err
 	}
 
 	var payload map[string]any
@@ -405,9 +413,9 @@ func addSubprocessStreamHint(message string, runErr error) string {
 }
 
 func validateJSONFile(path string) error {
-	data, err := os.ReadFile(path)
+	data, err := readAuditaResult(path, MaxReportOutputBytes, "report")
 	if err != nil {
-		return fmt.Errorf("read file: %w", err)
+		return err
 	}
 	var v any
 	if err := json.Unmarshal(data, &v); err != nil {
@@ -415,3 +423,11 @@ func validateJSONFile(path string) error {
 	}
 	return nil
 }
+
+func readAuditaResult(path string, limit int64, category string) ([]byte, error) {
+	data, err := fileops.ReadRegularFile(path, limit)
+	if err != nil {
+		return nil, fmt.Errorf("audita %s result exceeds or cannot be read within %d-byte limit: %w", category, limit, err)
+	}
+	return data, nil
+}

internal/adapters/audita/subprocess_test.go

@@ -189,7 +189,7 @@ func TestSubprocessRunnerUnconfiguredCredentialEnvOmitsCredential(t *testing.T)
 	}
 }
 
-func TestSubprocessRunnerInheritsParentEnvironment(t *testing.T) {
+func TestSubprocessRunnerOmitsUnspecifiedParentEnvironment(t *testing.T) {
 	if runtime.GOOS == "windows" {
 		t.Skip("helper wrapper script uses /bin/sh")
 	}
@@ -214,8 +214,8 @@ func TestSubprocessRunnerInheritsParentEnvironment(t *testing.T) {
 	}
 
 	rec := readAuditaHelperRecord(t, recordPath)
-	if rec.Env["AUDITA_INHERITED_MARKER"] != "inherited-from-parent" {
-		t.Fatalf("AUDITA_INHERITED_MARKER = %q, want inherited-from-parent", rec.Env["AUDITA_INHERITED_MARKER"])
+	if rec.Env["AUDITA_INHERITED_MARKER"] != "" {
+		t.Fatalf("AUDITA_INHERITED_MARKER = %q, want omitted from the child environment", rec.Env["AUDITA_INHERITED_MARKER"])
 	}
 }
 

internal/adapters/notarius/subprocess.go

@@ -5,12 +5,12 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
-	"io"
 	"os"
 	"path/filepath"
 	"strings"
 
 	"gitea.maximumdirect.net/eric/narratio/internal/adapters/subprocess"
+	"gitea.maximumdirect.net/eric/narratio/internal/fileops"
 	"gitea.maximumdirect.net/eric/narratio/internal/pathsafe"
 )
 
@@ -53,12 +53,13 @@ func (r *SubprocessRunner) Run(ctx context.Context, req RunRequest) (RunResult,
 		"--json",
 	}
 	processResult, err := r.run(ctx, subprocess.RunRequest{
-		Executable:    req.Binary,
-		Args:          args,
-		WorkingDir:    req.WorkingDirectory,
-		Timeout:       req.Timeout,
-		StdoutLogPath: req.ReceiptPath,
-		StderrLogPath: req.LogPath,
+		Executable:      req.Binary,
+		Args:            args,
+		WorkingDir:      req.WorkingDirectory,
+		Timeout:         req.Timeout,
+		DiagnosticOwner: "notarius",
+		StdoutLogPath:   req.ReceiptPath,
+		StderrLogPath:   req.LogPath,
 	})
 	baseResult := RunResult{
 		ReceiptPath: req.ReceiptPath,
@@ -388,32 +389,9 @@ func loadWarnings(path string) ([]WarningSummary, error) {
 }
 
 func decodeBoundedJSON(path string, limit int64, destination any) error {
-	inspected, err := os.Lstat(path)
+	data, err := fileops.ReadRegularFile(path, limit)
 	if err != nil {
-		return err
-	}
-	if inspected.Mode()&os.ModeSymlink != 0 || !inspected.Mode().IsRegular() {
-		return fmt.Errorf("path %q must be a regular file without symlinks", path)
-	}
-	file, err := os.Open(path)
-	if err != nil {
-		return err
-	}
-	defer func() { _ = file.Close() }()
-	opened, err := file.Stat()
-	if err != nil {
-		return err
-	}
-	if !opened.Mode().IsRegular() || !os.SameFile(inspected, opened) {
-		return fmt.Errorf("file %q changed before it could be read", path)
-	}
-	reader := io.LimitReader(file, limit+1)
-	data, err := io.ReadAll(reader)
-	if err != nil {
-		return err
-	}
-	if int64(len(data)) > limit {
-		return fmt.Errorf("file %q exceeds %d-byte limit", path, limit)
+		return fmt.Errorf("notarius JSON result exceeds or cannot be read within %d-byte limit: %w", limit, err)
 	}
 	if err := json.Unmarshal(data, destination); err != nil {
 		return err

internal/adapters/notarius/subprocess_test.go

@@ -69,7 +69,7 @@ func TestSubprocessRunnerBuildsExactInvocationAndDiscoversBundle(t *testing.T) {
 	}
 }
 
-func TestSubprocessRunnerInheritsEnvironmentAndSeparatesStreams(t *testing.T) {
+func TestSubprocessRunnerUsesMinimalEnvironmentAndSeparatesStreams(t *testing.T) {
 	req := validRunRequest(t)
 	writeValidBundleAndReceipt(t, req, false)
 	receiptFixture := req.ReceiptPath + ".fixture"
@@ -103,7 +103,7 @@ cat "$NOTARIUS_RECEIPT_FIXTURE"
 		t.Fatalf("Run() error = %v", err)
 	}
 	assertTextFile(t, filepath.Join(captureDir, "working-directory"), req.WorkingDirectory+"\n")
-	assertTextFile(t, filepath.Join(captureDir, "environment"), "inherited-value")
+	assertTextFile(t, filepath.Join(captureDir, "environment"), "")
 	assertTextFile(t, req.LogPath, "diagnostic stream\n")
 	receiptBytes, err := os.ReadFile(req.ReceiptPath)
 	if err != nil {

internal/adapters/scriptorium/fake.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 
 	"gitea.maximumdirect.net/eric/narratio/internal/adapters/subprocess"
+	"gitea.maximumdirect.net/eric/narratio/internal/fileops"
 )
 
 // NoopRunner is a deterministic no-op scriptorium adapter.
@@ -142,7 +143,7 @@ func (f *FakeRunner) RenderArtifact(ctx context.Context, req RenderArtifactReque
 
 func materializeRunPlaceholders(req RunArtifactRequest) error {
 	if req.OutputPath != "" {
-		if err := subprocess.WriteFileAtomic(req.OutputPath, []byte("scriptorium noop/fake run artifact\n"), 0o644); err != nil {
+		if err := subprocess.WriteFileAtomic(req.OutputPath, []byte("scriptorium noop/fake run artifact\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write run output %q: %w", req.OutputPath, err)
 		}
 	}
@@ -154,17 +155,17 @@ func materializeRunPlaceholders(req RunArtifactRequest) error {
 			"prompt_id":   req.PromptID,
 			"output_path": req.OutputPath,
 		}
-		if err := subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, 0o644); err != nil {
+		if err := subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write generated config %q: %w", req.GeneratedConfigPath, err)
 		}
 	}
 	if req.StdoutLogPath != "" {
-		if err := subprocess.WriteFileAtomic(req.StdoutLogPath, []byte("scriptorium noop/fake run stdout placeholder\n"), 0o644); err != nil {
+		if err := subprocess.WriteFileAtomic(req.StdoutLogPath, []byte("scriptorium noop/fake run stdout placeholder\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write stdout log %q: %w", req.StdoutLogPath, err)
 		}
 	}
 	if req.StderrLogPath != "" {
-		if err := subprocess.WriteFileAtomic(req.StderrLogPath, []byte("scriptorium noop/fake run stderr placeholder\n"), 0o644); err != nil {
+		if err := subprocess.WriteFileAtomic(req.StderrLogPath, []byte("scriptorium noop/fake run stderr placeholder\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write stderr log %q: %w", req.StderrLogPath, err)
 		}
 	}
@@ -173,7 +174,7 @@ func materializeRunPlaceholders(req RunArtifactRequest) error {
 
 func materializeRenderPlaceholders(req RenderArtifactRequest) error {
 	if req.OutputPath != "" {
-		if err := subprocess.WriteFileAtomic(req.OutputPath, []byte("{\"schema\":\"scriptorium.render.v1\",\"placeholder\":true}\n"), 0o644); err != nil {
+		if err := subprocess.WriteFileAtomic(req.OutputPath, []byte("{\"schema\":\"scriptorium.render.v1\",\"placeholder\":true}\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write render output %q: %w", req.OutputPath, err)
 		}
 	}
@@ -185,17 +186,17 @@ func materializeRenderPlaceholders(req RenderArtifactRequest) error {
 			"prompt_id":   req.PromptID,
 			"output_path": req.OutputPath,
 		}
-		if err := subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, 0o644); err != nil {
+		if err := subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write generated config %q: %w", req.GeneratedConfigPath, err)
 		}
 	}
 	if req.StdoutLogPath != "" {
-		if err := subprocess.WriteFileAtomic(req.StdoutLogPath, []byte("scriptorium noop/fake render stdout placeholder\n"), 0o644); err != nil {
+		if err := subprocess.WriteFileAtomic(req.StdoutLogPath, []byte("scriptorium noop/fake render stdout placeholder\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write stdout log %q: %w", req.StdoutLogPath, err)
 		}
 	}
 	if req.StderrLogPath != "" {
-		if err := subprocess.WriteFileAtomic(req.StderrLogPath, []byte("scriptorium noop/fake render stderr placeholder\n"), 0o644); err != nil {
+		if err := subprocess.WriteFileAtomic(req.StderrLogPath, []byte("scriptorium noop/fake render stderr placeholder\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write stderr log %q: %w", req.StderrLogPath, err)
 		}
 	}

internal/adapters/scriptorium/subprocess.go

@@ -9,8 +9,12 @@ import (
 	"time"
 
 	"gitea.maximumdirect.net/eric/narratio/internal/adapters/subprocess"
+	"gitea.maximumdirect.net/eric/narratio/internal/fileops"
 )
 
+// MaxOutputFileBytes bounds one Scriptorium artifact result.
+const MaxOutputFileBytes int64 = 64 * 1024 * 1024
+
 // SubprocessRunner invokes Scriptorium through its public CLI.
 type SubprocessRunner struct{}
 
@@ -52,13 +56,17 @@ func (r *SubprocessRunner) RunArtifact(ctx context.Context, req RunArtifactReque
 		}
 	}
 
+	envOverrides, sensitiveNames := credentialEnvironment(req.APIKeyEnv)
 	runRes, runErr := subprocess.Run(ctx, subprocess.RunRequest{
-		Executable:    req.Binary,
-		Args:          args,
-		WorkingDir:    req.WorkingDir,
-		Timeout:       req.Timeout,
-		StdoutLogPath: req.StdoutLogPath,
-		StderrLogPath: req.StderrLogPath,
+		Executable:        req.Binary,
+		Args:              args,
+		WorkingDir:        req.WorkingDir,
+		Timeout:           req.Timeout,
+		EnvOverrides:      envOverrides,
+		SensitiveEnvNames: sensitiveNames,
+		DiagnosticOwner:   "scriptorium",
+		StdoutLogPath:     req.StdoutLogPath,
+		StderrLogPath:     req.StderrLogPath,
 	})
 
 	result := ArtifactResult{
@@ -134,13 +142,17 @@ func (r *SubprocessRunner) RenderArtifact(ctx context.Context, req RenderArtifac
 		}
 	}
 
+	envOverrides, sensitiveNames := credentialEnvironment(req.APIKeyEnv)
 	runRes, runErr := subprocess.Run(ctx, subprocess.RunRequest{
-		Executable:    req.Binary,
-		Args:          args,
-		WorkingDir:    req.WorkingDir,
-		Timeout:       req.Timeout,
-		StdoutLogPath: req.StdoutLogPath,
-		StderrLogPath: req.StderrLogPath,
+		Executable:        req.Binary,
+		Args:              args,
+		WorkingDir:        req.WorkingDir,
+		Timeout:           req.Timeout,
+		EnvOverrides:      envOverrides,
+		SensitiveEnvNames: sensitiveNames,
+		DiagnosticOwner:   "scriptorium",
+		StdoutLogPath:     req.StdoutLogPath,
+		StderrLogPath:     req.StderrLogPath,
 	})
 
 	result := ArtifactResult{
@@ -223,6 +235,15 @@ func validateCommonRunRequest(
 	return true, nil
 }
 
+func credentialEnvironment(apiKeyEnv string) (map[string]string, []string) {
+	name := strings.TrimSpace(apiKeyEnv)
+	if name == "" {
+		return nil, nil
+	}
+	value, _ := os.LookupEnv(name)
+	return map[string]string{name: value}, []string{name}
+}
+
 func buildRunArgs(req RunArtifactRequest) []string {
 	args := []string{"run", "--prompt", strings.TrimSpace(req.PromptID)}
 	if cfgPath := strings.TrimSpace(req.ConfigPath); cfgPath != "" {
@@ -321,18 +342,15 @@ func writeInvocationConfig(path string, payload invocationPayload) error {
 		"render_format":        payload.RenderFormat,
 		"render_prompt_logged": payload.RenderPromptStore,
 	}
-	return subprocess.WriteYAMLAtomic(path, data, 0o644)
+	return subprocess.WriteYAMLAtomic(path, data, fileops.WorkspaceFileMode)
 }
 
 func validateNonEmptyOutput(path string) error {
-	info, err := os.Stat(path)
+	data, err := fileops.ReadRegularFile(path, MaxOutputFileBytes)
 	if err != nil {
-		return fmt.Errorf("stat file: %w", err)
+		return fmt.Errorf("scriptorium artifact output exceeds or cannot be read within %d-byte limit: %w", MaxOutputFileBytes, err)
 	}
-	if info.IsDir() {
-		return fmt.Errorf("path is a directory")
-	}
-	if info.Size() <= 0 {
+	if len(data) == 0 {
 		return fmt.Errorf("file is empty")
 	}
 	return nil

internal/adapters/seriatim/fake.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 
 	"gitea.maximumdirect.net/eric/narratio/internal/adapters/subprocess"
+	"gitea.maximumdirect.net/eric/narratio/internal/fileops"
 )
 
 // NoopRunner is a deterministic no-op seriatim adapter.
@@ -260,7 +261,7 @@ func (f *FakeRunner) Render(ctx context.Context, req RenderRequest) (RenderResul
 
 func materializePlaceholders(req MergeRequest) error {
 	if req.OutputMergedTranscriptPath != "" {
-		if err := subprocess.WriteFileAtomic(req.OutputMergedTranscriptPath, []byte(`{"schema":"seriatim.intermediate.v1","segments":[]}`), 0o644); err != nil {
+		if err := subprocess.WriteFileAtomic(req.OutputMergedTranscriptPath, []byte(`{"schema":"seriatim.intermediate.v1","segments":[]}`), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write merged transcript %q: %w", req.OutputMergedTranscriptPath, err)
 		}
 	}
@@ -271,22 +272,22 @@ func materializePlaceholders(req MergeRequest) error {
 			"input_transcript_paths": req.InputTranscriptPaths,
 			"output_path":            req.OutputMergedTranscriptPath,
 		}
-		if err := subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, 0o644); err != nil {
+		if err := subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write generated config %q: %w", req.GeneratedConfigPath, err)
 		}
 	}
 	if req.StdoutLogPath != "" {
-		if err := subprocess.WriteFileAtomic(req.StdoutLogPath, []byte("seriatim noop/fake stdout placeholder\n"), 0o644); err != nil {
+		if err := subprocess.WriteFileAtomic(req.StdoutLogPath, []byte("seriatim noop/fake stdout placeholder\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write stdout log %q: %w", req.StdoutLogPath, err)
 		}
 	}
 	if req.StderrLogPath != "" {
-		if err := subprocess.WriteFileAtomic(req.StderrLogPath, []byte("seriatim noop/fake stderr placeholder\n"), 0o644); err != nil {
+		if err := subprocess.WriteFileAtomic(req.StderrLogPath, []byte("seriatim noop/fake stderr placeholder\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write stderr log %q: %w", req.StderrLogPath, err)
 		}
 	}
 	if req.ReportPath != "" {
-		if err := subprocess.WriteFileAtomic(req.ReportPath, []byte(`{"schema":"seriatim.report.v1","placeholder":true}`), 0o644); err != nil {
+		if err := subprocess.WriteFileAtomic(req.ReportPath, []byte(`{"schema":"seriatim.report.v1","placeholder":true}`), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write report %q: %w", req.ReportPath, err)
 		}
 	}
@@ -295,7 +296,7 @@ func materializePlaceholders(req MergeRequest) error {
 
 func materializeTrimPlaceholders(req TrimRequest) error {
 	if req.OutputTrimmedPath != "" {
-		if err := subprocess.WriteFileAtomic(req.OutputTrimmedPath, []byte(`{"schema":"seriatim.intermediate.v1","segments":[]}`), 0o644); err != nil {
+		if err := subprocess.WriteFileAtomic(req.OutputTrimmedPath, []byte(`{"schema":"seriatim.intermediate.v1","segments":[]}`), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write trimmed transcript %q: %w", req.OutputTrimmedPath, err)
 		}
 	}
@@ -308,17 +309,17 @@ func materializeTrimPlaceholders(req TrimRequest) error {
 			"output_path":   req.OutputTrimmedPath,
 			"keep_selector": req.KeepSelector,
 		}
-		if err := subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, 0o644); err != nil {
+		if err := subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write generated config %q: %w", req.GeneratedConfigPath, err)
 		}
 	}
 	if req.StdoutLogPath != "" {
-		if err := subprocess.WriteFileAtomic(req.StdoutLogPath, []byte("seriatim noop/fake trim stdout placeholder\n"), 0o644); err != nil {
+		if err := subprocess.WriteFileAtomic(req.StdoutLogPath, []byte("seriatim noop/fake trim stdout placeholder\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write stdout log %q: %w", req.StdoutLogPath, err)
 		}
 	}
 	if req.StderrLogPath != "" {
-		if err := subprocess.WriteFileAtomic(req.StderrLogPath, []byte("seriatim noop/fake trim stderr placeholder\n"), 0o644); err != nil {
+		if err := subprocess.WriteFileAtomic(req.StderrLogPath, []byte("seriatim noop/fake trim stderr placeholder\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write stderr log %q: %w", req.StderrLogPath, err)
 		}
 	}
@@ -327,7 +328,7 @@ func materializeTrimPlaceholders(req TrimRequest) error {
 
 func materializeNormalizePlaceholders(req NormalizeRequest) error {
 	if req.OutputNormalizedPath != "" {
-		if err := subprocess.WriteFileAtomic(req.OutputNormalizedPath, []byte(`{"schema":"seriatim.intermediate.v1","segments":[]}`), 0o644); err != nil {
+		if err := subprocess.WriteFileAtomic(req.OutputNormalizedPath, []byte(`{"schema":"seriatim.intermediate.v1","segments":[]}`), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write normalized transcript %q: %w", req.OutputNormalizedPath, err)
 		}
 	}
@@ -343,22 +344,22 @@ func materializeNormalizePlaceholders(req NormalizeRequest) error {
 		if req.ReportPath != "" {
 			payload["report_path"] = req.ReportPath
 		}
-		if err := subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, 0o644); err != nil {
+		if err := subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write generated config %q: %w", req.GeneratedConfigPath, err)
 		}
 	}
 	if req.StdoutLogPath != "" {
-		if err := subprocess.WriteFileAtomic(req.StdoutLogPath, []byte("seriatim noop/fake normalize stdout placeholder\n"), 0o644); err != nil {
+		if err := subprocess.WriteFileAtomic(req.StdoutLogPath, []byte("seriatim noop/fake normalize stdout placeholder\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write stdout log %q: %w", req.StdoutLogPath, err)
 		}
 	}
 	if req.StderrLogPath != "" {
-		if err := subprocess.WriteFileAtomic(req.StderrLogPath, []byte("seriatim noop/fake normalize stderr placeholder\n"), 0o644); err != nil {
+		if err := subprocess.WriteFileAtomic(req.StderrLogPath, []byte("seriatim noop/fake normalize stderr placeholder\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write stderr log %q: %w", req.StderrLogPath, err)
 		}
 	}
 	if req.ReportPath != "" {
-		if err := subprocess.WriteFileAtomic(req.ReportPath, []byte(`{"schema":"seriatim.report.v1","placeholder":true}`), 0o644); err != nil {
+		if err := subprocess.WriteFileAtomic(req.ReportPath, []byte(`{"schema":"seriatim.report.v1","placeholder":true}`), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write report %q: %w", req.ReportPath, err)
 		}
 	}
@@ -367,7 +368,7 @@ func materializeNormalizePlaceholders(req NormalizeRequest) error {
 
 func materializeRenderPlaceholders(req RenderRequest) error {
 	if req.OutputRenderedPath != "" {
-		if err := subprocess.WriteFileAtomic(req.OutputRenderedPath, []byte("# Transcript\n\nRendered markdown placeholder.\n"), 0o644); err != nil {
+		if err := subprocess.WriteFileAtomic(req.OutputRenderedPath, []byte("# Transcript\n\nRendered markdown placeholder.\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write rendered transcript %q: %w", req.OutputRenderedPath, err)
 		}
 	}
@@ -384,17 +385,17 @@ func materializeRenderPlaceholders(req RenderRequest) error {
 			"include_segment_ids": req.IncludeSegmentIDs,
 			"include_metadata":    req.IncludeMetadata,
 		}
-		if err := subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, 0o644); err != nil {
+		if err := subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write generated config %q: %w", req.GeneratedConfigPath, err)
 		}
 	}
 	if req.StdoutLogPath != "" {
-		if err := subprocess.WriteFileAtomic(req.StdoutLogPath, []byte("seriatim noop/fake render stdout placeholder\n"), 0o644); err != nil {
+		if err := subprocess.WriteFileAtomic(req.StdoutLogPath, []byte("seriatim noop/fake render stdout placeholder\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write stdout log %q: %w", req.StdoutLogPath, err)
 		}
 	}
 	if req.StderrLogPath != "" {
-		if err := subprocess.WriteFileAtomic(req.StderrLogPath, []byte("seriatim noop/fake render stderr placeholder\n"), 0o644); err != nil {
+		if err := subprocess.WriteFileAtomic(req.StderrLogPath, []byte("seriatim noop/fake render stderr placeholder\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write stderr log %q: %w", req.StderrLogPath, err)
 		}
 	}

internal/adapters/seriatim/subprocess.go

@@ -4,15 +4,18 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
-	"os"
 	"strconv"
 	"strings"
 	"time"
 	"unicode/utf8"
 
 	"gitea.maximumdirect.net/eric/narratio/internal/adapters/subprocess"
+	"gitea.maximumdirect.net/eric/narratio/internal/fileops"
 )
 
+// MaxOutputFileBytes bounds each Seriatim JSON or rendered-text result.
+const MaxOutputFileBytes int64 = 64 * 1024 * 1024
+
 // EnvConfig defines optional Seriatim environment tuning values.
 type EnvConfig struct {
 	OverlapWordRunGap           *float64
@@ -129,12 +132,13 @@ func (r *SubprocessRunner) Run(ctx context.Context, req MergeRequest) (MergeResu
 	}
 
 	runRes, err := subprocess.Run(ctx, subprocess.RunRequest{
-		Executable:    r.binary,
-		Args:          args,
-		Timeout:       r.timeout,
-		EnvOverrides:  env,
-		StdoutLogPath: req.StdoutLogPath,
-		StderrLogPath: req.StderrLogPath,
+		Executable:      r.binary,
+		Args:            args,
+		Timeout:         r.timeout,
+		EnvOverrides:    env,
+		DiagnosticOwner: "seriatim",
+		StdoutLogPath:   req.StdoutLogPath,
+		StderrLogPath:   req.StderrLogPath,
 	})
 	if err != nil {
 		return MergeResult{
@@ -232,11 +236,12 @@ func (r *SubprocessRunner) Trim(ctx context.Context, req TrimRequest) (TrimResul
 	}
 
 	runRes, err := subprocess.Run(ctx, subprocess.RunRequest{
-		Executable:    binary,
-		Args:          args,
-		Timeout:       timeout,
-		StdoutLogPath: req.StdoutLogPath,
-		StderrLogPath: req.StderrLogPath,
+		Executable:      binary,
+		Args:            args,
+		Timeout:         timeout,
+		DiagnosticOwner: "seriatim",
+		StdoutLogPath:   req.StdoutLogPath,
+		StderrLogPath:   req.StderrLogPath,
 	})
 	if err != nil {
 		return TrimResult{
@@ -320,11 +325,12 @@ func (r *SubprocessRunner) Normalize(ctx context.Context, req NormalizeRequest)
 	}
 
 	runRes, err := subprocess.Run(ctx, subprocess.RunRequest{
-		Executable:    binary,
-		Args:          args,
-		Timeout:       timeout,
-		StdoutLogPath: req.StdoutLogPath,
-		StderrLogPath: req.StderrLogPath,
+		Executable:      binary,
+		Args:            args,
+		Timeout:         timeout,
+		DiagnosticOwner: "seriatim",
+		StdoutLogPath:   req.StdoutLogPath,
+		StderrLogPath:   req.StderrLogPath,
 	})
 	if err != nil {
 		return NormalizeResult{
@@ -425,11 +431,12 @@ func (r *SubprocessRunner) Render(ctx context.Context, req RenderRequest) (Rende
 	}
 
 	runRes, err := subprocess.Run(ctx, subprocess.RunRequest{
-		Executable:    binary,
-		Args:          args,
-		Timeout:       timeout,
-		StdoutLogPath: req.StdoutLogPath,
-		StderrLogPath: req.StderrLogPath,
+		Executable:      binary,
+		Args:            args,
+		Timeout:         timeout,
+		DiagnosticOwner: "seriatim",
+		StdoutLogPath:   req.StdoutLogPath,
+		StderrLogPath:   req.StderrLogPath,
 	})
 	if err != nil {
 		return RenderResult{
@@ -546,7 +553,7 @@ func (r *SubprocessRunner) writeMergeInvocationConfig(req MergeRequest, args []s
 		payload["coalesce_gap"] = *r.coalesceGap
 	}
 
-	return subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, 0o644)
+	return subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, fileops.WorkspaceFileMode)
 }
 
 func buildTrimArgs(req TrimRequest) []string {
@@ -598,7 +605,7 @@ func writeTrimInvocationConfig(req TrimRequest, args []string, binary string, ti
 		"output_path":   req.OutputTrimmedPath,
 		"keep_selector": req.KeepSelector,
 	}
-	return subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, 0o644)
+	return subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, fileops.WorkspaceFileMode)
 }
 
 func writeNormalizeInvocationConfig(req NormalizeRequest, args []string, binary string, timeout time.Duration, outputSchema string) error {
@@ -613,7 +620,7 @@ func writeNormalizeInvocationConfig(req NormalizeRequest, args []string, binary
 		"output_schema": outputSchema,
 		"report_path":   req.ReportPath,
 	}
-	return subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, 0o644)
+	return subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, fileops.WorkspaceFileMode)
 }
 
 func writeRenderInvocationConfig(req RenderRequest, args []string, binary string, timeout time.Duration, format string) error {
@@ -631,13 +638,13 @@ func writeRenderInvocationConfig(req RenderRequest, args []string, binary string
 		"include_segment_ids": req.IncludeSegmentIDs,
 		"include_metadata":    req.IncludeMetadata,
 	}
-	return subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, 0o644)
+	return subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, fileops.WorkspaceFileMode)
 }
 
 func validateJSONFile(path string) error {
-	data, err := os.ReadFile(path)
+	data, err := readSeriatimResult(path, "JSON output")
 	if err != nil {
-		return fmt.Errorf("read file: %w", err)
+		return err
 	}
 	var v any
 	if err := json.Unmarshal(data, &v); err != nil {
@@ -647,9 +654,9 @@ func validateJSONFile(path string) error {
 }
 
 func validateJSONFileWithSegments(path string) error {
-	data, err := os.ReadFile(path)
+	data, err := readSeriatimResult(path, "transcript JSON output")
 	if err != nil {
-		return fmt.Errorf("read file: %w", err)
+		return err
 	}
 
 	var payload map[string]any
@@ -668,9 +675,9 @@ func validateJSONFileWithSegments(path string) error {
 }
 
 func validateNonEmptyTextFile(path string) error {
-	data, err := os.ReadFile(path)
+	data, err := readSeriatimResult(path, "rendered text output")
 	if err != nil {
-		return fmt.Errorf("read file: %w", err)
+		return err
 	}
 	if len(data) == 0 {
 		return fmt.Errorf("file is empty")
@@ -683,3 +690,11 @@ func validateNonEmptyTextFile(path string) error {
 	}
 	return nil
 }
+
+func readSeriatimResult(path, category string) ([]byte, error) {
+	data, err := fileops.ReadRegularFile(path, MaxOutputFileBytes)
+	if err != nil {
+		return nil, fmt.Errorf("seriatim %s exceeds or cannot be read within %d-byte limit: %w", category, MaxOutputFileBytes, err)
+	}
+	return data, nil
+}

internal/adapters/storage/bounded_read.go

@@ -0,0 +1,90 @@
+package storage
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"math"
+	"strings"
+)
+
+// ReadLimitError reports that a remote object exceeded its caller-owned read
+// limit. The limit is enforced against both available object metadata and the
+// bytes returned by the opened object body.
+type ReadLimitError struct {
+	Key      string
+	Limit    int64
+	Observed int64
+}
+
+func (e *ReadLimitError) Error() string {
+	return fmt.Sprintf("object %q exceeds %d-byte read limit (observed at least %d bytes)", e.Key, e.Limit, e.Observed)
+}
+
+// ReadObjectBounded opens one object version and retains at most maxBytes of
+// its content. Object metadata may reject an oversized body early, but a
+// limit-plus-one read always enforces the boundary when transfer begins.
+func ReadObjectBounded(ctx context.Context, store ObjectStore, key string, maxBytes int64) (info ObjectInfo, data []byte, err error) {
+	key = strings.TrimSpace(key)
+	if store == nil {
+		return ObjectInfo{}, nil, fmt.Errorf("read bounded object: store is required")
+	}
+	if key == "" {
+		return ObjectInfo{}, nil, fmt.Errorf("read bounded object: key is required")
+	}
+	if maxBytes <= 0 || maxBytes == math.MaxInt64 {
+		return ObjectInfo{}, nil, fmt.Errorf("read bounded object %q: limit must be between 1 and %d bytes", key, int64(math.MaxInt64-1))
+	}
+	if err := ctx.Err(); err != nil {
+		return ObjectInfo{}, nil, err
+	}
+
+	info, body, err := store.Read(ctx, key)
+	if err != nil {
+		return ObjectInfo{}, nil, err
+	}
+	if body == nil {
+		return ObjectInfo{}, nil, fmt.Errorf("read bounded object %q: store returned no body", key)
+	}
+	defer func() {
+		if closeErr := body.Close(); closeErr != nil {
+			data = nil
+			err = errors.Join(err, fmt.Errorf("close object %q: %w", key, closeErr))
+		}
+	}()
+
+	if info.Size > maxBytes {
+		return info, nil, &ReadLimitError{Key: key, Limit: maxBytes, Observed: info.Size}
+	}
+
+	data, err = io.ReadAll(io.LimitReader(contextReader{ctx: ctx, reader: body}, maxBytes+1))
+	if err != nil {
+		return info, nil, err
+	}
+	if err := ctx.Err(); err != nil {
+		return info, nil, err
+	}
+	if int64(len(data)) > maxBytes {
+		return info, nil, &ReadLimitError{Key: key, Limit: maxBytes, Observed: int64(len(data))}
+	}
+	return info, data, nil
+}
+
+type contextReader struct {
+	ctx    context.Context
+	reader io.Reader
+}
+
+func (r contextReader) Read(p []byte) (int, error) {
+	if err := r.ctx.Err(); err != nil {
+		return 0, err
+	}
+	n, err := r.reader.Read(p)
+	if err == nil {
+		if contextErr := r.ctx.Err(); contextErr != nil {
+			return n, contextErr
+		}
+	}
+	return n, err
+}

internal/adapters/storage/bounded_read_test.go

@@ -0,0 +1,135 @@
+package storage
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"testing"
+)
+
+func TestReadObjectBoundedAcceptsExactLimitWithAbsentSizeMetadata(t *testing.T) {
+	body := &trackingReadCloser{reader: bytes.NewReader([]byte("12345678")), chunkSize: 2}
+	store := &boundedReadStore{read: func(context.Context, string) (ObjectInfo, io.ReadCloser, error) {
+		return ObjectInfo{Key: "control.json", ETag: "generation"}, body, nil
+	}}
+
+	info, data, err := ReadObjectBounded(context.Background(), store, "control.json", 8)
+	if err != nil {
+		t.Fatalf("ReadObjectBounded() error = %v", err)
+	}
+	if string(data) != "12345678" || info.ETag != "generation" {
+		t.Fatalf("ReadObjectBounded() = (%#v, %q), want opened object metadata and bytes", info, data)
+	}
+	if !body.closed {
+		t.Fatal("object body was not closed")
+	}
+}
+
+func TestReadObjectBoundedRejectsLimitPlusOneDespiteMissingOrInaccurateMetadata(t *testing.T) {
+	tests := []struct {
+		name         string
+		metadataSize int64
+	}{
+		{name: "missing", metadataSize: 0},
+		{name: "inaccurate", metadataSize: 2},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			body := &trackingReadCloser{reader: bytes.NewReader([]byte("123456789")), chunkSize: 1}
+			store := &boundedReadStore{read: func(context.Context, string) (ObjectInfo, io.ReadCloser, error) {
+				return ObjectInfo{Key: "control.json", Size: test.metadataSize}, body, nil
+			}}
+
+			_, data, err := ReadObjectBounded(context.Background(), store, "control.json", 8)
+			var limitErr *ReadLimitError
+			if !errors.As(err, &limitErr) {
+				t.Fatalf("ReadObjectBounded() error = %v, want ReadLimitError", err)
+			}
+			if data != nil || body.bytesRead != 9 || !body.closed {
+				t.Fatalf("data=%q bytes read=%d closed=%t, want nil, 9, true", data, body.bytesRead, body.closed)
+			}
+		})
+	}
+}
+
+func TestReadObjectBoundedRejectsOversizedMetadataBeforeTransfer(t *testing.T) {
+	body := &trackingReadCloser{reader: bytes.NewReader([]byte("small"))}
+	store := &boundedReadStore{read: func(context.Context, string) (ObjectInfo, io.ReadCloser, error) {
+		return ObjectInfo{Key: "control.json", Size: 9}, body, nil
+	}}
+
+	_, _, err := ReadObjectBounded(context.Background(), store, "control.json", 8)
+	var limitErr *ReadLimitError
+	if !errors.As(err, &limitErr) {
+		t.Fatalf("ReadObjectBounded() error = %v, want ReadLimitError", err)
+	}
+	if body.bytesRead != 0 || !body.closed {
+		t.Fatalf("bytes read=%d closed=%t, want zero-byte transfer and closed body", body.bytesRead, body.closed)
+	}
+}
+
+func TestReadObjectBoundedPropagatesCancellationAndClosesBody(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	body := &trackingReadCloser{reader: bytes.NewReader([]byte("12345678")), chunkSize: 1, afterRead: cancel}
+	store := &boundedReadStore{read: func(context.Context, string) (ObjectInfo, io.ReadCloser, error) {
+		return ObjectInfo{Key: "control.json"}, body, nil
+	}}
+
+	_, data, err := ReadObjectBounded(ctx, store, "control.json", 8)
+	if !errors.Is(err, context.Canceled) {
+		t.Fatalf("ReadObjectBounded() error = %v, want context cancellation", err)
+	}
+	if data != nil || body.bytesRead != 1 || !body.closed {
+		t.Fatalf("data=%q bytes read=%d closed=%t, want nil, 1, true", data, body.bytesRead, body.closed)
+	}
+}
+
+func TestReadObjectBoundedReturnsCloseFailure(t *testing.T) {
+	closeErr := errors.New("close failed")
+	body := &trackingReadCloser{reader: bytes.NewReader([]byte("ok")), closeErr: closeErr}
+	store := &boundedReadStore{read: func(context.Context, string) (ObjectInfo, io.ReadCloser, error) {
+		return ObjectInfo{Key: "control.json", Size: 2}, body, nil
+	}}
+
+	_, data, err := ReadObjectBounded(context.Background(), store, "control.json", 8)
+	if !errors.Is(err, closeErr) || data != nil || !body.closed {
+		t.Fatalf("data=%q error=%v closed=%t, want close failure and no retained data", data, err, body.closed)
+	}
+}
+
+type boundedReadStore struct {
+	ObjectStore
+	read func(context.Context, string) (ObjectInfo, io.ReadCloser, error)
+}
+
+func (s *boundedReadStore) Read(ctx context.Context, key string) (ObjectInfo, io.ReadCloser, error) {
+	return s.read(ctx, key)
+}
+
+type trackingReadCloser struct {
+	reader    io.Reader
+	chunkSize int
+	afterRead func()
+	closeErr  error
+	bytesRead int
+	closed    bool
+}
+
+func (r *trackingReadCloser) Read(p []byte) (int, error) {
+	if r.chunkSize > 0 && len(p) > r.chunkSize {
+		p = p[:r.chunkSize]
+	}
+	n, err := r.reader.Read(p)
+	r.bytesRead += n
+	if n > 0 && r.afterRead != nil {
+		r.afterRead()
+		r.afterRead = nil
+	}
+	return n, err
+}
+
+func (r *trackingReadCloser) Close() error {
+	r.closed = true
+	return r.closeErr
+}

internal/adapters/storage/download_writer.go

@@ -0,0 +1,23 @@
+package storage
+
+import (
+	"context"
+	"fmt"
+	"io"
+)
+
+// WriterDownloader is implemented by storage backends that stream an object
+// into a caller-owned file handle.
+type WriterDownloader interface {
+	DownloadTo(ctx context.Context, key string, destination io.Writer) error
+}
+
+// DownloadTo streams one object into destination. Destination-confined callers
+// require this capability rather than granting a backend a mutable pathname.
+func DownloadTo(ctx context.Context, store ObjectStore, key string, destination io.Writer) error {
+	writer, ok := store.(WriterDownloader)
+	if !ok {
+		return fmt.Errorf("object store does not support handle-confined downloads")
+	}
+	return writer.DownloadTo(ctx, key, destination)
+}

internal/adapters/storage/factory.go

@@ -14,16 +14,15 @@ func NewObjectStoreFromConfig(ctx context.Context, cfg *config.Config) (ObjectSt
 		return nil, fmt.Errorf("pipeline config is required")
 	}
 
-	if strings.EqualFold(strings.TrimSpace(cfg.Pipeline.Storage.Backend), "s3") {
+	switch strings.ToLower(strings.TrimSpace(cfg.Pipeline.Storage.Backend)) {
+	case config.StorageBackendS3:
 		if cfg.Pipeline.Storage.S3 == nil {
 			return nil, fmt.Errorf("pipeline.storage.s3 is required when pipeline.storage.backend is s3")
 		}
 		return NewS3BackendFromConfig(ctx, *cfg.Pipeline.Storage.S3)
+	case "", config.StorageBackendLocal:
+		return nil, fmt.Errorf("no remote object store backend is configured")
+	default:
+		return nil, fmt.Errorf("unsupported pipeline.storage.backend %q", cfg.Pipeline.Storage.Backend)
 	}
-
-	if cfg.Pipeline.Storage.S3 != nil && strings.TrimSpace(cfg.Pipeline.Storage.S3.Bucket) != "" {
-		return NewS3BackendFromConfig(ctx, *cfg.Pipeline.Storage.S3)
-	}
-
-	return nil, fmt.Errorf("no remote object store backend is configured")
 }

internal/adapters/storage/factory_test.go

@@ -54,3 +54,35 @@ func TestNewObjectStoreFromConfigNoRemoteBackendConfigured(t *testing.T) {
 		t.Fatalf("NewObjectStoreFromConfig() error = %v, want no-backend error", err)
 	}
 }
+
+func TestNewObjectStoreFromConfigDoesNotInferS3FromProviderFields(t *testing.T) {
+	called := false
+	original := newS3Client
+	t.Cleanup(func() { newS3Client = original })
+	newS3Client = func(_ context.Context, _ s3ClientOptions) (s3API, error) {
+		called = true
+		return &fakeS3API{}, nil
+	}
+
+	_, err := NewObjectStoreFromConfig(context.Background(), &config.Config{
+		Pipeline: &config.PipelineConfig{Storage: config.StorageConfig{
+			Backend: config.StorageBackendLocal,
+			S3:      &config.StorageS3Config{Bucket: "my-archive"},
+		}},
+	})
+	if err == nil || !strings.Contains(err.Error(), "no remote object store backend is configured") {
+		t.Fatalf("NewObjectStoreFromConfig() error = %v, want no-backend error", err)
+	}
+	if called {
+		t.Fatal("NewObjectStoreFromConfig() constructed S3 from incidental provider fields")
+	}
+}
+
+func TestNewObjectStoreFromConfigRejectsUnknownBackend(t *testing.T) {
+	_, err := NewObjectStoreFromConfig(context.Background(), &config.Config{
+		Pipeline: &config.PipelineConfig{Storage: config.StorageConfig{Backend: "s33"}},
+	})
+	if err == nil || !strings.Contains(err.Error(), "unsupported pipeline.storage.backend") {
+		t.Fatalf("NewObjectStoreFromConfig() error = %v, want unsupported-backend error", err)
+	}
+}

internal/adapters/storage/fake.go

@@ -1,25 +1,35 @@
 package storage
 
 import (
+	"bytes"
 	"context"
+	"crypto/sha256"
+	"encoding/hex"
 	"fmt"
+	"io"
 	"os"
 	"path/filepath"
 	"sort"
 	"strings"
+	"sync"
 	"time"
 )
 
 // FakeBackend provides a deterministic in-memory object store for tests.
 type FakeBackend struct {
+	mu sync.RWMutex
+
 	Objects   map[string]FakeObject
 	Uploads   []FakeUploadCall
 	Downloads []FakeDownloadCall
+	Reads     []FakeReadCall
 
-	ListErr     error
-	DownloadErr error
-	UploadErr   error
-	ExistsErr   error
+	ListErr      error
+	DownloadErr  error
+	UploadErr    error
+	ExistsErr    error
+	UploadHook   func(FakeUploadCall) error
+	DownloadHook func(FakeDownloadCall) error
 }
 
 // FakeUploadCall captures one upload invocation in call order.
@@ -33,6 +43,12 @@ type FakeUploadCall struct {
 type FakeDownloadCall struct {
 	Key       string
 	LocalPath string
+	Bytes     int64
+}
+
+// FakeReadCall captures one opened object in call order.
+type FakeReadCall struct {
+	Key string
 }
 
 // FakeObject is a deterministic fake object-store record.
@@ -46,6 +62,12 @@ type FakeObject struct {
 
 // SeedObject inserts or replaces an object in the fake object store.
 func (f *FakeBackend) SeedObject(obj FakeObject) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.seedObject(obj)
+}
+
+func (f *FakeBackend) seedObject(obj FakeObject) {
 	if f.Objects == nil {
 		f.Objects = map[string]FakeObject{}
 	}
@@ -53,6 +75,9 @@ func (f *FakeBackend) SeedObject(obj FakeObject) {
 	obj.Key = key
 	obj.Data = append([]byte(nil), obj.Data...)
 	obj.Metadata = copyMetadata(obj.Metadata)
+	if obj.ETag == "" {
+		obj.ETag = fakeObjectETag(obj.Data)
+	}
 	f.Objects[key] = obj
 }
 
@@ -65,6 +90,8 @@ func (f *FakeBackend) List(ctx context.Context, prefix string) ([]ObjectInfo, er
 		return nil, f.ListErr
 	}
 
+	f.mu.RLock()
+	defer f.mu.RUnlock()
 	normalizedPrefix := normalizeObjectKey(prefix)
 	keys := make([]string, 0, len(f.Objects))
 	for key := range f.Objects {
@@ -87,34 +114,77 @@ func (f *FakeBackend) List(ctx context.Context, prefix string) ([]ObjectInfo, er
 	return out, nil
 }
 
-// Download writes one object to a local path.
-func (f *FakeBackend) Download(ctx context.Context, key, localPath string) error {
+// Read returns a stable object body and the generation observed with it.
+func (f *FakeBackend) Read(ctx context.Context, key string) (ObjectInfo, io.ReadCloser, error) {
+	if err := ctx.Err(); err != nil {
+		return ObjectInfo{}, nil, err
+	}
+	if f.DownloadErr != nil {
+		return ObjectInfo{}, nil, f.DownloadErr
+	}
+	normalizedKey := normalizeObjectKey(key)
+	f.mu.RLock()
+	obj, ok := f.Objects[normalizedKey]
+	if ok {
+		obj.Data = append([]byte(nil), obj.Data...)
+		obj.Metadata = copyMetadata(obj.Metadata)
+	}
+	f.mu.RUnlock()
+	if !ok {
+		return ObjectInfo{}, nil, fmt.Errorf("read object %q: %w", normalizedKey, os.ErrNotExist)
+	}
+	f.mu.Lock()
+	f.Reads = append(f.Reads, FakeReadCall{Key: normalizedKey})
+	f.mu.Unlock()
+	return ObjectInfo{Key: obj.Key, Size: int64(len(obj.Data)), ETag: obj.ETag, LastModified: obj.LastModified}, io.NopCloser(bytes.NewReader(obj.Data)), nil
+}
+
+// DownloadTo writes one object to a caller-owned destination writer.
+func (f *FakeBackend) DownloadTo(ctx context.Context, key string, destination io.Writer) error {
 	if err := ctx.Err(); err != nil {
 		return err
 	}
 	if f.DownloadErr != nil {
 		return f.DownloadErr
 	}
+	if destination == nil {
+		return fmt.Errorf("download object: destination writer is required")
+	}
+	if f.DownloadHook != nil {
+		if err := f.DownloadHook(FakeDownloadCall{Key: normalizeObjectKey(key)}); err != nil {
+			return err
+		}
+	}
+
+	_, source, err := f.Read(ctx, key)
+	if err != nil {
+		return err
+	}
+	defer source.Close()
+	count, err := io.Copy(destination, source)
+	if err != nil {
+		return fmt.Errorf("download object %q: write destination: %w", key, err)
+	}
+	f.mu.Lock()
+	f.Downloads = append(f.Downloads, FakeDownloadCall{Key: normalizeObjectKey(key), Bytes: count})
+	f.mu.Unlock()
+	return nil
+}
+
+// Download writes one object to a local path.
+func (f *FakeBackend) Download(ctx context.Context, key, localPath string) error {
 	if strings.TrimSpace(localPath) == "" {
 		return fmt.Errorf("download object: local path is required")
 	}
-
-	obj, ok := f.Objects[normalizeObjectKey(key)]
-	if !ok {
-		return fmt.Errorf("download object %q: %w", key, os.ErrNotExist)
-	}
-	f.Downloads = append(f.Downloads, FakeDownloadCall{
-		Key:       normalizeObjectKey(key),
-		LocalPath: localPath,
-	})
-
 	if err := os.MkdirAll(filepath.Dir(localPath), 0o755); err != nil {
 		return fmt.Errorf("download object %q: create parent directory: %w", key, err)
 	}
-	if err := os.WriteFile(localPath, obj.Data, 0o644); err != nil {
-		return fmt.Errorf("download object %q: write local file: %w", key, err)
+	destination, err := os.Create(localPath)
+	if err != nil {
+		return fmt.Errorf("download object %q: create local file: %w", key, err)
 	}
-	return nil
+	defer destination.Close()
+	return f.DownloadTo(ctx, key, destination)
 }
 
 // Upload reads a local file and stores it under key.
@@ -132,33 +202,117 @@ func (f *FakeBackend) Upload(ctx context.Context, localPath, key string, opts Up
 		return ObjectInfo{}, fmt.Errorf("upload object: key is required")
 	}
 
-	data, err := os.ReadFile(localPath)
+	file, err := os.Open(localPath)
+	if err != nil {
+		return ObjectInfo{}, fmt.Errorf("upload object %q from %q: %w", key, localPath, err)
+	}
+	defer file.Close()
+	return f.uploadReader(ctx, file, key, opts, localPath)
+}
+
+// UploadReader stores content provided by a caller-owned reader.
+func (f *FakeBackend) UploadReader(ctx context.Context, source io.Reader, key string, opts UploadOptions) (ObjectInfo, error) {
+	return f.uploadReader(ctx, source, key, opts, "reader")
+}
+
+func (f *FakeBackend) uploadReader(ctx context.Context, source io.Reader, key string, opts UploadOptions, localPath string) (ObjectInfo, error) {
+	if err := ctx.Err(); err != nil {
+		return ObjectInfo{}, err
+	}
+	if f.UploadErr != nil {
+		return ObjectInfo{}, f.UploadErr
+	}
+	if source == nil {
+		return ObjectInfo{}, fmt.Errorf("upload object: source is required")
+	}
+	if strings.TrimSpace(key) == "" {
+		return ObjectInfo{}, fmt.Errorf("upload object: key is required")
+	}
+
+	data, err := io.ReadAll(source)
 	if err != nil {
 		return ObjectInfo{}, fmt.Errorf("upload object %q from %q: %w", key, localPath, err)
 	}
 
 	normalizedKey := normalizeObjectKey(key)
-	f.Uploads = append(f.Uploads, FakeUploadCall{
+	call := FakeUploadCall{
 		LocalPath: localPath,
 		Key:       normalizedKey,
 		Options: UploadOptions{
 			Metadata:    copyMetadata(opts.Metadata),
 			ContentType: opts.ContentType,
 		},
-	})
-	now := time.Now().UTC()
-	obj := FakeObject{
-		Key:          normalizedKey,
-		Data:         data,
-		Metadata:     copyMetadata(opts.Metadata),
-		LastModified: &now,
 	}
-	f.SeedObject(obj)
-	return ObjectInfo{
-		Key:          normalizedKey,
-		Size:         int64(len(data)),
-		LastModified: &now,
-	}, nil
+	f.mu.Lock()
+	f.Uploads = append(f.Uploads, call)
+	f.mu.Unlock()
+	if f.UploadHook != nil {
+		if err := f.UploadHook(call); err != nil {
+			return ObjectInfo{}, err
+		}
+	}
+	return f.storeUploadedObject(normalizedKey, data, opts), nil
+}
+
+// UploadConditional atomically checks and replaces one mutable object.
+func (f *FakeBackend) UploadConditional(ctx context.Context, source io.Reader, key string, opts UploadOptions, condition WriteCondition) (ObjectInfo, error) {
+	if err := ctx.Err(); err != nil {
+		return ObjectInfo{}, err
+	}
+	if err := validateWriteCondition(condition); err != nil {
+		return ObjectInfo{}, err
+	}
+	if f.UploadErr != nil {
+		return ObjectInfo{}, f.UploadErr
+	}
+	if source == nil {
+		return ObjectInfo{}, fmt.Errorf("upload object: source is required")
+	}
+	normalizedKey := normalizeObjectKey(key)
+	if normalizedKey == "" {
+		return ObjectInfo{}, fmt.Errorf("upload object: key is required")
+	}
+	data, err := io.ReadAll(source)
+	if err != nil {
+		return ObjectInfo{}, fmt.Errorf("upload object %q: %w", normalizedKey, err)
+	}
+	call := FakeUploadCall{Key: normalizedKey, Options: UploadOptions{Metadata: copyMetadata(opts.Metadata), ContentType: opts.ContentType}}
+	f.mu.Lock()
+	f.Uploads = append(f.Uploads, call)
+	f.mu.Unlock()
+	if f.UploadHook != nil {
+		if err := f.UploadHook(call); err != nil {
+			return ObjectInfo{}, err
+		}
+	}
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	existing, found := f.Objects[normalizedKey]
+	if condition.RequireAbsent && found {
+		return ObjectInfo{}, ErrConditionNotMet
+	}
+	if expected := strings.TrimSpace(condition.MatchETag); expected != "" && (!found || existing.ETag != expected) {
+		return ObjectInfo{}, ErrConditionNotMet
+	}
+	return f.storeUploadedObjectLocked(normalizedKey, data, opts), nil
+}
+
+func (f *FakeBackend) storeUploadedObject(key string, data []byte, opts UploadOptions) ObjectInfo {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	return f.storeUploadedObjectLocked(key, data, opts)
+}
+
+func (f *FakeBackend) storeUploadedObjectLocked(key string, data []byte, opts UploadOptions) ObjectInfo {
+	now := time.Now().UTC()
+	obj := FakeObject{Key: key, Data: append([]byte(nil), data...), Metadata: copyMetadata(opts.Metadata), LastModified: &now}
+	f.seedObject(obj)
+	return ObjectInfo{Key: key, Size: int64(len(data)), ETag: fakeObjectETag(data), LastModified: &now}
+}
+
+func fakeObjectETag(data []byte) string {
+	sum := sha256.Sum256(data)
+	return hex.EncodeToString(sum[:])
 }
 
 // Exists checks object presence.
@@ -169,7 +323,9 @@ func (f *FakeBackend) Exists(ctx context.Context, key string) (bool, error) {
 	if f.ExistsErr != nil {
 		return false, f.ExistsErr
 	}
+	f.mu.RLock()
 	_, ok := f.Objects[normalizeObjectKey(key)]
+	f.mu.RUnlock()
 	return ok, nil
 }
 

internal/adapters/storage/fake_test.go

@@ -71,6 +71,21 @@ func TestFakeBackendUploadAndExists(t *testing.T) {
 	}
 }
 
+func TestFakeBackendConditionalUploadRejectsStaleGeneration(t *testing.T) {
+	fake := &FakeBackend{}
+	fake.SeedObject(FakeObject{Key: "locks.yml", Data: []byte("old")})
+	old := fake.Objects["locks.yml"].ETag
+	if _, err := fake.UploadConditional(context.Background(), strings.NewReader("new"), "locks.yml", UploadOptions{}, WriteCondition{MatchETag: old}); err != nil {
+		t.Fatalf("UploadConditional() error = %v", err)
+	}
+	if _, err := fake.UploadConditional(context.Background(), strings.NewReader("lost"), "locks.yml", UploadOptions{}, WriteCondition{MatchETag: old}); !errors.Is(err, ErrConditionNotMet) {
+		t.Fatalf("UploadConditional() error = %v, want ErrConditionNotMet", err)
+	}
+	if got := string(fake.Objects["locks.yml"].Data); got != "new" {
+		t.Fatalf("locks object = %q, want successful replacement preserved", got)
+	}
+}
+
 func TestFakeBackendObjectErrors(t *testing.T) {
 	fake := &FakeBackend{DownloadErr: errors.New("download fail"), UploadErr: errors.New("upload fail"), ListErr: errors.New("list fail"), ExistsErr: errors.New("exists fail")}
 

internal/adapters/storage/object_store.go

@@ -2,9 +2,21 @@ package storage
 
 import (
 	"context"
+	"errors"
+	"io"
 	"time"
 )
 
+// ErrConditionNotMet reports that an object changed or already existed before a
+// conditional write could be committed.
+var ErrConditionNotMet = errors.New("object write condition not met")
+
+// ReaderUploader streams caller-owned, already-opened content to object storage.
+// Callers retain source-selection and filesystem-confinement policy.
+type ReaderUploader interface {
+	UploadReader(ctx context.Context, source io.Reader, key string, opts UploadOptions) (ObjectInfo, error)
+}
+
 // ObjectStore is a remote object storage boundary used by prepare, restore, and publish work.
 //
 // Key invariant:
@@ -12,8 +24,10 @@ import (
 // infer Narratio session semantics and do not prepend root prefixes.
 type ObjectStore interface {
 	List(ctx context.Context, prefix string) ([]ObjectInfo, error)
+	Read(ctx context.Context, key string) (ObjectInfo, io.ReadCloser, error)
 	Download(ctx context.Context, key, localPath string) error
 	Upload(ctx context.Context, localPath, key string, opts UploadOptions) (ObjectInfo, error)
+	UploadConditional(ctx context.Context, source io.Reader, key string, opts UploadOptions, condition WriteCondition) (ObjectInfo, error)
 	Exists(ctx context.Context, key string) (bool, error)
 }
 
@@ -30,3 +44,10 @@ type UploadOptions struct {
 	Metadata    map[string]string
 	ContentType string
 }
+
+// WriteCondition protects a mutable object update against a stale snapshot.
+// Exactly one condition is required by UploadConditional.
+type WriteCondition struct {
+	MatchETag     string
+	RequireAbsent bool
+}

internal/adapters/storage/s3_backend.go

@@ -117,6 +117,7 @@ func (b *S3Backend) List(ctx context.Context, prefix string) ([]ObjectInfo, erro
 	normalizedPrefix := normalizeObjectKey(prefix)
 	out := make([]ObjectInfo, 0)
 	var token *string
+	seenTokens := map[string]struct{}{}
 
 	for {
 		resp, err := b.client.ListObjectsV2(ctx, &s3.ListObjectsV2Input{
@@ -142,44 +143,78 @@ func (b *S3Backend) List(ctx context.Context, prefix string) ([]ObjectInfo, erro
 			})
 		}
 
-		if !valueOrFalseBool(resp.IsTruncated) || resp.NextContinuationToken == nil {
+		if !valueOrFalseBool(resp.IsTruncated) {
 			break
 		}
-		token = resp.NextContinuationToken
+		next := strings.TrimSpace(valueOrEmpty(resp.NextContinuationToken))
+		if next == "" {
+			return nil, fmt.Errorf("s3 list objects bucket %q prefix %q: truncated response has an empty continuation token", b.bucket, normalizedPrefix)
+		}
+		if _, repeated := seenTokens[next]; repeated {
+			return nil, fmt.Errorf("s3 list objects bucket %q prefix %q: truncated response repeated continuation token", b.bucket, normalizedPrefix)
+		}
+		seenTokens[next] = struct{}{}
+		token = &next
 	}
 	return out, nil
 }
 
+// Read retrieves an object together with the generation observed for its body.
+func (b *S3Backend) Read(ctx context.Context, key string) (ObjectInfo, io.ReadCloser, error) {
+	normalizedKey := normalizeObjectKey(key)
+	resp, err := b.client.GetObject(ctx, &s3.GetObjectInput{Bucket: &b.bucket, Key: &normalizedKey})
+	if err != nil {
+		if isS3NotFound(err) {
+			return ObjectInfo{}, nil, fmt.Errorf("read object %q: %w", normalizedKey, os.ErrNotExist)
+		}
+		return ObjectInfo{}, nil, fmt.Errorf("read object %q: %w", normalizedKey, err)
+	}
+	var lastModified *time.Time
+	if resp.LastModified != nil {
+		t := *resp.LastModified
+		lastModified = &t
+	}
+	return ObjectInfo{
+		Key: normalizedKey, Size: valueOrZeroInt64(resp.ContentLength),
+		ETag: strings.Trim(valueOrEmpty(resp.ETag), "\""), LastModified: lastModified,
+	}, resp.Body, nil
+}
+
+// DownloadTo retrieves one object into the caller-owned destination writer.
+func (b *S3Backend) DownloadTo(ctx context.Context, key string, destination io.Writer) error {
+	if destination == nil {
+		return fmt.Errorf("download object: destination writer is required")
+	}
+	_, body, err := b.Read(ctx, key)
+	if err != nil {
+		return fmt.Errorf("download object %q: %w", normalizeObjectKey(key), err)
+	}
+	defer body.Close()
+
+	if _, err := io.Copy(destination, body); err != nil {
+		return fmt.Errorf("download object %q: copy body: %w", normalizeObjectKey(key), err)
+	}
+	return nil
+}
+
 // Download retrieves one object to localPath, creating parent directories as needed.
 func (b *S3Backend) Download(ctx context.Context, key, localPath string) error {
-	normalizedKey := normalizeObjectKey(key)
 	if strings.TrimSpace(localPath) == "" {
 		return fmt.Errorf("download object: local path is required")
 	}
-
-	resp, err := b.client.GetObject(ctx, &s3.GetObjectInput{
-		Bucket: &b.bucket,
-		Key:    &normalizedKey,
-	})
-	if err != nil {
-		return fmt.Errorf("download object %q: %w", normalizedKey, err)
-	}
-	defer resp.Body.Close()
-
 	if err := os.MkdirAll(filepath.Dir(localPath), 0o755); err != nil {
-		return fmt.Errorf("download object %q: create parent directory: %w", normalizedKey, err)
+		return fmt.Errorf("download object %q: create parent directory: %w", key, err)
 	}
 	dst, err := os.Create(localPath)
 	if err != nil {
-		return fmt.Errorf("download object %q: create local file: %w", normalizedKey, err)
+		return fmt.Errorf("download object %q: create local file: %w", key, err)
 	}
 	defer dst.Close()
-
-	if _, err := io.Copy(dst, resp.Body); err != nil {
-		return fmt.Errorf("download object %q: copy body: %w", normalizedKey, err)
+	if err := b.DownloadTo(ctx, key, dst); err != nil {
+		return err
 	}
 	if err := dst.Sync(); err != nil {
-		return fmt.Errorf("download object %q: sync local file: %w", normalizedKey, err)
+		return fmt.Errorf("download object %q: sync local file: %w", key, err)
 	}
 	return nil
 }
@@ -204,28 +239,65 @@ func (b *S3Backend) Upload(ctx context.Context, localPath, key string, opts Uplo
 	if err != nil {
 		return ObjectInfo{}, fmt.Errorf("upload object %q from %q: stat local file: %w", normalizedKey, localPath, err)
 	}
+	return b.uploadReader(ctx, file, key, opts, stat.Size(), WriteCondition{})
+}
+
+// UploadReader sends caller-owned content to key.
+func (b *S3Backend) UploadReader(ctx context.Context, source io.Reader, key string, opts UploadOptions) (ObjectInfo, error) {
+	return b.uploadReader(ctx, source, key, opts, 0, WriteCondition{})
+}
+
+// UploadConditional uploads a mutable object only when its observed generation
+// still matches, or when no object exists yet.
+func (b *S3Backend) UploadConditional(ctx context.Context, source io.Reader, key string, opts UploadOptions, condition WriteCondition) (ObjectInfo, error) {
+	if err := validateWriteCondition(condition); err != nil {
+		return ObjectInfo{}, err
+	}
+	return b.uploadReader(ctx, source, key, opts, 0, condition)
+}
+
+func (b *S3Backend) uploadReader(ctx context.Context, source io.Reader, key string, opts UploadOptions, size int64, condition WriteCondition) (ObjectInfo, error) {
+	normalizedKey := normalizeObjectKey(key)
+	if source == nil {
+		return ObjectInfo{}, fmt.Errorf("upload object: source is required")
+	}
+	if normalizedKey == "" {
+		return ObjectInfo{}, fmt.Errorf("upload object: key is required")
+	}
 
 	input := &s3.PutObjectInput{
 		Bucket:   &b.bucket,
 		Key:      &normalizedKey,
-		Body:     file,
+		Body:     source,
 		Metadata: copyMetadata(opts.Metadata),
 	}
 	if strings.TrimSpace(opts.ContentType) != "" {
 		ct := strings.TrimSpace(opts.ContentType)
 		input.ContentType = &ct
 	}
+	if condition.RequireAbsent {
+		wildcard := "*"
+		input.IfNoneMatch = &wildcard
+	} else if expected := strings.TrimSpace(condition.MatchETag); expected != "" {
+		input.IfMatch = &expected
+	}
 
 	resp, err := b.client.PutObject(ctx, input)
 	if err != nil {
-		return ObjectInfo{}, fmt.Errorf("upload object %q from %q: %w", normalizedKey, localPath, err)
+		if isS3ConditionalConflict(err) {
+			return ObjectInfo{}, fmt.Errorf("upload object %q: %w", normalizedKey, ErrConditionNotMet)
+		}
+		return ObjectInfo{}, fmt.Errorf("upload object %q: %w", normalizedKey, err)
 	}
 
-	return ObjectInfo{
+	info := ObjectInfo{
 		Key:  normalizedKey,
-		Size: stat.Size(),
 		ETag: strings.Trim(valueOrEmpty(resp.ETag), "\""),
-	}, nil
+	}
+	if size > 0 {
+		info.Size = size
+	}
+	return info, nil
 }
 
 // Exists checks whether one object key exists.
@@ -239,18 +311,43 @@ func (b *S3Backend) Exists(ctx context.Context, key string) (bool, error) {
 		return true, nil
 	}
 
+	if isS3NotFound(err) {
+		return false, nil
+	}
+	return false, fmt.Errorf("head object %q: %w", normalizedKey, err)
+}
+
+func validateWriteCondition(condition WriteCondition) error {
+	if condition.RequireAbsent == (strings.TrimSpace(condition.MatchETag) != "") {
+		return fmt.Errorf("conditional upload requires exactly one of MatchETag or RequireAbsent")
+	}
+	return nil
+}
+
+func isS3NotFound(err error) bool {
 	var notFound *types.NotFound
 	if errors.As(err, &notFound) {
-		return false, nil
+		return true
 	}
 	var apiErr smithy.APIError
 	if errors.As(err, &apiErr) {
 		switch apiErr.ErrorCode() {
 		case "NotFound", "NoSuchKey", "404":
-			return false, nil
+			return true
 		}
 	}
-	return false, fmt.Errorf("head object %q: %w", normalizedKey, err)
+	return false
+}
+
+func isS3ConditionalConflict(err error) bool {
+	var apiErr smithy.APIError
+	if errors.As(err, &apiErr) {
+		switch apiErr.ErrorCode() {
+		case "PreconditionFailed", "ConditionalRequestConflict", "412", "409":
+			return true
+		}
+	}
+	return false
 }
 
 func valueOrEmpty(v *string) string {

internal/adapters/storage/s3_backend_test.go

@@ -2,6 +2,7 @@ package storage
 
 import (
 	"context"
+	"errors"
 	"io"
 	"os"
 	"path/filepath"
@@ -17,34 +18,81 @@ import (
 )
 
 type fakeS3API struct {
-	listOut *s3.ListObjectsV2Output
-	listErr error
+	listOut     *s3.ListObjectsV2Output
+	listOutputs []*s3.ListObjectsV2Output
+	listErr     error
+	listCalls   int
 
-	getBody io.ReadCloser
-	getErr  error
+	getBody         io.ReadCloser
+	getErr          error
+	getSize         *int64
+	getETag         *string
+	getLastModified *time.Time
 
 	putOut *s3.PutObjectOutput
 	putErr error
 
 	headErr error
 
-	lastList *s3.ListObjectsV2Input
-	lastGet  *s3.GetObjectInput
-	lastPut  *s3.PutObjectInput
-	lastHead *s3.HeadObjectInput
+	lastList  *s3.ListObjectsV2Input
+	lastLists []*s3.ListObjectsV2Input
+	lastGet   *s3.GetObjectInput
+	lastPut   *s3.PutObjectInput
+	lastHead  *s3.HeadObjectInput
 }
 
 func (f *fakeS3API) ListObjectsV2(_ context.Context, params *s3.ListObjectsV2Input, _ ...func(*s3.Options)) (*s3.ListObjectsV2Output, error) {
 	f.lastList = params
+	f.lastLists = append(f.lastLists, params)
 	if f.listErr != nil {
 		return nil, f.listErr
 	}
+	if f.listCalls < len(f.listOutputs) {
+		out := f.listOutputs[f.listCalls]
+		f.listCalls++
+		return out, nil
+	}
 	if f.listOut == nil {
 		return &s3.ListObjectsV2Output{}, nil
 	}
 	return f.listOut, nil
 }
 
+func TestS3BackendListPaginatesAndRejectsNonProgressingTokens(t *testing.T) {
+	t.Run("multiple pages", func(t *testing.T) {
+		client := &fakeS3API{listOutputs: []*s3.ListObjectsV2Output{
+			{Contents: []types.Object{{Key: strPtr("prefix/a"), Size: int64Ptr(1)}}, IsTruncated: boolPtr(true), NextContinuationToken: strPtr("next")},
+			{Contents: []types.Object{{Key: strPtr("prefix/b"), Size: int64Ptr(2)}}, IsTruncated: boolPtr(false)},
+		}}
+		items, err := (&S3Backend{bucket: "bucket-1", client: client}).List(context.Background(), "prefix/")
+		if err != nil {
+			t.Fatalf("List() error = %v", err)
+		}
+		if len(items) != 2 || items[0].Key != "prefix/a" || items[1].Key != "prefix/b" {
+			t.Fatalf("List() items = %#v", items)
+		}
+		if len(client.lastLists) != 2 || client.lastLists[1].ContinuationToken == nil || *client.lastLists[1].ContinuationToken != "next" {
+			t.Fatalf("continuation calls = %#v", client.lastLists)
+		}
+	})
+
+	for _, test := range []struct {
+		name    string
+		outputs []*s3.ListObjectsV2Output
+		want    string
+	}{
+		{name: "empty", outputs: []*s3.ListObjectsV2Output{{IsTruncated: boolPtr(true)}}, want: "empty continuation token"},
+		{name: "repeated", outputs: []*s3.ListObjectsV2Output{{IsTruncated: boolPtr(true), NextContinuationToken: strPtr("again")}, {IsTruncated: boolPtr(true), NextContinuationToken: strPtr("again")}}, want: "repeated continuation token"},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			_, err := (&S3Backend{bucket: "bucket-1", client: &fakeS3API{listOutputs: test.outputs}}).List(context.Background(), "prefix/")
+			if err == nil || !strings.Contains(err.Error(), test.want) || !strings.Contains(err.Error(), "bucket-1") || !strings.Contains(err.Error(), "prefix/") {
+				t.Fatalf("List() error = %v, want contextual %q", err, test.want)
+			}
+		})
+	}
+}
+
 func (f *fakeS3API) GetObject(_ context.Context, params *s3.GetObjectInput, _ ...func(*s3.Options)) (*s3.GetObjectOutput, error) {
 	f.lastGet = params
 	if f.getErr != nil {
@@ -54,7 +102,7 @@ func (f *fakeS3API) GetObject(_ context.Context, params *s3.GetObjectInput, _ ..
 	if body == nil {
 		body = io.NopCloser(strings.NewReader(""))
 	}
-	return &s3.GetObjectOutput{Body: body}, nil
+	return &s3.GetObjectOutput{Body: body, ContentLength: f.getSize, ETag: f.getETag, LastModified: f.getLastModified}, nil
 }
 
 func (f *fakeS3API) PutObject(_ context.Context, params *s3.PutObjectInput, _ ...func(*s3.Options)) (*s3.PutObjectOutput, error) {
@@ -126,6 +174,33 @@ func TestS3BackendDownloadCreatesParentDirectory(t *testing.T) {
 	}
 }
 
+func TestS3BackendReadReturnsOpenedObjectMetadata(t *testing.T) {
+	lastModified := time.Date(2026, 8, 11, 1, 2, 3, 0, time.UTC)
+	client := &fakeS3API{
+		getBody:         io.NopCloser(strings.NewReader("locks")),
+		getSize:         int64Ptr(5),
+		getETag:         strPtr(`"generation"`),
+		getLastModified: &lastModified,
+	}
+	backend := &S3Backend{bucket: "bucket-1", client: client}
+
+	info, body, err := backend.Read(context.Background(), `sessions\locks.yml`)
+	if err != nil {
+		t.Fatalf("Read() error = %v", err)
+	}
+	data, readErr := io.ReadAll(body)
+	closeErr := body.Close()
+	if readErr != nil || closeErr != nil {
+		t.Fatalf("read body error=%v close error=%v", readErr, closeErr)
+	}
+	if info.Key != "sessions/locks.yml" || info.Size != 5 || info.ETag != "generation" || info.LastModified == nil || !info.LastModified.Equal(lastModified) {
+		t.Fatalf("Read() info = %#v, want opened object metadata", info)
+	}
+	if string(data) != "locks" || client.lastGet == nil || *client.lastGet.Key != "sessions/locks.yml" {
+		t.Fatalf("Read() data=%q request=%#v", data, client.lastGet)
+	}
+}
+
 func TestS3BackendUploadAndExists(t *testing.T) {
 	client := &fakeS3API{putOut: &s3.PutObjectOutput{ETag: strPtr(`"etag123"`)}}
 	backend := &S3Backend{bucket: "bucket-1", client: client}
@@ -160,6 +235,22 @@ func TestS3BackendUploadAndExists(t *testing.T) {
 	}
 }
 
+func TestS3BackendConditionalUploadUsesProviderPrecondition(t *testing.T) {
+	client := &fakeS3API{putOut: &s3.PutObjectOutput{ETag: strPtr(`"etag123"`)}}
+	backend := &S3Backend{bucket: "bucket-1", client: client}
+	if _, err := backend.UploadConditional(context.Background(), strings.NewReader("payload"), "locks.yml", UploadOptions{}, WriteCondition{MatchETag: "before"}); err != nil {
+		t.Fatalf("UploadConditional() error = %v", err)
+	}
+	if client.lastPut == nil || client.lastPut.IfMatch == nil || *client.lastPut.IfMatch != "before" || client.lastPut.IfNoneMatch != nil {
+		t.Fatalf("PutObject conditional input = %#v", client.lastPut)
+	}
+	client.putErr = &smithy.GenericAPIError{Code: "PreconditionFailed", Message: "changed"}
+	_, err := backend.UploadConditional(context.Background(), strings.NewReader("payload"), "locks.yml", UploadOptions{}, WriteCondition{RequireAbsent: true})
+	if !errors.Is(err, ErrConditionNotMet) {
+		t.Fatalf("UploadConditional() error = %v, want ErrConditionNotMet", err)
+	}
+}
+
 func TestS3BackendUploadMissingLocalFile(t *testing.T) {
 	backend := &S3Backend{bucket: "bucket-1", client: &fakeS3API{}}
 	_, err := backend.Upload(context.Background(), filepath.Join(t.TempDir(), "missing.txt"), "key.txt", UploadOptions{})
@@ -249,5 +340,6 @@ func TestNewS3BackendFromConfigFallsBackWhenCredentialEnvMissing(t *testing.T) {
 
 func strPtr(v string) *string { return &v }
 func int64Ptr(v int64) *int64 { return &v }
+func boolPtr(v bool) *bool    { return &v }
 
 var _ s3API = (*fakeS3API)(nil)

internal/adapters/subprocess/diagnostics.go

@@ -0,0 +1,391 @@
+package subprocess
+
+import (
+	"bytes"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"sync"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/fileops"
+)
+
+const (
+	// MaxStdoutDiagnosticBytes bounds persisted stdout from one external command.
+	MaxStdoutDiagnosticBytes int64 = 8 * 1024 * 1024
+	// MaxStderrDiagnosticBytes bounds persisted stderr from one external command.
+	MaxStderrDiagnosticBytes int64 = 8 * 1024 * 1024
+	diagnosticTailBytes            = 2048
+)
+
+var inheritedEnvironmentNames = map[string]struct{}{
+	"COMSPEC":    {},
+	"HOME":       {},
+	"PATH":       {},
+	"SYSTEMROOT": {},
+	"TMP":        {},
+	"TMPDIR":     {},
+	"TEMP":       {},
+	"WINDIR":     {},
+	// These test-only helper destinations let the adapter package tests exercise
+	// real command invocation without widening the production environment.
+	"AUDITA_HELPER_RECORD_PATH":      {},
+	"AUDITA_HELPER_MODE":             {},
+	"GO_WANT_AUDITA_HELPER":          {},
+	"GO_WANT_SCRIPTORIUM_HELPER":     {},
+	"GO_WANT_SERIATIM_HELPER":        {},
+	"GO_WANT_SUBPROCESS_HELPER":      {},
+	"NOTARIUS_CAPTURE_DIR":           {},
+	"NOTARIUS_RECEIPT_FIXTURE":       {},
+	"SCRIPTORIUM_HELPER_RECORD_PATH": {},
+	"SCRIPTORIUM_HELPER_MODE":        {},
+	"SERIATIM_HELPER_RECORD_PATH":    {},
+	"SERIATIM_HELPER_MODE":           {},
+}
+
+var sensitiveEnvironmentNames = map[string]struct{}{
+	"ANTHROPIC_API_KEY":     {},
+	"API_KEY":               {},
+	"AUDITA_LLM_API_KEY":    {},
+	"AWS_ACCESS_KEY_ID":     {},
+	"AWS_SECRET_ACCESS_KEY": {},
+	"AWS_SESSION_TOKEN":     {},
+	"OPENAI_API_KEY":        {},
+	"OPENROUTER_API_KEY":    {},
+}
+
+type captureLimitError struct {
+	stream string
+	owner  string
+	limit  int64
+}
+
+func (e *captureLimitError) Error() string {
+	return fmt.Sprintf("%s diagnostic capture for %s exceeded %d bytes", e.stream, e.owner, e.limit)
+}
+
+type logWriters struct {
+	files  []*os.File
+	Stdout io.Writer
+	Stderr io.Writer
+
+	limits chan *captureLimitError
+	mu     sync.Mutex
+	limit  *captureLimitError
+	stdout *diagnosticWriter
+	stderr *diagnosticWriter
+}
+
+type diagnosticWriter struct {
+	logs      *logWriters
+	stream    string
+	owner     string
+	target    io.Writer
+	limit     int64
+	received  int64
+	persisted int64
+	redactor  streamRedactor
+	tail      []byte
+}
+
+func openLogWriters(stdoutPath, stderrPath, owner string, sensitiveValues []string) (*logWriters, error) {
+	logs := &logWriters{limits: make(chan *captureLimitError, 1)}
+	cleanStdout := cleanLogPath(stdoutPath)
+	cleanStderr := cleanLogPath(stderrPath)
+
+	stdoutFile, err := openDiagnosticFile(cleanStdout)
+	if err != nil {
+		return nil, fmt.Errorf("open stdout log: %w", err)
+	}
+	stderrFile := stdoutFile
+	if cleanStdout != cleanStderr {
+		stderrFile, err = openDiagnosticFile(cleanStderr)
+		if err != nil {
+			_ = stdoutFile.Close()
+			return nil, fmt.Errorf("open stderr log: %w", err)
+		}
+	}
+	if cleanStdout == cleanStderr {
+		logs.files = []*os.File{stdoutFile}
+	} else {
+		logs.files = []*os.File{stdoutFile, stderrFile}
+	}
+
+	logs.stdout = newDiagnosticWriter(logs, "stdout", owner, stdoutFile, MaxStdoutDiagnosticBytes, sensitiveValues)
+	logs.stderr = newDiagnosticWriter(logs, "stderr", owner, stderrFile, MaxStderrDiagnosticBytes, sensitiveValues)
+	logs.Stdout = logs.stdout
+	logs.Stderr = logs.stderr
+	return logs, nil
+}
+
+func newDiagnosticWriter(logs *logWriters, stream, owner string, target io.Writer, limit int64, sensitiveValues []string) *diagnosticWriter {
+	return &diagnosticWriter{
+		logs:     logs,
+		stream:   stream,
+		owner:    owner,
+		target:   target,
+		limit:    limit,
+		redactor: newStreamRedactor(sensitiveValues),
+	}
+}
+
+func (w *diagnosticWriter) Write(data []byte) (int, error) {
+	if w.received >= w.limit {
+		return len(data), w.reachLimit()
+	}
+	accepted := data
+	if remaining := w.limit - w.received; int64(len(accepted)) > remaining {
+		accepted = accepted[:remaining]
+	}
+	w.received += int64(len(accepted))
+	if err := w.writeRedacted(w.redactor.Write(accepted)); err != nil {
+		return len(data), err
+	}
+	if len(accepted) != len(data) {
+		return len(data), w.reachLimit()
+	}
+	return len(data), nil
+}
+
+func (w *diagnosticWriter) Flush() error {
+	return w.writeRedacted(w.redactor.Flush())
+}
+
+func (w *diagnosticWriter) writeRedacted(data []byte) error {
+	if len(data) == 0 {
+		return nil
+	}
+	w.logs.mu.Lock()
+	remaining := w.limit - w.persisted
+	if remaining <= 0 {
+		w.logs.mu.Unlock()
+		return w.reachLimit()
+	}
+	toWrite := data
+	exceeded := int64(len(data)) > remaining
+	if exceeded {
+		toWrite = toWrite[:remaining]
+	}
+	written, err := w.target.Write(toWrite)
+	w.persisted += int64(written)
+	w.retainTail(toWrite[:written])
+	w.logs.mu.Unlock()
+	if err != nil {
+		return err
+	}
+	if exceeded {
+		return w.reachLimit()
+	}
+	return nil
+}
+
+func (w *diagnosticWriter) Tail() string {
+	w.logs.mu.Lock()
+	defer w.logs.mu.Unlock()
+	return strings.TrimSpace(string(w.tail))
+}
+
+func (w *diagnosticWriter) retainTail(data []byte) {
+	if len(data) >= diagnosticTailBytes {
+		if cap(w.tail) < diagnosticTailBytes {
+			w.tail = make([]byte, diagnosticTailBytes)
+		} else {
+			w.tail = w.tail[:diagnosticTailBytes]
+		}
+		copy(w.tail, data[len(data)-diagnosticTailBytes:])
+		return
+	}
+	if cap(w.tail) < diagnosticTailBytes {
+		retained := make([]byte, len(w.tail), diagnosticTailBytes)
+		copy(retained, w.tail)
+		w.tail = retained
+	}
+	if overflow := len(w.tail) + len(data) - diagnosticTailBytes; overflow > 0 {
+		copy(w.tail, w.tail[overflow:])
+		w.tail = w.tail[:len(w.tail)-overflow]
+	}
+	w.tail = append(w.tail, data...)
+}
+
+func (w *diagnosticWriter) reachLimit() error {
+	limit := &captureLimitError{stream: w.stream, owner: w.owner, limit: w.limit}
+	w.logs.mu.Lock()
+	if w.logs.limit == nil {
+		w.logs.limit = limit
+		w.logs.limits <- limit
+	}
+	w.logs.mu.Unlock()
+	return limit
+}
+
+func (l *logWriters) Limits() <-chan *captureLimitError { return l.limits }
+
+func (l *logWriters) Limit() *captureLimitError {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	return l.limit
+}
+
+func (l *logWriters) Flush() error {
+	return joinErrors(l.stdout.Flush(), l.stderr.Flush())
+}
+
+func (l *logWriters) Close() {
+	_ = l.Flush()
+	for _, file := range l.files {
+		_ = file.Close()
+	}
+}
+
+func cleanLogPath(path string) string {
+	trimmed := strings.TrimSpace(path)
+	if trimmed == "" {
+		return ""
+	}
+	return filepath.Clean(trimmed)
+}
+
+func openDiagnosticFile(path string) (*os.File, error) {
+	if path == "" {
+		return os.OpenFile(os.DevNull, os.O_WRONLY, 0)
+	}
+	if err := fileops.EnsureWorkspaceDirectory(filepath.Dir(path)); err != nil {
+		return nil, fmt.Errorf("create log directory for %q: %w", path, err)
+	}
+	file, err := fileops.OpenFileConfined(path, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, fileops.WorkspaceFileMode)
+	if err != nil {
+		return nil, fmt.Errorf("open log file %q: %w", path, err)
+	}
+	if err := file.Chmod(fileops.WorkspaceFileMode); err != nil {
+		_ = file.Close()
+		return nil, fmt.Errorf("set log file permissions %q: %w", path, err)
+	}
+	return file, nil
+}
+
+func (r RunRequest) diagnosticOwner() string {
+	if owner := strings.TrimSpace(r.DiagnosticOwner); owner != "" {
+		return owner
+	}
+	return "subprocess"
+}
+
+func buildChildEnvironment(base []string, overrides map[string]string) []string {
+	values := make(map[string]string, len(inheritedEnvironmentNames)+len(overrides))
+	for _, item := range base {
+		name, value, ok := strings.Cut(item, "=")
+		if !ok {
+			continue
+		}
+		normalized := strings.ToUpper(name)
+		if _, allowed := inheritedEnvironmentNames[normalized]; allowed {
+			values[name] = value
+		}
+	}
+	for name, value := range overrides {
+		values[name] = value
+	}
+	names := make([]string, 0, len(values))
+	for name := range values {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+	out := make([]string, 0, len(names))
+	for _, name := range names {
+		out = append(out, name+"="+values[name])
+	}
+	return out
+}
+
+func sensitiveEnvironmentValues(environment []string, additionalNames []string) []string {
+	names := make(map[string]struct{}, len(sensitiveEnvironmentNames)+len(additionalNames))
+	for name := range sensitiveEnvironmentNames {
+		names[name] = struct{}{}
+	}
+	for _, name := range additionalNames {
+		if trimmed := strings.ToUpper(strings.TrimSpace(name)); trimmed != "" {
+			names[trimmed] = struct{}{}
+		}
+	}
+	values := make([]string, 0, len(names))
+	for _, item := range environment {
+		name, value, ok := strings.Cut(item, "=")
+		if !ok || strings.TrimSpace(value) == "" {
+			continue
+		}
+		if _, sensitive := names[strings.ToUpper(name)]; sensitive {
+			values = append(values, value)
+		}
+	}
+	return values
+}
+
+type streamRedactor struct {
+	values []string
+	buffer []byte
+	maxLen int
+}
+
+func newStreamRedactor(values []string) streamRedactor {
+	unique := make(map[string]struct{}, len(values))
+	for _, value := range values {
+		if value != "" {
+			unique[value] = struct{}{}
+		}
+	}
+	sorted := make([]string, 0, len(unique))
+	for value := range unique {
+		sorted = append(sorted, value)
+	}
+	sort.Slice(sorted, func(i, j int) bool { return len(sorted[i]) > len(sorted[j]) })
+	maxLen := 1
+	for _, value := range sorted {
+		if len(value) > maxLen {
+			maxLen = len(value)
+		}
+	}
+	return streamRedactor{values: sorted, maxLen: maxLen}
+}
+
+func (r *streamRedactor) Write(data []byte) []byte {
+	r.buffer = append(r.buffer, data...)
+	safeCut := len(r.buffer) - r.maxLen + 1
+	if safeCut <= 0 {
+		return nil
+	}
+	emitCut := safeCut
+	for _, value := range r.values {
+		start := 0
+		for {
+			index := bytes.Index(r.buffer[start:], []byte(value))
+			if index < 0 {
+				break
+			}
+			index += start
+			if index+len(value) > safeCut && index < emitCut {
+				emitCut = index
+			}
+			start = index + 1
+		}
+	}
+	output := redactBytes(r.buffer[:emitCut], r.values)
+	r.buffer = append(r.buffer[:0], r.buffer[emitCut:]...)
+	return output
+}
+
+func (r *streamRedactor) Flush() []byte {
+	output := redactBytes(r.buffer, r.values)
+	r.buffer = nil
+	return output
+}
+
+func redactBytes(data []byte, values []string) []byte {
+	out := append([]byte(nil), data...)
+	for _, value := range values {
+		out = bytes.ReplaceAll(out, []byte(value), []byte("<redacted>"))
+	}
+	return out
+}

internal/adapters/subprocess/process_tree.go

@@ -0,0 +1,66 @@
+package subprocess
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os/exec"
+	"time"
+)
+
+const (
+	gracefulTerminationWait = 2 * time.Second
+	forcefulTerminationWait = 2 * time.Second
+)
+
+// ownedProcessTree owns every process started by a command invocation.
+// Implementations must tolerate a leader that has already exited.
+type ownedProcessTree interface {
+	Start(*exec.Cmd) error
+	TerminateGracefully() error
+	TerminateForcefully() error
+	Dispose() error
+}
+
+func waitForOwnedCommand(ctx context.Context, tree ownedProcessTree, waitCh <-chan error, captureLimits <-chan *captureLimitError) (waitErr, ctxErr error, captureLimit *captureLimitError, cleanupErr error) {
+	select {
+	case waitErr = <-waitCh:
+		return waitErr, nil, nil, nil
+	case <-ctx.Done():
+		ctxErr = ctx.Err()
+	case captureLimit = <-captureLimits:
+	}
+
+	cleanupErr = tree.TerminateGracefully()
+	gracefulTimer := time.NewTimer(gracefulTerminationWait)
+	defer gracefulTimer.Stop()
+
+	select {
+	case waitErr = <-waitCh:
+		// The leader may exit before descendants finish graceful shutdown.
+		cleanupErr = joinErrors(cleanupErr, tree.TerminateForcefully())
+		return waitErr, ctxErr, captureLimit, cleanupErr
+	case <-gracefulTimer.C:
+	}
+
+	cleanupErr = joinErrors(cleanupErr, tree.TerminateForcefully())
+	forcefulTimer := time.NewTimer(forcefulTerminationWait)
+	defer forcefulTimer.Stop()
+
+	select {
+	case waitErr = <-waitCh:
+		return waitErr, ctxErr, captureLimit, cleanupErr
+	case <-forcefulTimer.C:
+		return nil, ctxErr, captureLimit, joinErrors(cleanupErr, fmt.Errorf("owned subprocess did not reap within %s after forceful termination", forcefulTerminationWait))
+	}
+}
+
+func joinErrors(errs ...error) error {
+	filtered := make([]error, 0, len(errs))
+	for _, err := range errs {
+		if err != nil {
+			filtered = append(filtered, err)
+		}
+	}
+	return errors.Join(filtered...)
+}

internal/adapters/subprocess/process_tree_supported_test.go

@@ -0,0 +1,227 @@
+//go:build linux || darwin || windows
+
+package subprocess
+
+import (
+	"context"
+	"errors"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestRunCancellationTerminatesProcessTree(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	resultCh := make(chan runOutcome, 1)
+	req, sentinelPath := processTreeRequest(t)
+	go func() {
+		result, err := Run(ctx, req)
+		resultCh <- runOutcome{result: result, err: err}
+	}()
+
+	awaitHelperReady(t, req.EnvOverrides["SUBPROCESS_HELPER_READY_PATH"])
+	cancel()
+
+	outcome := awaitRunOutcome(t, resultCh)
+	if !outcome.result.Canceled {
+		t.Fatalf("Canceled = %v, want true", outcome.result.Canceled)
+	}
+	if !errors.Is(outcome.err, context.Canceled) {
+		t.Fatalf("error = %v, want context cancellation", outcome.err)
+	}
+	assertDescendantDidNotSurvive(t, sentinelPath)
+}
+
+func TestRunTimeoutTerminatesProcessTree(t *testing.T) {
+	req, sentinelPath := processTreeRequest(t)
+	req.Timeout = 100 * time.Millisecond
+
+	result, err := Run(context.Background(), req)
+	if !result.TimedOut {
+		t.Fatalf("TimedOut = %v, want true", result.TimedOut)
+	}
+	if !errors.Is(err, context.DeadlineExceeded) {
+		t.Fatalf("error = %v, want context deadline exceeded", err)
+	}
+	assertDescendantDidNotSurvive(t, sentinelPath)
+}
+
+func TestRunCaptureLimitTerminatesProcessTree(t *testing.T) {
+	req, sentinelPath := processTreeRequest(t)
+	req.Args[len(req.Args)-1] = "tree-spam"
+
+	result, err := Run(context.Background(), req)
+	if err == nil {
+		t.Fatal("Run() error = nil, want capture-limit error")
+	}
+	if result.ExitCode == 0 {
+		t.Fatalf("ExitCode = %d, want terminated process", result.ExitCode)
+	}
+	if !strings.Contains(err.Error(), "stdout diagnostic capture for subprocess exceeded") {
+		t.Fatalf("error = %q, want stdout capture-limit context", err)
+	}
+	info, statErr := os.Stat(req.StdoutLogPath)
+	if statErr != nil {
+		t.Fatalf("stat stdout diagnostic: %v", statErr)
+	}
+	if info.Size() != MaxStdoutDiagnosticBytes {
+		t.Fatalf("stdout diagnostic size = %d, want %d", info.Size(), MaxStdoutDiagnosticBytes)
+	}
+	assertDescendantDidNotSurvive(t, sentinelPath)
+}
+
+func TestRunDisposesDescendantsAfterLeaderExit(t *testing.T) {
+	tests := []struct {
+		name          string
+		mode          string
+		wantExitCode  int
+		wantWaitDelay bool
+		ignoreTerm    bool
+	}{
+		{name: "success retaining streams", mode: "leader-exit-retained", wantExitCode: 0, wantWaitDelay: true},
+		{name: "success redirecting streams", mode: "leader-exit-redirected", wantExitCode: 0},
+		{name: "failed leader", mode: "leader-fail-redirected", wantExitCode: 9, ignoreTerm: true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			req, sentinelPath, releasePath := leaderExitRequest(t, tt.mode)
+			if tt.ignoreTerm {
+				req.EnvOverrides["SUBPROCESS_HELPER_IGNORE_TERM"] = "1"
+			}
+			outcomes := make(chan runOutcome, 1)
+			go func() {
+				result, err := Run(context.Background(), req)
+				outcomes <- runOutcome{result: result, err: err}
+			}()
+
+			var outcome runOutcome
+			select {
+			case outcome = <-outcomes:
+			case <-time.After(6 * time.Second):
+				t.Fatal("Run() did not complete bounded owned-tree disposal")
+			}
+			if outcome.result.ExitCode != tt.wantExitCode {
+				t.Fatalf("ExitCode = %d, want %d", outcome.result.ExitCode, tt.wantExitCode)
+			}
+			if tt.wantWaitDelay {
+				if !errors.Is(outcome.err, exec.ErrWaitDelay) {
+					t.Fatalf("error = %v, want exec.ErrWaitDelay", outcome.err)
+				}
+			} else if tt.wantExitCode == 0 && outcome.err != nil {
+				t.Fatalf("Run() error = %v, want nil", outcome.err)
+			} else if tt.wantExitCode != 0 {
+				var exitErr *exec.ExitError
+				if !errors.As(outcome.err, &exitErr) || exitErr.ExitCode() != tt.wantExitCode {
+					t.Fatalf("error = %v, want exit code %d", outcome.err, tt.wantExitCode)
+				}
+			}
+			if _, err := os.Stat(req.EnvOverrides["SUBPROCESS_HELPER_READY_PATH"]); err != nil {
+				t.Fatalf("descendant readiness file: %v", err)
+			}
+			if err := os.WriteFile(releasePath, []byte("release"), 0o600); err != nil {
+				t.Fatalf("WriteFile(release) error = %v", err)
+			}
+			assertDescendantDidNotSurvive(t, sentinelPath)
+		})
+	}
+}
+
+type runOutcome struct {
+	result RunResult
+	err    error
+}
+
+func processTreeRequest(t *testing.T) (RunRequest, string) {
+	t.Helper()
+
+	executable, err := os.Executable()
+	if err != nil {
+		t.Fatalf("os.Executable() error = %v", err)
+	}
+	dir := t.TempDir()
+	readyPath := filepath.Join(dir, "ready")
+	sentinelPath := filepath.Join(dir, "descendant-survived")
+	return RunRequest{
+		Executable: executable,
+		Args:       []string{"-test.run=^TestSubprocessHelper$", "--", "tree"},
+		EnvOverrides: map[string]string{
+			"GO_WANT_SUBPROCESS_HELPER":       "1",
+			"SUBPROCESS_HELPER_READY_PATH":    readyPath,
+			"SUBPROCESS_HELPER_SENTINEL_PATH": sentinelPath,
+		},
+		StdoutLogPath: filepath.Join(dir, "stdout.log"),
+		StderrLogPath: filepath.Join(dir, "stderr.log"),
+	}, sentinelPath
+}
+
+func leaderExitRequest(t *testing.T, mode string) (RunRequest, string, string) {
+	t.Helper()
+
+	executable, err := os.Executable()
+	if err != nil {
+		t.Fatalf("os.Executable() error = %v", err)
+	}
+	dir := t.TempDir()
+	readyPath := filepath.Join(dir, "ready")
+	releasePath := filepath.Join(dir, "release")
+	sentinelPath := filepath.Join(dir, "descendant-survived")
+	return RunRequest{
+		Executable: executable,
+		Args:       []string{"-test.run=^TestSubprocessHelper$", "--", mode},
+		EnvOverrides: map[string]string{
+			"GO_WANT_SUBPROCESS_HELPER":       "1",
+			"SUBPROCESS_HELPER_READY_PATH":    readyPath,
+			"SUBPROCESS_HELPER_RELEASE_PATH":  releasePath,
+			"SUBPROCESS_HELPER_SENTINEL_PATH": sentinelPath,
+		},
+		StdoutLogPath: filepath.Join(dir, "stdout.log"),
+		StderrLogPath: filepath.Join(dir, "stderr.log"),
+	}, sentinelPath, releasePath
+}
+
+func awaitHelperReady(t *testing.T, readyPath string) {
+	t.Helper()
+
+	deadline := time.Now().Add(2 * time.Second)
+	for time.Now().Before(deadline) {
+		if _, err := os.Stat(readyPath); err == nil {
+			return
+		} else if !errors.Is(err, os.ErrNotExist) {
+			t.Fatalf("stat helper readiness: %v", err)
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+	t.Fatal("helper did not start its descendant")
+}
+
+func awaitRunOutcome(t *testing.T, outcomes <-chan runOutcome) runOutcome {
+	t.Helper()
+
+	select {
+	case outcome := <-outcomes:
+		if outcome.err == nil {
+			t.Fatal("Run() error = nil, want cancellation error")
+		}
+		return outcome
+	case <-time.After(3 * time.Second):
+		t.Fatal("Run() did not return after cancellation")
+		return runOutcome{}
+	}
+}
+
+func assertDescendantDidNotSurvive(t *testing.T, sentinelPath string) {
+	t.Helper()
+
+	time.Sleep(700 * time.Millisecond)
+	if _, err := os.Stat(sentinelPath); err == nil {
+		t.Fatal("descendant survived cancellation and wrote its sentinel")
+	} else if !errors.Is(err, os.ErrNotExist) {
+		t.Fatalf("stat descendant sentinel: %v", err)
+	}
+}

internal/adapters/subprocess/process_tree_unix.go

@@ -0,0 +1,104 @@
+//go:build linux || darwin
+
+package subprocess
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"syscall"
+	"time"
+)
+
+const processGroupPollInterval = 10 * time.Millisecond
+
+type unixProcessTree struct {
+	processGroupID int
+}
+
+func newOwnedProcessTree() (ownedProcessTree, error) {
+	return &unixProcessTree{}, nil
+}
+
+func (tree *unixProcessTree) Start(cmd *exec.Cmd) error {
+	cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
+	if err := cmd.Start(); err != nil {
+		return err
+	}
+	tree.processGroupID = cmd.Process.Pid
+	return nil
+}
+
+func (tree *unixProcessTree) TerminateGracefully() error {
+	return tree.signal(syscall.SIGTERM)
+}
+
+func (tree *unixProcessTree) TerminateForcefully() error {
+	return tree.signal(syscall.SIGKILL)
+}
+
+func (tree *unixProcessTree) Dispose() error {
+	hasMembers, err := tree.hasMembers()
+	if err != nil || !hasMembers {
+		return err
+	}
+
+	cleanupErr := tree.TerminateGracefully()
+	empty, waitErr := tree.waitUntilEmpty(gracefulTerminationWait)
+	cleanupErr = joinErrors(cleanupErr, waitErr)
+	if empty {
+		return cleanupErr
+	}
+
+	cleanupErr = joinErrors(cleanupErr, tree.TerminateForcefully())
+	empty, waitErr = tree.waitUntilEmpty(forcefulTerminationWait)
+	cleanupErr = joinErrors(cleanupErr, waitErr)
+	if !empty {
+		cleanupErr = joinErrors(cleanupErr, fmt.Errorf("owned subprocess group did not exit within %s after forceful termination", forcefulTerminationWait))
+	}
+	return cleanupErr
+}
+
+func (tree *unixProcessTree) signal(signal syscall.Signal) error {
+	if tree.processGroupID <= 0 {
+		return nil
+	}
+	err := syscall.Kill(-tree.processGroupID, signal)
+	if errors.Is(err, syscall.ESRCH) || errors.Is(err, os.ErrProcessDone) {
+		return nil
+	}
+	return err
+}
+
+func (tree *unixProcessTree) hasMembers() (bool, error) {
+	if tree.processGroupID <= 0 {
+		return false, nil
+	}
+	err := syscall.Kill(-tree.processGroupID, 0)
+	if err == nil || errors.Is(err, syscall.EPERM) {
+		return true, nil
+	}
+	if errors.Is(err, syscall.ESRCH) || errors.Is(err, os.ErrProcessDone) {
+		return false, nil
+	}
+	return false, fmt.Errorf("inspect owned subprocess group: %w", err)
+}
+
+func (tree *unixProcessTree) waitUntilEmpty(timeout time.Duration) (bool, error) {
+	deadline := time.Now().Add(timeout)
+	for {
+		hasMembers, err := tree.hasMembers()
+		if err != nil || !hasMembers {
+			return !hasMembers, err
+		}
+		remaining := time.Until(deadline)
+		if remaining <= 0 {
+			return false, nil
+		}
+		if remaining > processGroupPollInterval {
+			remaining = processGroupPollInterval
+		}
+		time.Sleep(remaining)
+	}
+}

internal/adapters/subprocess/process_tree_unsupported.go

@@ -0,0 +1,12 @@
+//go:build !linux && !darwin && !windows
+
+package subprocess
+
+import (
+	"fmt"
+	"runtime"
+)
+
+func newOwnedProcessTree() (ownedProcessTree, error) {
+	return nil, fmt.Errorf("owned subprocess trees are unsupported on %s", runtime.GOOS)
+}

internal/adapters/subprocess/process_tree_windows.go

@@ -0,0 +1,122 @@
+//go:build windows
+
+package subprocess
+
+import (
+	"errors"
+	"fmt"
+	"os/exec"
+	"syscall"
+	"unsafe"
+
+	"golang.org/x/sys/windows"
+)
+
+type windowsProcessTree struct {
+	job windows.Handle
+}
+
+func newOwnedProcessTree() (ownedProcessTree, error) {
+	return &windowsProcessTree{}, nil
+}
+
+func (tree *windowsProcessTree) Start(cmd *exec.Cmd) error {
+	job, err := windows.CreateJobObject(nil, nil)
+	if err != nil {
+		return fmt.Errorf("create job object: %w", err)
+	}
+
+	limits := windows.JOBOBJECT_EXTENDED_LIMIT_INFORMATION{}
+	limits.BasicLimitInformation.LimitFlags = windows.JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE
+	if _, err := windows.SetInformationJobObject(job, windows.JobObjectExtendedLimitInformation, uintptr(unsafe.Pointer(&limits)), uint32(unsafe.Sizeof(limits))); err != nil {
+		_ = windows.CloseHandle(job)
+		return fmt.Errorf("configure job object: %w", err)
+	}
+
+	cmd.SysProcAttr = &syscall.SysProcAttr{CreationFlags: windows.CREATE_SUSPENDED}
+	if err := cmd.Start(); err != nil {
+		_ = windows.CloseHandle(job)
+		return err
+	}
+
+	process, err := windows.OpenProcess(windows.PROCESS_SET_QUOTA|windows.PROCESS_TERMINATE, false, uint32(cmd.Process.Pid))
+	if err == nil {
+		err = windows.AssignProcessToJobObject(job, process)
+		_ = windows.CloseHandle(process)
+	}
+	if err == nil {
+		err = resumeInitialThread(uint32(cmd.Process.Pid))
+	}
+	if err != nil {
+		killErr := cmd.Process.Kill()
+		waitErr := cmd.Wait()
+		_ = windows.CloseHandle(job)
+		return joinErrors(fmt.Errorf("assign process to job object: %w", err), killErr, waitErr)
+	}
+
+	tree.job = job
+	return nil
+}
+
+func resumeInitialThread(processID uint32) error {
+	snapshot, err := windows.CreateToolhelp32Snapshot(windows.TH32CS_SNAPTHREAD, 0)
+	if err != nil {
+		return fmt.Errorf("snapshot initial thread: %w", err)
+	}
+	defer func() { _ = windows.CloseHandle(snapshot) }()
+
+	entry := windows.ThreadEntry32{Size: uint32(unsafe.Sizeof(windows.ThreadEntry32{}))}
+	if err := windows.Thread32First(snapshot, &entry); err != nil {
+		return fmt.Errorf("find initial thread: %w", err)
+	}
+	for {
+		if entry.OwnerProcessID != processID {
+			// Keep enumerating until the suspended process's only initial thread
+			// is found.
+		} else {
+			thread, openErr := windows.OpenThread(windows.THREAD_SUSPEND_RESUME, false, entry.ThreadID)
+			if openErr != nil {
+				return fmt.Errorf("open initial thread: %w", openErr)
+			}
+			defer func() { _ = windows.CloseHandle(thread) }()
+			if _, resumeErr := windows.ResumeThread(thread); resumeErr != nil {
+				return fmt.Errorf("resume initial thread: %w", resumeErr)
+			}
+			return nil
+		}
+
+		if err := windows.Thread32Next(snapshot, &entry); err != nil {
+			if errors.Is(err, windows.ERROR_NO_MORE_FILES) {
+				break
+			}
+			return fmt.Errorf("find initial thread: %w", err)
+		}
+	}
+	return fmt.Errorf("find initial thread: no thread found for process %d", processID)
+}
+
+func (tree *windowsProcessTree) TerminateGracefully() error {
+	// Windows jobs have no portable graceful signal. Terminating the owned job
+	// is the safe fallback and prevents a descendant from escaping cleanup.
+	return tree.terminate()
+}
+
+func (tree *windowsProcessTree) TerminateForcefully() error {
+	return tree.terminate()
+}
+
+func (tree *windowsProcessTree) Dispose() error {
+	if tree.job == 0 {
+		return nil
+	}
+	err := windows.CloseHandle(tree.job)
+	tree.job = 0
+	return err
+}
+
+func (tree *windowsProcessTree) terminate() error {
+	if tree.job == 0 {
+		return nil
+	}
+	return windows.TerminateJobObject(tree.job, 1)
+}

internal/adapters/subprocess/run.go

@@ -2,28 +2,27 @@ package subprocess
 
 import (
 	"context"
-	"errors"
 	"fmt"
-	"io"
 	"os"
 	"os/exec"
-	"path/filepath"
-	"sort"
 	"strings"
 	"time"
 
+	"gitea.maximumdirect.net/eric/narratio/internal/fileops"
 	"gopkg.in/yaml.v3"
 )
 
 // RunRequest defines a subprocess invocation.
 type RunRequest struct {
-	Executable    string
-	Args          []string
-	WorkingDir    string
-	EnvOverrides  map[string]string
-	Timeout       time.Duration
-	StdoutLogPath string
-	StderrLogPath string
+	Executable        string
+	Args              []string
+	WorkingDir        string
+	EnvOverrides      map[string]string
+	SensitiveEnvNames []string
+	DiagnosticOwner   string
+	Timeout           time.Duration
+	StdoutLogPath     string
+	StderrLogPath     string
 }
 
 // RunResult captures subprocess execution details.
@@ -54,17 +53,26 @@ func Run(ctx context.Context, req RunRequest) (RunResult, error) {
 	}
 	defer cancel()
 
-	logs, err := openLogWriters(req.StdoutLogPath, req.StderrLogPath)
+	childEnv := buildChildEnvironment(os.Environ(), req.EnvOverrides)
+	logs, err := openLogWriters(req.StdoutLogPath, req.StderrLogPath, req.diagnosticOwner(), sensitiveEnvironmentValues(childEnv, req.SensitiveEnvNames))
 	if err != nil {
 		return RunResult{}, err
 	}
 	defer logs.Close()
 
-	cmd := exec.CommandContext(runCtx, req.Executable, req.Args...)
+	tree, err := newOwnedProcessTree()
+	if err != nil {
+		return RunResult{}, fmt.Errorf("prepare owned subprocess tree: %w", err)
+	}
+
+	cmd := exec.Command(req.Executable, req.Args...)
 	cmd.Dir = req.WorkingDir
-	cmd.Env = mergeEnv(os.Environ(), req.EnvOverrides)
+	cmd.Env = childEnv
 	cmd.Stdout = logs.Stdout
 	cmd.Stderr = logs.Stderr
+	// Streaming capture uses pipes. Bound their lifetime when a leader exits
+	// while a descendant still holds a stream descriptor.
+	cmd.WaitDelay = forcefulTerminationWait
 
 	started := time.Now().UTC()
 	result := RunResult{
@@ -74,45 +82,67 @@ func Run(ctx context.Context, req RunRequest) (RunResult, error) {
 		StderrLogPath: req.StderrLogPath,
 	}
 
-	if err := cmd.Start(); err != nil {
+	if err := runCtx.Err(); err != nil {
+		result.CompletedAt = time.Now().UTC()
+		result.Duration = result.CompletedAt.Sub(result.StartedAt)
+		return result, fmt.Errorf("command was not started: %w", err)
+	}
+
+	if err := tree.Start(cmd); err != nil {
 		result.CompletedAt = time.Now().UTC()
 		result.Duration = result.CompletedAt.Sub(result.StartedAt)
 		return result, fmt.Errorf("start command %q with args %v: %w", req.Executable, req.Args, err)
 	}
 
-	waitErr := cmd.Wait()
+	waitCh := make(chan error, 1)
+	go func() { waitCh <- cmd.Wait() }()
+
+	waitErr, ctxErr, captureLimit, cleanupErr := waitForOwnedCommand(runCtx, tree, waitCh, logs.Limits())
+	cleanupErr = joinErrors(cleanupErr, tree.Dispose())
+	cleanupErr = joinErrors(cleanupErr, logs.Flush())
+	if captureLimit == nil {
+		captureLimit = logs.Limit()
+	}
 	result.CompletedAt = time.Now().UTC()
 	result.Duration = result.CompletedAt.Sub(result.StartedAt)
 	if cmd.ProcessState != nil {
 		result.ExitCode = cmd.ProcessState.ExitCode()
 	}
 
-	ctxErr := runCtx.Err()
-	if errors.Is(ctxErr, context.DeadlineExceeded) {
+	if ctxErr == context.DeadlineExceeded {
 		result.TimedOut = true
 	}
-	if errors.Is(ctxErr, context.Canceled) && !result.TimedOut {
+	if ctxErr == context.Canceled && !result.TimedOut {
 		result.Canceled = true
 	}
 
-	if waitErr == nil {
+	if waitErr == nil && ctxErr == nil && cleanupErr == nil {
 		return result, nil
 	}
 
-	stderrTail := readRedactedTail(req.StderrLogPath, req.EnvOverrides, 2048)
+	stderrTail := logs.stderr.Tail()
 	diagnostics := buildDiagnostics(req, result, stderrTail)
 
+	if captureLimit != nil {
+		if cause := joinErrors(waitErr, cleanupErr); cause != nil {
+			return result, fmt.Errorf("%w (%s): %w", captureLimit, diagnostics, cause)
+		}
+		return result, fmt.Errorf("%w (%s)", captureLimit, diagnostics)
+	}
 	if result.TimedOut {
-		return result, fmt.Errorf("command timed out after %s (%s)", req.Timeout, diagnostics)
+		return result, fmt.Errorf("command timed out after %s (%s): %w", req.Timeout, diagnostics, joinErrors(ctxErr, waitErr, cleanupErr))
 	}
 	if result.Canceled {
-		return result, fmt.Errorf("command canceled (%s)", diagnostics)
+		return result, fmt.Errorf("command canceled (%s): %w", diagnostics, joinErrors(ctxErr, waitErr, cleanupErr))
 	}
 	if exitErr, ok := waitErr.(*exec.ExitError); ok {
-		return result, fmt.Errorf("command failed with exit code %d (%s): %w", exitErr.ExitCode(), diagnostics, waitErr)
+		return result, fmt.Errorf("command failed with exit code %d (%s): %w", exitErr.ExitCode(), diagnostics, joinErrors(waitErr, cleanupErr))
+	}
+	if cleanupErr != nil {
+		return result, fmt.Errorf("command cleanup failed (%s): %w", diagnostics, joinErrors(waitErr, cleanupErr))
 	}
 
-	return result, fmt.Errorf("command failed to run (%s): %w", diagnostics, waitErr)
+	return result, fmt.Errorf("command failed to run (%s): %w", diagnostics, joinErrors(waitErr, cleanupErr))
 }
 
 // WriteYAMLAtomic marshals value as YAML and atomically writes it to path.
@@ -127,141 +157,17 @@ func WriteYAMLAtomic(path string, value any, perm os.FileMode) error {
 	return nil
 }
 
-// WriteFileAtomic writes bytes via same-directory temp file + atomic rename.
+// WriteFileAtomic writes bytes through the shared durable replacement primitive.
 func WriteFileAtomic(path string, data []byte, perm os.FileMode) error {
 	if strings.TrimSpace(path) == "" {
 		return fmt.Errorf("write file: path is required")
 	}
-
-	dir := filepath.Dir(path)
-	if err := os.MkdirAll(dir, 0o755); err != nil {
-		return fmt.Errorf("create parent directory %q: %w", dir, err)
+	if err := fileops.WriteFileAtomic(path, data, perm); err != nil {
+		return fmt.Errorf("write file %q: %w", path, err)
 	}
-
-	base := filepath.Base(path)
-	tmp, err := os.CreateTemp(dir, "."+base+".tmp-*")
-	if err != nil {
-		return fmt.Errorf("create temp file: %w", err)
-	}
-	tmpPath := tmp.Name()
-	removeTmp := true
-	defer func() {
-		if removeTmp {
-			_ = os.Remove(tmpPath)
-		}
-	}()
-
-	if _, err := tmp.Write(data); err != nil {
-		_ = tmp.Close()
-		return fmt.Errorf("write temp file: %w", err)
-	}
-	if err := tmp.Sync(); err != nil {
-		_ = tmp.Close()
-		return fmt.Errorf("sync temp file: %w", err)
-	}
-	if err := tmp.Close(); err != nil {
-		return fmt.Errorf("close temp file: %w", err)
-	}
-	if err := os.Chmod(tmpPath, perm); err != nil {
-		return fmt.Errorf("chmod temp file: %w", err)
-	}
-	if err := os.Rename(tmpPath, path); err != nil {
-		return fmt.Errorf("rename temp file: %w", err)
-	}
-	removeTmp = false
 	return nil
 }
 
-type logWriters struct {
-	files  []*os.File
-	Stdout io.Writer
-	Stderr io.Writer
-}
-
-func (l *logWriters) Close() {
-	for _, f := range l.files {
-		_ = f.Close()
-	}
-}
-
-func openLogWriters(stdoutPath, stderrPath string) (*logWriters, error) {
-	cleanStdout := cleanLogPath(stdoutPath)
-	cleanStderr := cleanLogPath(stderrPath)
-
-	// Keep stdout/stderr on the same file descriptor when both paths target
-	// the same file to avoid descriptor aliasing surprises across runtimes.
-	if cleanStdout != "" && cleanStdout == cleanStderr {
-		f, err := openLogFile(cleanStdout)
-		if err != nil {
-			return nil, fmt.Errorf("open shared stdout/stderr log %q: %w", cleanStdout, err)
-		}
-		return &logWriters{
-			files:  []*os.File{f},
-			Stdout: f,
-			Stderr: f,
-		}, nil
-	}
-
-	stdoutFile, stdoutWriter, err := logWriter(cleanStdout)
-	if err != nil {
-		return nil, fmt.Errorf("open stdout log: %w", err)
-	}
-	stderrFile, stderrWriter, err := logWriter(cleanStderr)
-	if err != nil {
-		closeFile(stdoutFile)
-		return nil, fmt.Errorf("open stderr log: %w", err)
-	}
-
-	files := make([]*os.File, 0, 2)
-	if stdoutFile != nil {
-		files = append(files, stdoutFile)
-	}
-	if stderrFile != nil {
-		files = append(files, stderrFile)
-	}
-	return &logWriters{
-		files:  files,
-		Stdout: stdoutWriter,
-		Stderr: stderrWriter,
-	}, nil
-}
-
-func cleanLogPath(path string) string {
-	trimmed := strings.TrimSpace(path)
-	if trimmed == "" {
-		return ""
-	}
-	return filepath.Clean(trimmed)
-}
-
-func logWriter(path string) (*os.File, io.Writer, error) {
-	if strings.TrimSpace(path) == "" {
-		return nil, io.Discard, nil
-	}
-	f, err := openLogFile(path)
-	if err != nil {
-		return nil, nil, err
-	}
-	return f, f, nil
-}
-
-func openLogFile(path string) (*os.File, error) {
-	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
-		return nil, fmt.Errorf("create log directory for %q: %w", path, err)
-	}
-	f, err := os.Create(path)
-	if err != nil {
-		return nil, fmt.Errorf("open log file %q: %w", path, err)
-	}
-	return f, nil
-}
-
-func closeFile(f *os.File) {
-	if f != nil {
-		_ = f.Close()
-	}
-}
-
 func buildDiagnostics(req RunRequest, result RunResult, stderrTail string) string {
 	details := fmt.Sprintf(
 		"executable=%q args=%v cwd=%q timeout=%s exit_code=%d timed_out=%t canceled=%t stdout_log=%q stderr_log=%q",
@@ -298,87 +204,3 @@ func fdDiagnosticsHint(exitCode int, stderrTail string) string {
 	}
 	return ""
 }
-
-func readRedactedTail(path string, envOverrides map[string]string, maxBytes int64) string {
-	if strings.TrimSpace(path) == "" || maxBytes <= 0 {
-		return ""
-	}
-	f, err := os.Open(path)
-	if err != nil {
-		return ""
-	}
-	defer f.Close()
-
-	info, err := f.Stat()
-	if err != nil {
-		return ""
-	}
-	size := info.Size()
-	start := int64(0)
-	if size > maxBytes {
-		start = size - maxBytes
-	}
-	if _, err := f.Seek(start, io.SeekStart); err != nil {
-		return ""
-	}
-	data, err := io.ReadAll(f)
-	if err != nil {
-		return ""
-	}
-	tail := strings.TrimSpace(string(data))
-	if tail == "" {
-		return ""
-	}
-	return redactSensitiveTail(tail, envOverrides)
-}
-
-func redactSensitiveTail(tail string, envOverrides map[string]string) string {
-	out := tail
-	for k, v := range envOverrides {
-		if strings.TrimSpace(v) == "" {
-			continue
-		}
-		if looksSensitiveEnvKey(k) {
-			out = strings.ReplaceAll(out, v, "<redacted>")
-		}
-	}
-	return out
-}
-
-func looksSensitiveEnvKey(key string) bool {
-	k := strings.ToUpper(strings.TrimSpace(key))
-	return strings.Contains(k, "KEY") ||
-		strings.Contains(k, "TOKEN") ||
-		strings.Contains(k, "SECRET") ||
-		strings.Contains(k, "PASSWORD")
-}
-
-func mergeEnv(base []string, overrides map[string]string) []string {
-	if len(overrides) == 0 {
-		return base
-	}
-
-	kv := make(map[string]string, len(base)+len(overrides))
-	for _, item := range base {
-		k, v, ok := strings.Cut(item, "=")
-		if !ok {
-			continue
-		}
-		kv[k] = v
-	}
-	for k, v := range overrides {
-		kv[k] = v
-	}
-
-	keys := make([]string, 0, len(kv))
-	for k := range kv {
-		keys = append(keys, k)
-	}
-	sort.Strings(keys)
-
-	out := make([]string, 0, len(keys))
-	for _, k := range keys {
-		out = append(out, k+"="+kv[k])
-	}
-	return out
-}

internal/adapters/subprocess/run_test.go

@@ -1,10 +1,17 @@
 package subprocess
 
 import (
+	"bytes"
 	"context"
+	"errors"
 	"os"
+	"os/exec"
+	"os/signal"
 	"path/filepath"
+	"runtime"
+	"strconv"
 	"strings"
+	"syscall"
 	"testing"
 	"time"
 
@@ -120,6 +127,316 @@ func TestRunFailureRedactsSensitiveTail(t *testing.T) {
 	if !strings.Contains(err.Error(), "<redacted>") {
 		t.Fatalf("error = %q, want redacted stderr tail marker", err.Error())
 	}
+	for _, path := range []string{req.StdoutLogPath, req.StderrLogPath} {
+		data, readErr := os.ReadFile(path)
+		if readErr != nil {
+			t.Fatalf("read diagnostic %q: %v", path, readErr)
+		}
+		if strings.Contains(string(data), secretValue) {
+			t.Fatalf("diagnostic %q leaked secret: %q", path, data)
+		}
+	}
+}
+
+func TestRunRejectsSymlinkDiagnosticWithoutTruncatingTarget(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("creating symlinks requires privileges that are not available on every Windows runner")
+	}
+	exe, err := os.Executable()
+	if err != nil {
+		t.Fatalf("os.Executable() error = %v", err)
+	}
+
+	dir := t.TempDir()
+	targetPath := filepath.Join(dir, "outside.log")
+	const original = "must remain unchanged"
+	if err := os.WriteFile(targetPath, []byte(original), 0o600); err != nil {
+		t.Fatalf("WriteFile(target) error = %v", err)
+	}
+	stdoutPath := filepath.Join(dir, "stdout.log")
+	if err := os.Symlink(targetPath, stdoutPath); err != nil {
+		t.Fatalf("Symlink() error = %v", err)
+	}
+
+	_, err = Run(context.Background(), RunRequest{
+		Executable:    exe,
+		Args:          []string{"-test.run=^TestSubprocessHelper$", "--", "success"},
+		EnvOverrides:  map[string]string{"GO_WANT_SUBPROCESS_HELPER": "1"},
+		StdoutLogPath: stdoutPath,
+		StderrLogPath: filepath.Join(dir, "stderr.log"),
+	})
+	if err == nil || !strings.Contains(err.Error(), "symbolic link") {
+		t.Fatalf("Run() error = %v, want symbolic-link rejection", err)
+	}
+	data, readErr := os.ReadFile(targetPath)
+	if readErr != nil {
+		t.Fatalf("ReadFile(target) error = %v", readErr)
+	}
+	if string(data) != original {
+		t.Fatalf("target content = %q, want %q", data, original)
+	}
+}
+
+func TestRunFailureUsesOpenedDiagnosticAfterPathReplacement(t *testing.T) {
+	exe, err := os.Executable()
+	if err != nil {
+		t.Fatalf("os.Executable() error = %v", err)
+	}
+
+	dir := t.TempDir()
+	readyPath := filepath.Join(dir, "ready")
+	releasePath := filepath.Join(dir, "release")
+	stderrPath := filepath.Join(dir, "stderr.log")
+	openedPath := filepath.Join(dir, "opened-stderr.log")
+	const secretValue = "replacement-api-key-value"
+	const commandContent = "trusted command failure"
+	req := RunRequest{
+		Executable: exe,
+		Args:       []string{"-test.run=^TestSubprocessHelper$", "--", "delayed-fail"},
+		EnvOverrides: map[string]string{
+			"GO_WANT_SUBPROCESS_HELPER":      "1",
+			"API_KEY":                        secretValue,
+			"SUBPROCESS_HELPER_READY_PATH":   readyPath,
+			"SUBPROCESS_HELPER_RELEASE_PATH": releasePath,
+			"SUBPROCESS_HELPER_STDERR":       commandContent,
+		},
+		StdoutLogPath: filepath.Join(dir, "stdout.log"),
+		StderrLogPath: stderrPath,
+	}
+
+	resultCh := make(chan error, 1)
+	go func() {
+		_, runErr := Run(context.Background(), req)
+		resultCh <- runErr
+	}()
+	waitForHelperFile(t, readyPath)
+	if err := os.Rename(stderrPath, openedPath); err != nil {
+		t.Fatalf("Rename(stderr log) error = %v", err)
+	}
+	if err := os.WriteFile(stderrPath, []byte(secretValue), 0o600); err != nil {
+		t.Fatalf("WriteFile(replacement) error = %v", err)
+	}
+	if err := os.WriteFile(releasePath, []byte("continue"), 0o600); err != nil {
+		t.Fatalf("WriteFile(release) error = %v", err)
+	}
+
+	select {
+	case runErr := <-resultCh:
+		if runErr == nil {
+			t.Fatal("Run() error = nil, want command failure")
+		}
+		if strings.Contains(runErr.Error(), secretValue) {
+			t.Fatalf("error read replacement-path content: %q", runErr)
+		}
+		if !strings.Contains(runErr.Error(), commandContent) {
+			t.Fatalf("error = %q, want retained command diagnostic", runErr)
+		}
+	case <-time.After(3 * time.Second):
+		t.Fatal("Run() did not return after helper release")
+	}
+
+	openedData, err := os.ReadFile(openedPath)
+	if err != nil {
+		t.Fatalf("ReadFile(opened diagnostic) error = %v", err)
+	}
+	if !strings.Contains(string(openedData), commandContent) {
+		t.Fatalf("opened diagnostic = %q, want command content", openedData)
+	}
+	replacementData, err := os.ReadFile(stderrPath)
+	if err != nil {
+		t.Fatalf("ReadFile(replacement diagnostic) error = %v", err)
+	}
+	if string(replacementData) != secretValue {
+		t.Fatalf("replacement diagnostic = %q, want %q", replacementData, secretValue)
+	}
+}
+
+func TestRunRedactsSplitCredentialInSeparateAndSharedDiagnostics(t *testing.T) {
+	exe, err := os.Executable()
+	if err != nil {
+		t.Fatalf("os.Executable() error = %v", err)
+	}
+	const secretValue = "split-super-secret-value"
+
+	for _, shared := range []bool{false, true} {
+		t.Run(map[bool]string{false: "separate", true: "shared"}[shared], func(t *testing.T) {
+			dir := t.TempDir()
+			stdoutPath := filepath.Join(dir, "stdout.log")
+			stderrPath := filepath.Join(dir, "stderr.log")
+			if shared {
+				stderrPath = stdoutPath
+			}
+			req := RunRequest{
+				Executable: exe,
+				Args:       []string{"-test.run=^TestSubprocessHelper$", "--", "splitsecret"},
+				EnvOverrides: map[string]string{
+					"GO_WANT_SUBPROCESS_HELPER": "1",
+					"API_KEY":                   secretValue,
+				},
+				StdoutLogPath: stdoutPath,
+				StderrLogPath: stderrPath,
+			}
+
+			_, runErr := Run(context.Background(), req)
+			if runErr == nil {
+				t.Fatal("Run() error = nil, want command failure")
+			}
+			if strings.Contains(runErr.Error(), secretValue) || !strings.Contains(runErr.Error(), "<redacted>") {
+				t.Fatalf("error = %q, want redacted credential", runErr)
+			}
+			paths := map[string]struct{}{stdoutPath: {}, stderrPath: {}}
+			for path := range paths {
+				data, readErr := os.ReadFile(path)
+				if readErr != nil {
+					t.Fatalf("ReadFile(%q) error = %v", path, readErr)
+				}
+				if strings.Contains(string(data), secretValue) || !strings.Contains(string(data), "<redacted>") {
+					t.Fatalf("diagnostic %q = %q, want redacted credential", path, data)
+				}
+			}
+		})
+	}
+}
+
+func TestRunRedactsInheritedSensitiveEnvironment(t *testing.T) {
+	exe, err := os.Executable()
+	if err != nil {
+		t.Fatalf("os.Executable() error = %v", err)
+	}
+	secretValue := "inherited-secret-value"
+	t.Setenv("OPENROUTER_API_KEY", secretValue)
+	dir := t.TempDir()
+	req := RunRequest{
+		Executable: exe,
+		Args:       []string{"-test.run=TestSubprocessHelper", "--", "echoenv"},
+		EnvOverrides: map[string]string{
+			"GO_WANT_SUBPROCESS_HELPER": "1",
+			"SUBPROCESS_HELPER_ENV_KEY": "OPENROUTER_API_KEY",
+		},
+		StdoutLogPath: filepath.Join(dir, "stdout.log"),
+		StderrLogPath: filepath.Join(dir, "stderr.log"),
+	}
+	_, err = Run(context.Background(), req)
+	if err == nil {
+		t.Fatal("Run() error = nil, want non-nil")
+	}
+	if strings.Contains(err.Error(), secretValue) {
+		t.Fatalf("error leaked inherited secret: %q", err)
+	}
+	for _, path := range []string{req.StdoutLogPath, req.StderrLogPath} {
+		data, readErr := os.ReadFile(path)
+		if readErr != nil {
+			t.Fatalf("read diagnostic %q: %v", path, readErr)
+		}
+		if strings.Contains(string(data), secretValue) {
+			t.Fatalf("diagnostic %q leaked inherited secret: %q", path, data)
+		}
+	}
+}
+
+func TestRunRedactsSensitiveOutputAndErrorTail(t *testing.T) {
+	exe, err := os.Executable()
+	if err != nil {
+		t.Fatalf("os.Executable() error = %v", err)
+	}
+	secretValue := "override-secret-value"
+	dir := t.TempDir()
+	req := RunRequest{
+		Executable: exe,
+		Args:       []string{"-test.run=TestSubprocessHelper", "--", "echoenv"},
+		EnvOverrides: map[string]string{
+			"GO_WANT_SUBPROCESS_HELPER": "1",
+			"SUBPROCESS_HELPER_ENV_KEY": "OPENROUTER_API_KEY",
+			"OPENROUTER_API_KEY":        secretValue,
+		},
+		StdoutLogPath: filepath.Join(dir, "stdout.log"),
+		StderrLogPath: filepath.Join(dir, "stderr.log"),
+	}
+	_, err = Run(context.Background(), req)
+	if err == nil {
+		t.Fatal("Run() error = nil, want non-nil")
+	}
+	if strings.Contains(err.Error(), secretValue) || !strings.Contains(err.Error(), "<redacted>") {
+		t.Fatalf("error = %q, want redacted secret", err)
+	}
+	for _, path := range []string{req.StdoutLogPath, req.StderrLogPath} {
+		data, readErr := os.ReadFile(path)
+		if readErr != nil {
+			t.Fatalf("read diagnostic %q: %v", path, readErr)
+		}
+		if strings.Contains(string(data), secretValue) || !strings.Contains(string(data), "<redacted>") {
+			t.Fatalf("diagnostic %q = %q, want redacted secret", path, data)
+		}
+	}
+}
+
+func TestStreamRedactorHandlesSplitAndOverlappingSecrets(t *testing.T) {
+	redactor := newStreamRedactor([]string{"abc", "abcde", "cde", ""})
+	var output bytes.Buffer
+	output.Write(redactor.Write([]byte("start-ab")))
+	output.Write(redactor.Write([]byte("cde-end")))
+	output.Write(redactor.Flush())
+	if got := output.String(); got != "start-<redacted>-end" {
+		t.Fatalf("redacted output = %q, want one redacted marker", got)
+	}
+}
+
+func TestDiagnosticWriterHonorsExactLimitAndCapPlusOne(t *testing.T) {
+	exactLogs := &logWriters{limits: make(chan *captureLimitError, 1)}
+	var exactOutput bytes.Buffer
+	exact := newDiagnosticWriter(exactLogs, "stdout", "test", &exactOutput, 5, nil)
+	if _, err := exact.Write([]byte("abcde")); err != nil {
+		t.Fatalf("exact Write() error = %v", err)
+	}
+	if err := exact.Flush(); err != nil {
+		t.Fatalf("exact Flush() error = %v", err)
+	}
+	if got := exactOutput.String(); got != "abcde" {
+		t.Fatalf("exact output = %q, want abcde", got)
+	}
+	if exactLogs.Limit() != nil {
+		t.Fatal("exact write recorded a capture limit")
+	}
+
+	cappedLogs := &logWriters{limits: make(chan *captureLimitError, 1)}
+	var cappedOutput bytes.Buffer
+	capped := newDiagnosticWriter(cappedLogs, "stderr", "test", &cappedOutput, 5, nil)
+	if _, err := capped.Write([]byte("abcdef")); err == nil {
+		t.Fatal("cap-plus-one Write() error = nil, want capture limit")
+	}
+	if err := capped.Flush(); err != nil {
+		t.Fatalf("cap-plus-one Flush() error = %v", err)
+	}
+	if got := cappedOutput.String(); got != "abcde" {
+		t.Fatalf("capped output = %q, want abcde", got)
+	}
+	if limit := cappedLogs.Limit(); limit == nil || limit.stream != "stderr" || limit.limit != 5 {
+		t.Fatalf("capture limit = %#v, want stderr limit 5", limit)
+	}
+}
+
+func TestDiagnosticWriterRetainsBoundedRedactedTail(t *testing.T) {
+	logs := &logWriters{limits: make(chan *captureLimitError, 1)}
+	var output bytes.Buffer
+	secret := "credential-value"
+	writer := newDiagnosticWriter(logs, "stderr", "test", &output, 16*1024, []string{secret})
+	prefix := strings.Repeat("x", diagnosticTailBytes+512)
+	if _, err := writer.Write([]byte(prefix + secret[:7])); err != nil {
+		t.Fatalf("first Write() error = %v", err)
+	}
+	if _, err := writer.Write([]byte(secret[7:] + "-failure")); err != nil {
+		t.Fatalf("second Write() error = %v", err)
+	}
+	if err := writer.Flush(); err != nil {
+		t.Fatalf("Flush() error = %v", err)
+	}
+	tail := writer.Tail()
+	if len(tail) > diagnosticTailBytes {
+		t.Fatalf("retained tail length = %d, want at most %d", len(tail), diagnosticTailBytes)
+	}
+	if strings.Contains(tail, secret) || !strings.Contains(tail, "<redacted>-failure") {
+		t.Fatalf("retained tail = %q, want bounded redacted content", tail)
+	}
 }
 
 func TestRunFailureAddsBadDescriptorHint(t *testing.T) {
@@ -184,15 +501,14 @@ func TestRunInheritsParentEnvironmentByDefault(t *testing.T) {
 		t.Fatalf("os.Executable() error = %v", err)
 	}
 
-	t.Setenv("GO_WANT_SUBPROCESS_HELPER", "1")
-	t.Setenv("SUBPROCESS_HELPER_ENV_KEY", "SUBPROCESS_PARENT_VALUE")
-	t.Setenv("SUBPROCESS_PARENT_VALUE", "inherited-value")
+	t.Setenv("PATH", "inherited-value")
 
 	dir := t.TempDir()
 	stdoutPath := filepath.Join(dir, "stdout.log")
 	req := RunRequest{
 		Executable:    exe,
 		Args:          []string{"-test.run=TestSubprocessHelper", "--", "printenv"},
+		EnvOverrides:  map[string]string{"GO_WANT_SUBPROCESS_HELPER": "1", "SUBPROCESS_HELPER_ENV_KEY": "PATH"},
 		StdoutLogPath: stdoutPath,
 	}
 
@@ -214,16 +530,16 @@ func TestRunEnvOverridesWinOverInheritedValues(t *testing.T) {
 		t.Fatalf("os.Executable() error = %v", err)
 	}
 
-	t.Setenv("GO_WANT_SUBPROCESS_HELPER", "1")
-	t.Setenv("SUBPROCESS_HELPER_ENV_KEY", "SUBPROCESS_PARENT_VALUE")
-	t.Setenv("SUBPROCESS_PARENT_VALUE", "parent-value")
-
 	dir := t.TempDir()
 	stdoutPath := filepath.Join(dir, "stdout.log")
 	req := RunRequest{
-		Executable:    exe,
-		Args:          []string{"-test.run=TestSubprocessHelper", "--", "printenv"},
-		EnvOverrides:  map[string]string{"SUBPROCESS_PARENT_VALUE": "override-value"},
+		Executable: exe,
+		Args:       []string{"-test.run=TestSubprocessHelper", "--", "printenv"},
+		EnvOverrides: map[string]string{
+			"GO_WANT_SUBPROCESS_HELPER": "1",
+			"SUBPROCESS_HELPER_ENV_KEY": "SUBPROCESS_PARENT_VALUE",
+			"SUBPROCESS_PARENT_VALUE":   "override-value",
+		},
 		StdoutLogPath: stdoutPath,
 	}
 
@@ -361,6 +677,30 @@ func TestSubprocessHelper(t *testing.T) {
 	case "failbadfd":
 		_, _ = os.Stderr.WriteString("OSError: [Errno 9] Bad file descriptor\n")
 		os.Exit(120)
+	case "delayed-fail":
+		if err := os.WriteFile(os.Getenv("SUBPROCESS_HELPER_READY_PATH"), []byte("ready"), 0o600); err != nil {
+			os.Exit(4)
+		}
+		deadline := time.Now().Add(2 * time.Second)
+		for {
+			if _, err := os.Stat(os.Getenv("SUBPROCESS_HELPER_RELEASE_PATH")); err == nil {
+				break
+			} else if !errors.Is(err, os.ErrNotExist) || time.Now().After(deadline) {
+				os.Exit(5)
+			}
+			time.Sleep(10 * time.Millisecond)
+		}
+		_, _ = os.Stderr.WriteString(os.Getenv("SUBPROCESS_HELPER_STDERR"))
+		os.Exit(6)
+	case "splitsecret":
+		secret := os.Getenv("API_KEY")
+		split := len(secret) / 2
+		for _, stream := range []*os.File{os.Stdout, os.Stderr} {
+			_, _ = stream.WriteString(secret[:split])
+			time.Sleep(20 * time.Millisecond)
+			_, _ = stream.WriteString(secret[split:] + "\n")
+		}
+		os.Exit(7)
 	case "sleep":
 		time.Sleep(500 * time.Millisecond)
 		os.Exit(0)
@@ -368,7 +708,115 @@ func TestSubprocessHelper(t *testing.T) {
 		key := os.Getenv("SUBPROCESS_HELPER_ENV_KEY")
 		_, _ = os.Stdout.WriteString(os.Getenv(key) + "\n")
 		os.Exit(0)
+	case "echoenv":
+		key := os.Getenv("SUBPROCESS_HELPER_ENV_KEY")
+		value := os.Getenv(key)
+		_, _ = os.Stdout.WriteString(value)
+		_, _ = os.Stderr.WriteString(value)
+		os.Exit(5)
+	case "spam":
+		chunk := strings.Repeat("x", 64*1024)
+		count, _ := strconv.Atoi(os.Getenv("SUBPROCESS_HELPER_CHUNKS"))
+		for range count {
+			_, _ = os.Stdout.WriteString(chunk)
+		}
+		os.Exit(0)
+	case "tree-spam":
+		descendant := exec.Command(os.Args[0], "-test.run=^TestSubprocessHelper$", "--", "descendant")
+		descendant.Env = append(os.Environ(), "GO_WANT_SUBPROCESS_HELPER=1")
+		descendant.Stdout = os.Stdout
+		descendant.Stderr = os.Stderr
+		if err := descendant.Start(); err != nil {
+			os.Exit(3)
+		}
+		if err := os.WriteFile(os.Getenv("SUBPROCESS_HELPER_READY_PATH"), []byte("ready"), 0o600); err != nil {
+			os.Exit(4)
+		}
+		chunk := strings.Repeat("x", 64*1024)
+		for {
+			_, _ = os.Stdout.WriteString(chunk)
+		}
+	case "tree":
+		descendant := exec.Command(os.Args[0], "-test.run=^TestSubprocessHelper$", "--", "descendant")
+		descendant.Env = append(os.Environ(), "GO_WANT_SUBPROCESS_HELPER=1")
+		descendant.Stdout = os.Stdout
+		descendant.Stderr = os.Stderr
+		if err := descendant.Start(); err != nil {
+			os.Exit(3)
+		}
+		if err := os.WriteFile(os.Getenv("SUBPROCESS_HELPER_READY_PATH"), []byte("ready"), 0o600); err != nil {
+			os.Exit(4)
+		}
+		time.Sleep(10 * time.Second)
+		os.Exit(0)
+	case "leader-exit-retained", "leader-exit-redirected", "leader-fail-redirected":
+		descendant := exec.Command(os.Args[0], "-test.run=^TestSubprocessHelper$", "--", "descendant-after-release")
+		descendant.Env = append(os.Environ(), "GO_WANT_SUBPROCESS_HELPER=1")
+		if mode == "leader-exit-retained" {
+			descendant.Stdout = os.Stdout
+			descendant.Stderr = os.Stderr
+		}
+		if err := descendant.Start(); err != nil {
+			os.Exit(3)
+		}
+		if !helperFileAppeared(os.Getenv("SUBPROCESS_HELPER_READY_PATH"), 2*time.Second) {
+			os.Exit(4)
+		}
+		if mode == "leader-fail-redirected" {
+			os.Exit(9)
+		}
+		os.Exit(0)
+	case "descendant-after-release":
+		if os.Getenv("SUBPROCESS_HELPER_IGNORE_TERM") == "1" {
+			signal.Ignore(syscall.SIGTERM)
+		}
+		if err := os.WriteFile(os.Getenv("SUBPROCESS_HELPER_READY_PATH"), []byte("ready"), 0o600); err != nil {
+			os.Exit(4)
+		}
+		deadline := time.Now().Add(10 * time.Second)
+		for time.Now().Before(deadline) {
+			if _, err := os.Stat(os.Getenv("SUBPROCESS_HELPER_RELEASE_PATH")); err == nil {
+				_ = os.WriteFile(os.Getenv("SUBPROCESS_HELPER_SENTINEL_PATH"), []byte("survived"), 0o600)
+				os.Exit(0)
+			} else if !errors.Is(err, os.ErrNotExist) {
+				os.Exit(5)
+			}
+			time.Sleep(10 * time.Millisecond)
+		}
+		os.Exit(0)
+	case "descendant":
+		time.Sleep(500 * time.Millisecond)
+		_ = os.WriteFile(os.Getenv("SUBPROCESS_HELPER_SENTINEL_PATH"), []byte("survived"), 0o600)
+		time.Sleep(10 * time.Second)
+		os.Exit(0)
 	default:
 		os.Exit(2)
 	}
 }
+
+func waitForHelperFile(t *testing.T, path string) {
+	t.Helper()
+	deadline := time.Now().Add(2 * time.Second)
+	for time.Now().Before(deadline) {
+		if _, err := os.Stat(path); err == nil {
+			return
+		} else if !errors.Is(err, os.ErrNotExist) {
+			t.Fatalf("Stat(%q) error = %v", path, err)
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+	t.Fatalf("helper file %q was not created", path)
+}
+
+func helperFileAppeared(path string, timeout time.Duration) bool {
+	deadline := time.Now().Add(timeout)
+	for time.Now().Before(deadline) {
+		if _, err := os.Stat(path); err == nil {
+			return true
+		} else if !errors.Is(err, os.ErrNotExist) {
+			return false
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+	return false
+}

internal/adapters/whisperx/fake.go

@@ -2,8 +2,10 @@ package whisperx
 
 import (
 	"context"
-	"os"
 	"path/filepath"
+	"sync"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/fileops"
 )
 
 var minimalTranscriptJSON = []byte(`{"schema":"speaker_transcript.v1","segments":[]}`)
@@ -31,7 +33,8 @@ func (n *NoopClient) Transcribe(ctx context.Context, req TranscribeRequest) (Tra
 
 // FakeClient captures requests and returns deterministic responses for tests.
 type FakeClient struct {
-	Requests     []TranscribeRequest
+	requestsMu   sync.RWMutex
+	requests     []TranscribeRequest
 	Err          error
 	Result       TranscribeResult
 	TranscribeFn func(ctx context.Context, req TranscribeRequest) (TranscribeResult, error)
@@ -42,7 +45,9 @@ func (f *FakeClient) Transcribe(ctx context.Context, req TranscribeRequest) (Tra
 	if err := ctx.Err(); err != nil {
 		return TranscribeResult{}, err
 	}
-	f.Requests = append(f.Requests, req)
+	f.requestsMu.Lock()
+	f.requests = append(f.requests, req)
+	f.requestsMu.Unlock()
 	if f.TranscribeFn != nil {
 		return f.TranscribeFn(ctx, req)
 	}
@@ -65,12 +70,19 @@ func (f *FakeClient) Transcribe(ctx context.Context, req TranscribeRequest) (Tra
 	return res, nil
 }
 
+// RequestsSnapshot returns a copy of captured requests safe for concurrent test assertions.
+func (f *FakeClient) RequestsSnapshot() []TranscribeRequest {
+	f.requestsMu.RLock()
+	defer f.requestsMu.RUnlock()
+	return append([]TranscribeRequest(nil), f.requests...)
+}
+
 func writeMinimalJSON(path string) error {
 	if path == "" {
 		return nil
 	}
-	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+	if err := fileops.EnsureWorkspaceDirectory(filepath.Dir(path)); err != nil {
 		return err
 	}
-	return os.WriteFile(path, minimalTranscriptJSON, 0o644)
+	return fileops.WriteFileAtomic(path, minimalTranscriptJSON, fileops.WorkspaceFileMode)
 }

internal/adapters/whisperx/fake_test.go

@@ -3,6 +3,7 @@ package whisperx
 import (
 	"context"
 	"errors"
+	"sync"
 	"testing"
 )
 
@@ -14,8 +15,9 @@ func TestFakeClientCapturesRequestAndReturnsPath(t *testing.T) {
 	if err != nil {
 		t.Fatalf("Transcribe() error = %v", err)
 	}
-	if len(fake.Requests) != 1 || fake.Requests[0].SpeakerID != "alice" {
-		t.Fatalf("requests = %#v, want one alice request", fake.Requests)
+	requests := fake.RequestsSnapshot()
+	if len(requests) != 1 || requests[0].SpeakerID != "alice" {
+		t.Fatalf("requests = %#v, want one alice request", requests)
 	}
 	if res.OutputRawTranscriptPath != req.OutputRawTranscriptPath {
 		t.Fatalf("output path = %q, want %q", res.OutputRawTranscriptPath, req.OutputRawTranscriptPath)
@@ -29,3 +31,22 @@ func TestFakeClientError(t *testing.T) {
 		t.Fatal("expected error, got nil")
 	}
 }
+
+func TestFakeClientRequestsSnapshotSupportsConcurrentCalls(t *testing.T) {
+	fake := &FakeClient{}
+	const callers = 16
+	var group sync.WaitGroup
+	group.Add(callers)
+	for i := 0; i < callers; i++ {
+		go func() {
+			defer group.Done()
+			if _, err := fake.Transcribe(context.Background(), TranscribeRequest{}); err != nil {
+				t.Errorf("Transcribe() error = %v", err)
+			}
+		}()
+	}
+	group.Wait()
+	if got := len(fake.RequestsSnapshot()); got != callers {
+		t.Fatalf("captured requests = %d, want %d", got, callers)
+	}
+}

internal/adapters/whisperx/http.go

@@ -1,7 +1,6 @@
 package whisperx
 
 import (
-	"bytes"
 	"context"
 	"encoding/json"
 	"errors"
@@ -14,10 +13,16 @@ import (
 	"os"
 	"path/filepath"
 	"strings"
+	"sync"
 	"time"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/fileops"
 )
 
-const defaultMaxResponseBytes int64 = 10 * 1024 * 1024
+const (
+	defaultMaxWhisperXResponseBytes int64 = 10 * 1024 * 1024
+	whisperXUploadBufferSize              = 32 * 1024
+)
 
 // HTTPClientConfig contains parsed, deterministic WhisperX HTTP client settings.
 type HTTPClientConfig struct {
@@ -39,6 +44,7 @@ type HTTPClient struct {
 	retryDelay       time.Duration
 	httpClient       *http.Client
 	maxResponseBytes int64
+	openAudio        func(string) (io.ReadCloser, error)
 }
 
 // NewHTTPClientFromConfigValues builds a client from config values and parses durations once.
@@ -72,11 +78,11 @@ func NewHTTPClient(cfg HTTPClientConfig) (*HTTPClient, error) {
 		return nil, fmt.Errorf("whisperx transcribe_url is required")
 	}
 	u, err := url.Parse(cfg.TranscribeURL)
-	if err != nil || u.Scheme == "" || u.Host == "" {
+	if err != nil || !u.IsAbs() || u.Host == "" || !isHTTPURLScheme(u.Scheme) {
 		if err != nil {
 			return nil, fmt.Errorf("invalid whisperx transcribe_url %q: %w", cfg.TranscribeURL, err)
 		}
-		return nil, fmt.Errorf("invalid whisperx transcribe_url %q", cfg.TranscribeURL)
+		return nil, fmt.Errorf("invalid whisperx transcribe_url %q: must be an absolute http or https URL", cfg.TranscribeURL)
 	}
 	if cfg.Timeout <= 0 {
 		return nil, fmt.Errorf("whisperx timeout must be > 0")
@@ -93,12 +99,14 @@ func NewHTTPClient(cfg HTTPClientConfig) (*HTTPClient, error) {
 
 	client := cfg.HTTPClient
 	if client == nil {
-		client = &http.Client{}
+		transport := http.DefaultTransport.(*http.Transport).Clone()
+		transport.ExpectContinueTimeout = 100 * time.Millisecond
+		client = &http.Client{Transport: transport}
 	}
 
 	maxBytes := cfg.MaxResponseBytes
 	if maxBytes <= 0 {
-		maxBytes = defaultMaxResponseBytes
+		maxBytes = defaultMaxWhisperXResponseBytes
 	}
 
 	return &HTTPClient{
@@ -109,6 +117,7 @@ func NewHTTPClient(cfg HTTPClientConfig) (*HTTPClient, error) {
 		retryDelay:       cfg.RetryDelay,
 		httpClient:       client,
 		maxResponseBytes: maxBytes,
+		openAudio:        func(path string) (io.ReadCloser, error) { return os.Open(path) },
 	}, nil
 }
 
@@ -147,7 +156,7 @@ func (c *HTTPClient) Transcribe(ctx context.Context, req TranscribeRequest) (Tra
 				result.Duration = time.Since(start)
 				return result, fmt.Errorf("whisperx attempt %d returned invalid json: %w", attempt, err)
 			}
-			if err := writeFileAtomic(req.OutputRawTranscriptPath, body, 0o644); err != nil {
+			if err := writeFileAtomic(req.OutputRawTranscriptPath, body, fileops.WorkspaceFileMode); err != nil {
 				result.Duration = time.Since(start)
 				return result, fmt.Errorf("whisperx write transcript output %q: %w", req.OutputRawTranscriptPath, err)
 			}
@@ -183,52 +192,44 @@ func (c *HTTPClient) Transcribe(ctx context.Context, req TranscribeRequest) (Tra
 }
 
 func (c *HTTPClient) doTranscribeAttempt(ctx context.Context, audioPath string) (int, []byte, error) {
-	bodyBuf := &bytes.Buffer{}
-	writer := multipart.NewWriter(bodyBuf)
+	upload := newMultipartUpload(ctx, audioPath, c.language, c.openAudio)
+	defer upload.Close()
 
-	fileWriter, err := writer.CreateFormFile("file", filepath.Base(audioPath))
-	if err != nil {
-		return 0, nil, fmt.Errorf("create multipart file field: %w", err)
-	}
-
-	audioFile, err := os.Open(audioPath)
-	if err != nil {
-		return 0, nil, fmt.Errorf("open audio file %q: %w", audioPath, err)
-	}
-	if _, err := io.Copy(fileWriter, audioFile); err != nil {
-		_ = audioFile.Close()
-		return 0, nil, fmt.Errorf("copy audio file %q: %w", audioPath, err)
-	}
-	if err := audioFile.Close(); err != nil {
-		return 0, nil, fmt.Errorf("close audio file %q: %w", audioPath, err)
-	}
-
-	if err := writer.WriteField("language", c.language); err != nil {
-		return 0, nil, fmt.Errorf("write language form field: %w", err)
-	}
-	if err := writer.Close(); err != nil {
-		return 0, nil, fmt.Errorf("close multipart writer: %w", err)
-	}
-
-	req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.url.String(), bodyBuf)
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.url.String(), upload)
 	if err != nil {
 		return 0, nil, fmt.Errorf("build whisperx request: %w", err)
 	}
-	req.Header.Set("Content-Type", writer.FormDataContentType())
+	req.Header.Set("Content-Type", upload.contentType)
+	req.Header.Set("Expect", "100-continue")
 
 	resp, err := c.httpClient.Do(req)
 	if err != nil {
+		_ = upload.Close()
+		if producerErr := upload.Wait(); producerErr != nil {
+			return 0, nil, fmt.Errorf("stream whisperx request body: %w", producerErr)
+		}
 		return 0, nil, fmt.Errorf("perform whisperx request: %w", err)
 	}
 	defer resp.Body.Close()
 
-	data, err := readBounded(resp.Body, c.maxResponseBytes)
-	if err != nil {
-		return resp.StatusCode, nil, fmt.Errorf("read whisperx response body: %w", err)
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		_ = upload.Close()
+		if producerErr := upload.Wait(); producerErr != nil {
+			return resp.StatusCode, nil, fmt.Errorf("stream whisperx request body: %w", producerErr)
+		}
+		if _, err := readWhisperXResponse(resp.Body, c.maxResponseBytes); err != nil {
+			return resp.StatusCode, nil, fmt.Errorf("read whisperx response body: %w", err)
+		}
+		return resp.StatusCode, nil, fmt.Errorf("whisperx returned status %d", resp.StatusCode)
 	}
 
-	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
-		return resp.StatusCode, nil, fmt.Errorf("whisperx returned status %d", resp.StatusCode)
+	if err := upload.Wait(); err != nil {
+		return resp.StatusCode, nil, fmt.Errorf("stream whisperx request body: %w", err)
+	}
+
+	data, err := readWhisperXResponse(resp.Body, c.maxResponseBytes)
+	if err != nil {
+		return resp.StatusCode, nil, fmt.Errorf("read whisperx response body: %w", err)
 	}
 	return resp.StatusCode, data, nil
 }
@@ -264,57 +265,188 @@ func (c *HTTPClient) shouldRetry(parent context.Context, err error, status int)
 	return false
 }
 
-func readBounded(r io.Reader, maxBytes int64) ([]byte, error) {
+func readWhisperXResponse(r io.Reader, maxBytes int64) ([]byte, error) {
 	limited := io.LimitReader(r, maxBytes+1)
 	data, err := io.ReadAll(limited)
 	if err != nil {
 		return nil, err
 	}
 	if int64(len(data)) > maxBytes {
-		return nil, fmt.Errorf("response exceeds max size %d bytes", maxBytes)
+		return nil, fmt.Errorf("whisperx response exceeds configured limit of %d bytes", maxBytes)
 	}
 	return data, nil
 }
 
+func isHTTPURLScheme(scheme string) bool {
+	switch strings.ToLower(scheme) {
+	case "http", "https":
+		return true
+	default:
+		return false
+	}
+}
+
+type multipartUpload struct {
+	reader      *io.PipeReader
+	writer      *io.PipeWriter
+	contentType string
+	done        chan struct{}
+
+	mu      sync.Mutex
+	audio   io.Closer
+	err     error
+	aborted bool
+}
+
+func newMultipartUpload(ctx context.Context, audioPath, language string, openAudio func(string) (io.ReadCloser, error)) *multipartUpload {
+	reader, writer := io.Pipe()
+	multipartWriter := multipart.NewWriter(writer)
+	upload := &multipartUpload{
+		reader:      reader,
+		writer:      writer,
+		contentType: multipartWriter.FormDataContentType(),
+		done:        make(chan struct{}),
+	}
+
+	go func() {
+		err := upload.write(ctx, multipartWriter, audioPath, language, openAudio)
+		if err != nil {
+			_ = writer.CloseWithError(err)
+		} else {
+			_ = writer.Close()
+		}
+		upload.mu.Lock()
+		upload.err = err
+		upload.audio = nil
+		upload.mu.Unlock()
+		close(upload.done)
+	}()
+
+	go func() {
+		select {
+		case <-ctx.Done():
+			upload.abort()
+		case <-upload.done:
+		}
+	}()
+
+	return upload
+}
+
+func (u *multipartUpload) Read(p []byte) (int, error) {
+	return u.reader.Read(p)
+}
+
+func (u *multipartUpload) Close() error {
+	u.abort()
+	return nil
+}
+
+func (u *multipartUpload) Wait() error {
+	<-u.done
+	u.mu.Lock()
+	defer u.mu.Unlock()
+	return u.err
+}
+
+func (u *multipartUpload) write(ctx context.Context, writer *multipart.Writer, audioPath, language string, openAudio func(string) (io.ReadCloser, error)) error {
+	fileWriter, err := writer.CreateFormFile("file", filepath.Base(audioPath))
+	if err != nil {
+		return u.producerError(ctx, fmt.Errorf("create multipart file field: %w", err))
+	}
+
+	audioFile, err := openAudio(audioPath)
+	if err != nil {
+		return u.producerError(ctx, fmt.Errorf("open audio file %q: %w", audioPath, err))
+	}
+	u.setAudio(audioFile)
+
+	_, copyErr := io.CopyBuffer(fileWriter, &contextReader{ctx: ctx, reader: audioFile}, make([]byte, whisperXUploadBufferSize))
+	closeErr := audioFile.Close()
+	u.clearAudio(audioFile)
+	if copyErr != nil {
+		return u.producerError(ctx, fmt.Errorf("copy audio file %q: %w", audioPath, copyErr))
+	}
+	if closeErr != nil {
+		return u.producerError(ctx, fmt.Errorf("close audio file %q: %w", audioPath, closeErr))
+	}
+
+	if err := writer.WriteField("language", language); err != nil {
+		return u.producerError(ctx, fmt.Errorf("write language form field: %w", err))
+	}
+	if err := writer.Close(); err != nil {
+		return u.producerError(ctx, fmt.Errorf("close multipart writer: %w", err))
+	}
+	return nil
+}
+
+func (u *multipartUpload) producerError(ctx context.Context, err error) error {
+	if ctx.Err() != nil {
+		return ctx.Err()
+	}
+	u.mu.Lock()
+	aborted := u.aborted
+	u.mu.Unlock()
+	if aborted {
+		return nil
+	}
+	return err
+}
+
+func (u *multipartUpload) setAudio(audio io.Closer) {
+	u.mu.Lock()
+	u.audio = audio
+	aborted := u.aborted
+	u.mu.Unlock()
+	if aborted {
+		_ = audio.Close()
+	}
+}
+
+func (u *multipartUpload) clearAudio(audio io.Closer) {
+	u.mu.Lock()
+	if u.audio == audio {
+		u.audio = nil
+	}
+	u.mu.Unlock()
+}
+
+func (u *multipartUpload) abort() {
+	u.mu.Lock()
+	if u.aborted {
+		u.mu.Unlock()
+		return
+	}
+	u.aborted = true
+	audio := u.audio
+	u.mu.Unlock()
+
+	_ = u.reader.Close()
+	if audio != nil {
+		_ = audio.Close()
+	}
+}
+
+type contextReader struct {
+	ctx    context.Context
+	reader io.Reader
+}
+
+func (r *contextReader) Read(p []byte) (int, error) {
+	select {
+	case <-r.ctx.Done():
+		return 0, r.ctx.Err()
+	default:
+		return r.reader.Read(p)
+	}
+}
+
 func writeFileAtomic(path string, data []byte, perm os.FileMode) error {
 	if strings.TrimSpace(path) == "" {
 		return fmt.Errorf("path is required")
 	}
-	dir := filepath.Dir(path)
-	if err := os.MkdirAll(dir, 0o755); err != nil {
-		return fmt.Errorf("create parent dir %q: %w", dir, err)
+	if err := fileops.WriteFileAtomic(path, data, perm); err != nil {
+		return fmt.Errorf("write file %q: %w", path, err)
 	}
-
-	base := filepath.Base(path)
-	tmp, err := os.CreateTemp(dir, "."+base+".tmp-*")
-	if err != nil {
-		return fmt.Errorf("create temp file: %w", err)
-	}
-	tmpPath := tmp.Name()
-	removeTmp := true
-	defer func() {
-		if removeTmp {
-			_ = os.Remove(tmpPath)
-		}
-	}()
-
-	if _, err := tmp.Write(data); err != nil {
-		_ = tmp.Close()
-		return fmt.Errorf("write temp file: %w", err)
-	}
-	if err := tmp.Sync(); err != nil {
-		_ = tmp.Close()
-		return fmt.Errorf("sync temp file: %w", err)
-	}
-	if err := tmp.Close(); err != nil {
-		return fmt.Errorf("close temp file: %w", err)
-	}
-	if err := os.Chmod(tmpPath, perm); err != nil {
-		return fmt.Errorf("chmod temp file: %w", err)
-	}
-	if err := os.Rename(tmpPath, path); err != nil {
-		return fmt.Errorf("rename temp file: %w", err)
-	}
-	removeTmp = false
 	return nil
 }

internal/adapters/whisperx/http_test.go

@@ -5,6 +5,7 @@ import (
 	"encoding/json"
 	"errors"
 	"io"
+	"mime/multipart"
 	"net/http"
 	"net/http/httptest"
 	"os"
@@ -19,6 +20,7 @@ func TestHTTPClientTranscribeSuccess(t *testing.T) {
 	var gotLanguage string
 	var gotFileField string
 	var gotFileSize int
+	var gotFileData string
 
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if r.Method != http.MethodPost {
@@ -40,6 +42,7 @@ func TestHTTPClientTranscribeSuccess(t *testing.T) {
 			t.Fatalf("ReadAll(file) error = %v", err)
 		}
 		gotFileSize = len(data)
+		gotFileData = string(data)
 
 		w.Header().Set("Content-Type", "application/json")
 		_, _ = w.Write([]byte(`{"schema":"speaker_transcript.v1","segments":[]}`))
@@ -77,13 +80,27 @@ func TestHTTPClientTranscribeSuccess(t *testing.T) {
 	if gotFileSize == 0 {
 		t.Fatal("file size = 0, want >0")
 	}
+	if gotFileData != "audio-data" {
+		t.Fatalf("file data = %q, want exact payload", gotFileData)
+	}
 	verifyJSONFile(t, outPath)
 }
 
 func TestHTTPClientRetriesOnTransientAndSucceeds(t *testing.T) {
 	var calls atomic.Int32
+	var payloads []string
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		n := calls.Add(1)
+		file, _, err := r.FormFile("file")
+		if err != nil {
+			t.Fatalf("FormFile(file) error = %v", err)
+		}
+		data, err := io.ReadAll(file)
+		_ = file.Close()
+		if err != nil {
+			t.Fatalf("ReadAll(file) error = %v", err)
+		}
+		payloads = append(payloads, string(data))
 		if n == 1 {
 			http.Error(w, "temporary", http.StatusInternalServerError)
 			return
@@ -112,6 +129,9 @@ func TestHTTPClientRetriesOnTransientAndSucceeds(t *testing.T) {
 	if calls.Load() != 2 {
 		t.Fatalf("calls = %d, want 2", calls.Load())
 	}
+	if len(payloads) != 2 || payloads[0] != "audio-data" || payloads[1] != "audio-data" {
+		t.Fatalf("retry payloads = %#v, want two exact audio payloads", payloads)
+	}
 	verifyJSONFile(t, outPath)
 }
 
@@ -247,8 +267,245 @@ func TestHTTPClientConstructorValidation(t *testing.T) {
 	if err == nil {
 		t.Fatal("expected bad retry_delay error")
 	}
+	for _, endpoint := range []string{"ftp://example.com/transcribe", "file:///tmp/transcribe", "//example.com/transcribe", "https:/missing-host"} {
+		if _, err := NewHTTPClientFromConfigValues(endpoint, "en", "30m", "2s", 1); err == nil {
+			t.Errorf("NewHTTPClientFromConfigValues(%q) error = nil, want endpoint validation error", endpoint)
+		}
+	}
+	for _, endpoint := range []string{"http://example.com/transcribe", "https://example.com/transcribe"} {
+		if _, err := NewHTTPClientFromConfigValues(endpoint, "en", "30m", "2s", 1); err != nil {
+			t.Errorf("NewHTTPClientFromConfigValues(%q) error = %v", endpoint, err)
+		}
+	}
 }
 
+func TestHTTPClientStreamsUploadBeforeSourceCompletes(t *testing.T) {
+	release := make(chan struct{})
+	source := newGatedReadCloser([]byte("audio-data"), release)
+	firstByteReceived := make(chan struct{})
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		part := firstMultipartFilePart(t, r)
+		buf := make([]byte, 1)
+		if _, err := part.Read(buf); err != nil {
+			t.Errorf("Read(file) error = %v", err)
+			return
+		}
+		close(firstByteReceived)
+		if _, err := io.Copy(io.Discard, part); err != nil {
+			t.Errorf("discard remaining file data: %v", err)
+			return
+		}
+		_, _ = w.Write([]byte(`{"ok":true}`))
+	}))
+	defer srv.Close()
+
+	client := newTestHTTPClient(t, srv.URL)
+	client.openAudio = func(string) (io.ReadCloser, error) { return source, nil }
+
+	done := make(chan error, 1)
+	go func() {
+		_, err := client.Transcribe(context.Background(), TranscribeRequest{AudioPath: "audio.flac", OutputRawTranscriptPath: filepath.Join(t.TempDir(), "raw.json")})
+		done <- err
+	}()
+
+	select {
+	case <-firstByteReceived:
+		close(release)
+	case <-time.After(time.Second):
+		t.Fatal("server did not receive streamed audio before source completed")
+	}
+	if err := <-done; err != nil {
+		t.Fatalf("Transcribe() error = %v", err)
+	}
+}
+
+func TestHTTPClientSourceReadFailureReachesCaller(t *testing.T) {
+	sourceErr := errors.New("source read failed")
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_, _ = io.Copy(io.Discard, r.Body)
+	}))
+	defer srv.Close()
+
+	client := newTestHTTPClient(t, srv.URL)
+	client.openAudio = func(string) (io.ReadCloser, error) {
+		return &failingReadCloser{first: []byte("partial"), err: sourceErr}, nil
+	}
+
+	_, err := client.Transcribe(context.Background(), TranscribeRequest{AudioPath: "audio.flac", OutputRawTranscriptPath: filepath.Join(t.TempDir(), "raw.json")})
+	if !errors.Is(err, sourceErr) {
+		t.Fatalf("Transcribe() error = %v, want source read failure", err)
+	}
+}
+
+func TestHTTPClientEarlyServerResponseReturns(t *testing.T) {
+	release := make(chan struct{})
+	source := newGatedReadCloser([]byte("audio-data"), release)
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		http.Error(w, "bad request", http.StatusBadRequest)
+	}))
+	defer srv.Close()
+
+	client := newTestHTTPClient(t, srv.URL)
+	client.openAudio = func(string) (io.ReadCloser, error) { return source, nil }
+
+	done := make(chan error, 1)
+	go func() {
+		_, err := client.Transcribe(context.Background(), TranscribeRequest{AudioPath: "audio.flac", OutputRawTranscriptPath: filepath.Join(t.TempDir(), "raw.json")})
+		done <- err
+	}()
+
+	select {
+	case err := <-done:
+		if err == nil {
+			t.Fatal("Transcribe() error = nil, want HTTP status error")
+		}
+	case <-time.After(time.Second):
+		t.Fatal("Transcribe() did not finish after server closed the request early")
+	}
+}
+
+func TestHTTPClientCancellationReleasesBlockedProducer(t *testing.T) {
+	release := make(chan struct{})
+	source := newGatedReadCloser([]byte("audio-data"), release)
+	firstByteReceived := make(chan struct{})
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		part := firstMultipartFilePart(t, r)
+		buf := make([]byte, 1)
+		if _, err := part.Read(buf); err != nil {
+			t.Errorf("Read(file) error = %v", err)
+			return
+		}
+		close(firstByteReceived)
+		select {
+		case <-r.Context().Done():
+		case <-source.closed:
+		}
+	}))
+	defer srv.Close()
+
+	client := newTestHTTPClient(t, srv.URL)
+	client.openAudio = func(string) (io.ReadCloser, error) { return source, nil }
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan error, 1)
+	go func() {
+		_, err := client.Transcribe(ctx, TranscribeRequest{AudioPath: "audio.flac", OutputRawTranscriptPath: filepath.Join(t.TempDir(), "raw.json")})
+		done <- err
+	}()
+
+	select {
+	case <-firstByteReceived:
+		cancel()
+	case <-time.After(time.Second):
+		cancel()
+		t.Fatal("server did not receive initial streamed audio")
+	}
+	select {
+	case err := <-done:
+		if !errors.Is(err, context.Canceled) {
+			t.Fatalf("Transcribe() error = %v, want context cancellation", err)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("Transcribe() did not finish after cancellation")
+	}
+	select {
+	case <-source.closed:
+	case <-time.After(time.Second):
+		t.Fatal("blocked audio source was not closed on cancellation")
+	}
+}
+
+func TestHTTPClientBoundsWhisperXResponse(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_, _ = io.Copy(io.Discard, r.Body)
+		_, _ = w.Write([]byte(`{"ok":true}`))
+	}))
+	defer srv.Close()
+
+	client, err := NewHTTPClient(HTTPClientConfig{TranscribeURL: srv.URL, Language: "en", Timeout: time.Second, MaxResponseBytes: 4})
+	if err != nil {
+		t.Fatalf("NewHTTPClient() error = %v", err)
+	}
+	audioPath := writeWhisperXTestFile(t, "audio.flac", "audio-data")
+	_, err = client.Transcribe(context.Background(), TranscribeRequest{AudioPath: audioPath, OutputRawTranscriptPath: filepath.Join(t.TempDir(), "raw.json")})
+	if err == nil || !strings.Contains(err.Error(), "whisperx response exceeds configured limit") {
+		t.Fatalf("Transcribe() error = %v, want bounded WhisperX response error", err)
+	}
+}
+
+func newTestHTTPClient(t *testing.T, endpoint string) *HTTPClient {
+	t.Helper()
+	client, err := NewHTTPClientFromConfigValues(endpoint, "en", "2s", "1ms", 0)
+	if err != nil {
+		t.Fatalf("NewHTTPClientFromConfigValues() error = %v", err)
+	}
+	return client
+}
+
+func firstMultipartFilePart(t *testing.T, r *http.Request) *multipart.Part {
+	t.Helper()
+	reader, err := r.MultipartReader()
+	if err != nil {
+		t.Fatalf("MultipartReader() error = %v", err)
+	}
+	part, err := reader.NextPart()
+	if err != nil {
+		t.Fatalf("NextPart() error = %v", err)
+	}
+	if part.FormName() != "file" {
+		t.Fatalf("first form field = %q, want file", part.FormName())
+	}
+	return part
+}
+
+type gatedReadCloser struct {
+	first   []byte
+	release <-chan struct{}
+	closed  chan struct{}
+	sent    bool
+	once    atomic.Bool
+}
+
+func newGatedReadCloser(first []byte, release <-chan struct{}) *gatedReadCloser {
+	return &gatedReadCloser{first: first, release: release, closed: make(chan struct{})}
+}
+
+func (r *gatedReadCloser) Read(p []byte) (int, error) {
+	if !r.sent {
+		r.sent = true
+		return copy(p, r.first), nil
+	}
+	select {
+	case <-r.release:
+		return 0, io.EOF
+	case <-r.closed:
+		return 0, errors.New("audio source closed")
+	}
+}
+
+func (r *gatedReadCloser) Close() error {
+	if r.once.CompareAndSwap(false, true) {
+		close(r.closed)
+	}
+	return nil
+}
+
+type failingReadCloser struct {
+	first []byte
+	err   error
+	sent  bool
+}
+
+func (r *failingReadCloser) Read(p []byte) (int, error) {
+	if !r.sent {
+		r.sent = true
+		return copy(p, r.first), nil
+	}
+	return 0, r.err
+}
+
+func (r *failingReadCloser) Close() error { return nil }
+
 func writeWhisperXTestFile(t *testing.T, name, contents string) string {
 	t.Helper()
 	path := filepath.Join(t.TempDir(), name)

internal/app/analyze_artifacts.go

@@ -5,6 +5,7 @@ import (
 	"sort"
 	"strings"
 
+	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
 	"gitea.maximumdirect.net/eric/narratio/internal/config"
 )
 
@@ -47,19 +48,55 @@ func (f *artifactSelectionFlag) Normalize() ([]string, error) {
 }
 
 func validateSelectedArtifacts(cfg *config.Config, selected []string) error {
-	if len(selected) == 0 {
-		return nil
-	}
+	_, err := resolveEffectiveArtifacts(cfg, selected)
+	return err
+}
+
+func resolveEffectiveArtifacts(cfg *config.Config, selected []string) (artifacts.EffectiveArtifactSet, error) {
 	if cfg == nil || cfg.Pipeline == nil || cfg.Pipeline.Scriptorium == nil {
-		return fmt.Errorf("--artifacts requires pipeline.scriptorium.artifacts to be configured")
+		if len(selected) == 0 {
+			return artifacts.ResolveEffectiveArtifactSet(nil, nil)
+		}
+		return artifacts.EffectiveArtifactSet{}, fmt.Errorf("--artifacts requires pipeline.scriptorium.artifacts to be configured")
 	}
-	configured := cfg.Pipeline.Scriptorium.Artifacts
-	if len(configured) == 0 {
-		return fmt.Errorf("--artifacts requires at least one configured artifact in pipeline.scriptorium.artifacts")
+	configured := artifacts.ConfiguredArtifactDefinitions(cfg.Pipeline.Scriptorium.Artifacts)
+	if len(selected) > 0 && len(configured) == 0 {
+		return artifacts.EffectiveArtifactSet{}, fmt.Errorf("--artifacts requires at least one configured artifact in pipeline.scriptorium.artifacts")
 	}
-	for _, name := range selected {
-		if _, ok := configured[name]; !ok {
-			return fmt.Errorf("--artifacts includes unknown artifact %q", name)
+	effective, err := artifacts.ResolveEffectiveArtifactSet(configured, selected)
+	if err != nil {
+		if strings.Contains(err.Error(), "is not configured") {
+			return artifacts.EffectiveArtifactSet{}, fmt.Errorf("--artifacts includes unknown artifact %q", selectedArtifactName(err))
+		}
+		return artifacts.EffectiveArtifactSet{}, err
+	}
+	if err := validateEffectiveArtifactConfiguration(cfg.Pipeline.Scriptorium.Artifacts, effective); err != nil {
+		return artifacts.EffectiveArtifactSet{}, err
+	}
+	return effective, nil
+}
+
+func selectedArtifactName(err error) string {
+	message := err.Error()
+	start := strings.Index(message, "\"")
+	if start < 0 {
+		return ""
+	}
+	end := strings.Index(message[start+1:], "\"")
+	if end < 0 {
+		return ""
+	}
+	return message[start+1 : start+1+end]
+}
+
+func validateEffectiveArtifactConfiguration(configured map[string]config.ScriptoriumArtifactConfig, effective artifacts.EffectiveArtifactSet) error {
+	for _, name := range effective.Keys() {
+		artifactCfg := configured[name]
+		if strings.TrimSpace(artifactCfg.PromptID) == "" {
+			return fmt.Errorf("pipeline.scriptorium.artifacts.%s.prompt_id is required when selected", name)
+		}
+		if strings.TrimSpace(artifactCfg.OutputPath) == "" {
+			return fmt.Errorf("pipeline.scriptorium.artifacts.%s.output_path is required when selected", name)
 		}
 	}
 	return nil

internal/app/analyze_artifacts_test.go

@@ -110,6 +110,20 @@ func TestValidateSelectedArtifacts(t *testing.T) {
 			},
 			selected: []string{"player_handout", "session_recap"},
 		},
+		{
+			name: "selected disabled artifact must be executable",
+			cfg: &config.Config{
+				Pipeline: &config.PipelineConfig{
+					Scriptorium: &config.ScriptoriumConfig{
+						Artifacts: map[string]config.ScriptoriumArtifactConfig{
+							"player_handout": {Enabled: false, OutputPath: "artifacts/player_handout.md"},
+						},
+					},
+				},
+			},
+			selected: []string{"player_handout"},
+			wantErr:  "pipeline.scriptorium.artifacts.player_handout.prompt_id is required when selected",
+		},
 	}
 
 	for _, tt := range tests {

internal/app/campaign_config_path.go

@@ -6,6 +6,7 @@ import (
 	"strings"
 
 	"gitea.maximumdirect.net/eric/narratio/internal/config"
+	"gitea.maximumdirect.net/eric/narratio/internal/pathsafe"
 )
 
 func resolveCampaignConfigPath(pipelineCfg *config.PipelineConfig, campaignIDFlag, campaignFileFlag string) (string, error) {
@@ -33,12 +34,8 @@ func resolveCampaignConfigPath(pipelineCfg *config.PipelineConfig, campaignIDFla
 }
 
 func validateCampaignIDToken(campaignID string) error {
-	if filepath.IsAbs(campaignID) ||
-		strings.Contains(campaignID, "/") ||
-		strings.Contains(campaignID, `\`) ||
-		campaignID == "." ||
-		campaignID == ".." {
-		return fmt.Errorf("campaign id %q must be a single path segment", campaignID)
+	if err := pathsafe.ValidateOpaqueSegment(campaignID); err != nil {
+		return fmt.Errorf("campaign id %q must be a single path segment and opaque identifier: %w", campaignID, err)
 	}
 	return nil
 }

internal/app/clean.go

@@ -11,6 +11,7 @@ import (
 
 	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
 	"gitea.maximumdirect.net/eric/narratio/internal/config"
+	"gitea.maximumdirect.net/eric/narratio/internal/fileops"
 )
 
 // Clean removes local workspace/spool state while preserving durable cache
@@ -39,10 +40,12 @@ func cleanSession(ctx context.Context, flags commonConfigFlags, dryRun, clearCac
 	if strings.TrimSpace(flags.sessionID) == "" {
 		return fmt.Errorf("clean: session_id is required unless --all is set")
 	}
-	cfg, err := loadCommandConfig(ctx, flags.pipelinePath, flags.campaignPath, flags.campaignFilePath, flags.sessionPath, flags.sessionOptions())
+	loaded, err := loadCommandConfig(ctx, flags.pipelinePath, flags.campaignPath, flags.campaignFilePath, flags.sessionPath, flags.sessionOptions())
 	if err != nil {
 		return fmt.Errorf("clean: %w", err)
 	}
+	defer func() { _ = loaded.Close() }()
+	cfg := loaded.Config
 	if cfg == nil || cfg.Pipeline == nil || cfg.Session == nil {
 		return fmt.Errorf("clean: resolved pipeline and session config are required")
 	}
@@ -135,7 +138,7 @@ func reportCleanScopedDir(out io.Writer, root, target, policy string, dryRun boo
 		fmt.Fprintf(out, "Missing: %s\n", dir.TargetAbs)
 		return nil
 	}
-	if err := os.RemoveAll(dir.TargetAbs); err != nil {
+	if err := fileops.RemoveAllUnderRoot(dir.RootAbs, dir.TargetAbs); err != nil {
 		return fmt.Errorf("cleanup policy %s: remove %q: %w", policy, dir.TargetAbs, err)
 	}
 	fmt.Fprintf(out, "Deleted: %s\n", dir.TargetAbs)
@@ -160,7 +163,7 @@ func reportCleanRootChildren(out io.Writer, root, policy string, dryRun bool) er
 			fmt.Fprintf(out, "Would delete: %s\n", entry)
 			continue
 		}
-		if err := os.RemoveAll(entry); err != nil {
+		if err := fileops.RemoveAllUnderRoot(rootAbs, entry); err != nil {
 			return fmt.Errorf("cleanup policy %s: remove %q: %w", policy, entry, err)
 		}
 		fmt.Fprintf(out, "Deleted: %s\n", entry)
@@ -265,7 +268,7 @@ func reportCleanScopedFile(out io.Writer, root, target, policy string, dryRun bo
 		fmt.Fprintf(out, "Missing cache file: %s\n", file.TargetAbs)
 		return false, nil
 	}
-	if err := os.Remove(file.TargetAbs); err != nil {
+	if err := fileops.RemoveAllUnderRoot(file.RootAbs, file.TargetAbs); err != nil {
 		return false, fmt.Errorf("cleanup policy %s: remove %q: %w", policy, file.TargetAbs, err)
 	}
 	fmt.Fprintf(out, "Deleted cache file: %s\n", file.TargetAbs)

internal/app/commands_test.go

@@ -189,7 +189,7 @@ func TestExecuteRunStagePolishLoadsCredentialFromSecretsDir(t *testing.T) {
 	configDir := t.TempDir()
 	sessionID := "2026-05-03"
 	secretsDir := filepath.Join(configDir, "secrets")
-	if err := os.MkdirAll(secretsDir, 0o755); err != nil {
+	if err := os.MkdirAll(secretsDir, secretDirectoryPrivateMode); err != nil {
 		t.Fatalf("MkdirAll(%q): %v", secretsDir, err)
 	}
 	if err := os.WriteFile(filepath.Join(secretsDir, "OPENROUTER_API_KEY"), []byte("from-secret-file\n"), 0o600); err != nil {
@@ -218,7 +218,7 @@ audita:
   binary: ` + auditaBinary + `
   llm_api_key_env: OPENROUTER_API_KEY
 notification:
-  timeout: 10s
+  mode: noop
 `
 	sessionYAML := `session_id: ` + sessionID + `
 campaign: sample-campaign
@@ -283,7 +283,7 @@ seriatim:
 audita:
   binary: audita
 notification:
-  timeout: 10s
+  mode: noop
 `
 	sessionYAML := `session_id: 2026-05-03
 campaign: sample-campaign
@@ -308,8 +308,8 @@ inputs:
 	if code == 0 {
 		t.Fatal("exit code = 0, want non-zero")
 	}
-	if !strings.Contains(stderr.String(), "read secrets env_dir") {
-		t.Fatalf("stderr = %q, want secrets read-dir error context", stderr.String())
+	if !strings.Contains(stderr.String(), "validate secrets env_dir") {
+		t.Fatalf("stderr = %q, want secrets validation error context", stderr.String())
 	}
 }
 
@@ -476,9 +476,6 @@ func writeValidConfigFiles(t *testing.T, workspaceRoot string, transcribeURL ...
 	seriatimBinary := writeSeriatimAppTestWrapper(t)
 	scriptoriumBinary := writeScriptoriumAppTestWrapper(t)
 	auditaBinary := writeAuditaAppTestWrapper(t)
-	t.Setenv("GO_WANT_APP_SERIATIM_HELPER", "1")
-	t.Setenv("GO_WANT_APP_SCRIPTORIUM_HELPER", "1")
-	t.Setenv("GO_WANT_APP_AUDITA_HELPER", "1")
 	t.Setenv("AUDITA_LLM_API_KEY", "test-audita-key")
 	t.Setenv("PATH", filepath.Dir(scriptoriumBinary)+string(os.PathListSeparator)+os.Getenv("PATH"))
 
@@ -513,7 +510,7 @@ seriatim:
 audita:
   binary: ` + auditaBinary + `
 notification:
-  timeout: 10s
+  mode: noop
 `
 
 	sessionYAML := `session_id: 2026-05-03
@@ -623,7 +620,7 @@ func writeScriptoriumAppTestWrapper(t *testing.T) string {
 }
 
 func TestScriptoriumAppHelper(t *testing.T) {
-	if os.Getenv("GO_WANT_APP_SCRIPTORIUM_HELPER") != "1" {
+	if !appHelperInvocation() {
 		return
 	}
 
@@ -663,7 +660,7 @@ func TestScriptoriumAppHelper(t *testing.T) {
 }
 
 func TestSeriatimAppHelper(t *testing.T) {
-	if os.Getenv("GO_WANT_APP_SERIATIM_HELPER") != "1" {
+	if !appHelperInvocation() {
 		return
 	}
 
@@ -725,7 +722,7 @@ func writeAuditaAppTestWrapper(t *testing.T) string {
 }
 
 func TestAuditaAppHelper(t *testing.T) {
-	if os.Getenv("GO_WANT_APP_AUDITA_HELPER") != "1" {
+	if !appHelperInvocation() {
 		return
 	}
 
@@ -779,6 +776,15 @@ func TestAuditaAppHelper(t *testing.T) {
 	os.Exit(0)
 }
 
+func appHelperInvocation() bool {
+	for _, arg := range os.Args {
+		if arg == "--" {
+			return true
+		}
+	}
+	return false
+}
+
 func appSeriatimFlagValue(args []string, name string) string {
 	for i := 0; i < len(args)-1; i++ {
 		if args[i] == name {

internal/app/config_loader.go

@@ -2,13 +2,16 @@ package app
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"os"
+	"path/filepath"
 	"strings"
 
 	"gitea.maximumdirect.net/eric/narratio/internal/adapters/storage"
 	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
 	"gitea.maximumdirect.net/eric/narratio/internal/config"
+	"gitea.maximumdirect.net/eric/narratio/internal/fileops"
 )
 
 type pipelineCampaignConfig struct {
@@ -18,14 +21,48 @@ type pipelineCampaignConfig struct {
 	Campaign     *config.CampaignConfig
 }
 
-func loadCommandConfig(ctx context.Context, pipelineFlag, campaignFlag, campaignFileFlag, sessionFlag string, sessionOpts config.SessionLoadOptions) (*config.Config, error) {
+var downloadObjectToTempFn = storage.DownloadObjectToTemp
+
+type commandConfig struct {
+	Config  *config.Config
+	cleanup func() error
+}
+
+func (c *commandConfig) Close() error {
+	if c == nil || c.cleanup == nil {
+		return nil
+	}
+	cleanup := c.cleanup
+	c.cleanup = nil
+	return cleanup()
+}
+
+func retainedCommandConfig(cfg *config.Config) *commandConfig {
+	return &commandConfig{Config: cfg}
+}
+
+func loadCommandConfig(ctx context.Context, pipelineFlag, campaignFlag, campaignFileFlag, sessionFlag string, sessionOpts config.SessionLoadOptions) (loaded *commandConfig, err error) {
+	var cleanup func() error
+	defer func() {
+		if err == nil || cleanup == nil {
+			return
+		}
+		if cleanupErr := cleanup(); cleanupErr != nil {
+			err = errors.Join(err, cleanupErr)
+		}
+	}()
+
 	base, err := loadPipelineCampaignConfig(pipelineFlag, campaignFlag, campaignFileFlag)
 	if err != nil {
 		return nil, err
 	}
 
 	if explicitSession := strings.TrimSpace(sessionFlag); explicitSession != "" {
-		return config.LoadWithSessionOptions(base.PipelinePath, base.CampaignPath, explicitSession, sessionOpts)
+		cfg, err := config.LoadWithSessionOptions(base.PipelinePath, base.CampaignPath, explicitSession, sessionOpts)
+		if err != nil {
+			return nil, err
+		}
+		return retainedCommandConfig(cfg), nil
 	}
 
 	discoveredSession, err := discoverSessionConfigPathWithCandidates(config.DefaultSessionConfigSearchPaths)
@@ -33,7 +70,11 @@ func loadCommandConfig(ctx context.Context, pipelineFlag, campaignFlag, campaign
 		return nil, err
 	}
 	if discoveredSession.Path != "" {
-		return config.LoadWithSessionOptions(base.PipelinePath, base.CampaignPath, discoveredSession.Path, sessionOpts)
+		cfg, err := config.LoadWithSessionOptions(base.PipelinePath, base.CampaignPath, discoveredSession.Path, sessionOpts)
+		if err != nil {
+			return nil, err
+		}
+		return retainedCommandConfig(cfg), nil
 	}
 
 	sessionID := strings.TrimSpace(sessionOpts.SessionID)
@@ -41,7 +82,11 @@ func loadCommandConfig(ctx context.Context, pipelineFlag, campaignFlag, campaign
 		return nil, missingSessionConfigError(discoveredSession.Searched, "remote session loading requires a session_id")
 	}
 
-	sessionPrefix := artifacts.S3SessionPrefix(base.Pipeline.Storage.S3.RootPrefix, config.CampaignID(base.Campaign), sessionID)
+	rootPrefix := ""
+	if base.Pipeline.Storage.S3 != nil {
+		rootPrefix = base.Pipeline.Storage.S3.RootPrefix
+	}
+	sessionPrefix := artifacts.S3SessionPrefix(rootPrefix, config.CampaignID(base.Campaign), sessionID)
 	remoteKey := artifacts.S3SessionConfigKey(sessionPrefix)
 	partialCfg := &config.Config{
 		Pipeline:     base.Pipeline,
@@ -58,20 +103,26 @@ func loadCommandConfig(ctx context.Context, pipelineFlag, campaignFlag, campaign
 	if err != nil {
 		return nil, missingSessionConfigError(discoveredSession.Searched, err.Error())
 	}
-	sessionTempPath, err := storage.DownloadObjectToTemp(ctx, store, remoteKey, "narratio-session-*.yml")
+	sessionTempPath, err := downloadObjectToTempFn(ctx, store, remoteKey, "narratio-session-*.yml")
 	if err != nil {
 		return nil, missingSessionConfigError(discoveredSession.Searched, fmt.Sprintf("remote session %q download failed: %v", remoteKey, err))
 	}
+	cleanup = func() error {
+		if err := fileops.RemoveAllUnderRoot(filepath.Dir(sessionTempPath), sessionTempPath); err != nil {
+			return fmt.Errorf("remove downloaded remote session config: %w", err)
+		}
+		return nil
+	}
 	sessionBytes, err := os.ReadFile(sessionTempPath)
 	if err != nil {
-		return nil, fmt.Errorf("read downloaded remote session %q: %w", sessionTempPath, err)
+		return nil, fmt.Errorf("read downloaded remote session config: %w", err)
 	}
 	sessionCfg, err := config.LoadSessionBytesWithOptions("s3://"+s3BucketName(base.Pipeline)+"/"+remoteKey, sessionBytes, sessionOpts)
 	if err != nil {
 		return nil, err
 	}
 
-	return config.Resolve(
+	cfg, err := config.Resolve(
 		base.PipelinePath,
 		base.Pipeline,
 		base.CampaignPath,
@@ -85,9 +136,14 @@ func loadCommandConfig(ctx context.Context, pipelineFlag, campaignFlag, campaign
 			S3Key:     remoteKey,
 			S3Size:    sessionInfo.Size,
 			S3ETag:    sessionInfo.ETag,
-			SpoolPath: sessionTempPath,
 		},
 	)
+	if err != nil {
+		return nil, err
+	}
+	loaded = &commandConfig{Config: cfg, cleanup: cleanup}
+	cleanup = nil
+	return loaded, nil
 }
 
 func loadPipelineCampaignConfig(pipelineFlag, campaignFlag, campaignFileFlag string) (*pipelineCampaignConfig, error) {

internal/app/extract_lifecycle_test.go

@@ -252,6 +252,32 @@ func TestExtractLifecycleSkipsCurrentResumableResult(t *testing.T) {
 	}
 }
 
+func TestExtractLifecycleRerunsAfterDirectTranscriptChange(t *testing.T) {
+	cfg, env, runner := extractionLifecycleFixture(t, true)
+	analyzeRuns := 0
+	plan := extractionLifecyclePlan(t, &analyzeRuns)
+	if _, err := executeStages(context.Background(), cfg, plan, RunOptions{Env: env}); err != nil {
+		t.Fatalf("first executeStages() error = %v", err)
+	}
+
+	persisted := loadLifecycleManifest(t, cfg)
+	trimmed := persisted.Stages["trim"].Outputs[0].LocalPath
+	if err := os.WriteFile(trimmed, []byte(`{"segments":[{"id":"changed"}]}`), 0o644); err != nil {
+		t.Fatalf("WriteFile(trimmed transcript) error = %v", err)
+	}
+	if err := (&manifest.LocalStore{}).Save(context.Background(), manifestPathFor(cfg), persisted); err != nil {
+		t.Fatalf("Save(mutated) error = %v", err)
+	}
+
+	rerun, err := executeStages(context.Background(), cfg, plan, RunOptions{Env: env})
+	if err != nil {
+		t.Fatalf("rerun executeStages() error = %v", err)
+	}
+	if len(rerun.Executed) != 2 || len(rerun.Skipped) != 0 || len(runner.requests) != 2 || analyzeRuns != 2 {
+		t.Fatalf("rerun summary = %#v requests=%d analyze=%d", rerun, len(runner.requests), analyzeRuns)
+	}
+}
+
 func TestExtractLifecycleResumesAndRerunsObsoleteResults(t *testing.T) {
 	for _, test := range []struct {
 		name   string

internal/app/object_store_test.go

@@ -142,24 +142,3 @@ func commandObjectStoreTestConfig(secretsDir string) *config.Config {
 	}
 	return cfg
 }
-
-func restoreEnvAfterTest(t *testing.T, names ...string) {
-	t.Helper()
-	originals := make(map[string]string, len(names))
-	present := make(map[string]bool, len(names))
-	for _, name := range names {
-		value, ok := os.LookupEnv(name)
-		originals[name] = value
-		present[name] = ok
-		_ = os.Unsetenv(name)
-	}
-	t.Cleanup(func() {
-		for _, name := range names {
-			if present[name] {
-				_ = os.Setenv(name, originals[name])
-			} else {
-				_ = os.Unsetenv(name)
-			}
-		}
-	})
-}

internal/app/operator_artifact_rendering.go

@@ -14,21 +14,17 @@ import (
 )
 
 func buildHelperArtifactCatalog(cfg *config.Config, m *manifest.Manifest) (*artifacts.ArtifactCatalog, error) {
-	catalog := artifacts.NewArtifactCatalog()
-	if err := catalog.RegisterBuiltIns(); err != nil {
-		return nil, err
-	}
-	configured := map[string]artifacts.ConfiguredArtifactDefinition{}
+	configured := artifacts.ConfiguredArtifactDefinitions(nil)
 	if cfg.Pipeline.Scriptorium != nil {
-		for key, item := range cfg.Pipeline.Scriptorium.Artifacts {
-			configured[key] = artifacts.ConfiguredArtifactDefinition{Enabled: item.Enabled, OutputPath: item.OutputPath}
-		}
-	}
-	if err := catalog.RegisterConfiguredArtifacts(configured, nil); err != nil {
-		return nil, err
+		configured = artifacts.ConfiguredArtifactDefinitions(cfg.Pipeline.Scriptorium.Artifacts)
 	}
 	extractionDefinitions := artifacts.ExtractionDefinitionsFromConfig(cfg.Pipeline.Notarius)
-	if err := catalog.RegisterExtractionArtifacts(extractionDefinitions); err != nil {
+	effective, err := artifacts.ResolveEffectiveArtifactSet(configured, nil)
+	if err != nil {
+		return nil, err
+	}
+	catalog, err := artifacts.BootstrapRuntimeCatalog(configured, effective, extractionDefinitions)
+	if err != nil {
 		return nil, err
 	}
 	paths := artifacts.NewLocalStore(cfg.Pipeline.Workspace.Root).SessionPathsFor(cfg.Session.Campaign, cfg.Session.SessionID)
@@ -58,8 +54,10 @@ func writeArtifactList(out io.Writer, cfg *config.Config, catalog *artifacts.Art
 		writeExtractionArtifactLine(out, entry.SourceID, state, entry.Provenance, lockSet)
 	}
 	fmt.Fprintln(out, "Previous-session:")
-	for _, req := range artifacts.CollectPreviousArtifactRequirements(configuredScriptoriumArtifacts(cfg)) {
-		fmt.Fprintf(out, "- %s required=%t\n", artifactpolicy.PreviousSessionSourceID(req.Name), req.Required)
+	if effective, err := resolveEffectiveArtifacts(cfg, nil); err == nil {
+		for _, req := range artifacts.CollectPreviousArtifactRequirements(configuredScriptoriumArtifacts(cfg), effective) {
+			fmt.Fprintf(out, "- %s required=%t\n", artifactpolicy.PreviousSessionSourceID(req.Name), req.Required)
+		}
 	}
 	fmt.Fprintln(out, "Published:")
 	for _, rule := range cfg.Pipeline.Publish.Outputs {
@@ -129,6 +127,47 @@ func remotePublishedOutputAvailability(ctx context.Context, cfg *config.Config,
 	return out
 }
 
+func remotePublishedOutputAvailabilityForCurrent(
+	ctx context.Context,
+	cfg *config.Config,
+	store storage.ObjectStore,
+	catalog *artifacts.ArtifactCatalog,
+	current *RemoteCurrentState,
+) map[string]string {
+	if current == nil || current.Commit == nil {
+		return remotePublishedOutputAvailability(ctx, cfg, store, catalog)
+	}
+	out := map[string]string{}
+	runPrefix := artifacts.S3RunPrefix(current.SessionPrefix, current.RunID)
+	for _, rule := range cfg.Pipeline.Publish.Outputs {
+		source := strings.TrimSpace(rule.Source)
+		dest, _, err := helperPublishedOutputDest(rule, catalog)
+		if err != nil {
+			out[publishedOutputRemoteStateKey(source, "")] = "remote=error"
+			continue
+		}
+		key := artifacts.S3RunRelativeDestinationKey(runPrefix, dest)
+		if committedPublishedOutput(current.Commit, key) {
+			out[publishedOutputRemoteStateKey(source, dest)] = "remote=published"
+		} else {
+			out[publishedOutputRemoteStateKey(source, dest)] = "remote=missing"
+		}
+	}
+	return out
+}
+
+func committedPublishedOutput(commit *artifacts.RemoteCommitManifest, key string) bool {
+	if commit == nil {
+		return false
+	}
+	for _, artifact := range commit.Artifacts {
+		if artifact.Type == artifacts.RemoteArtifactTypePublishedOutput && artifact.DestinationKey == key {
+			return true
+		}
+	}
+	return false
+}
+
 func helperPublishedOutputDest(rule config.PublishOutputRule, catalog *artifacts.ArtifactCatalog) (string, bool, error) {
 	source := strings.TrimSpace(rule.Source)
 	normalized, err := artifactpolicy.ResolvePublishedDestinationWithExtractions(

internal/app/operator_artifacts_list.go

@@ -22,10 +22,11 @@ func ArtifactsList(ctx context.Context, args []string, out io.Writer) error {
 	if strings.TrimSpace(flags.sessionID) == "" {
 		return fmt.Errorf("artifacts list: session_id is required")
 	}
-	cfg, store, locks, m, err := loadHelperContext(ctx, flags, remote)
+	cfg, store, locks, m, cleanup, err := loadHelperContext(ctx, flags, remote)
 	if err != nil {
 		return fmt.Errorf("artifacts list: %w", err)
 	}
+	defer cleanup()
 	catalog, err := buildHelperArtifactCatalog(cfg, m)
 	if err != nil {
 		return fmt.Errorf("artifacts list: %w", err)

internal/app/operator_helpers.go

@@ -90,33 +90,41 @@ func Artifacts(ctx context.Context, args []string, out io.Writer) error {
 	}
 }
 
-func loadHelperContext(ctx context.Context, flags commonConfigFlags, needStore bool) (*config.Config, storage.ObjectStore, *effectiveLocks, *manifest.Manifest, error) {
-	cfg, err := loadCommandConfig(ctx, flags.pipelinePath, flags.campaignPath, flags.campaignFilePath, flags.sessionPath, flags.sessionOptions())
+func loadHelperContext(ctx context.Context, flags commonConfigFlags, needStore bool) (*config.Config, storage.ObjectStore, *effectiveLocks, *manifest.Manifest, func(), error) {
+	loaded, err := loadCommandConfig(ctx, flags.pipelinePath, flags.campaignPath, flags.campaignFilePath, flags.sessionPath, flags.sessionOptions())
 	if err != nil {
-		return nil, nil, nil, nil, err
+		return nil, nil, nil, nil, nil, err
 	}
+	release := true
+	defer func() {
+		if release {
+			_ = loaded.Close()
+		}
+	}()
+	cfg := loaded.Config
 	if err := config.Validate(cfg); err != nil {
-		return nil, nil, nil, nil, err
+		return nil, nil, nil, nil, nil, err
 	}
 	var store storage.ObjectStore
 	if needStore {
 		store, err = newCommandObjectStore(ctx, cfg, nil)
 		if err != nil {
-			return nil, nil, nil, nil, err
+			return nil, nil, nil, nil, nil, err
 		}
 	} else {
 		store, _ = objectStoreIfConfigured(ctx, cfg)
 	}
 	locks, err := loadEffectiveLocks(ctx, cfg, store)
 	if err != nil {
-		return nil, nil, nil, nil, err
+		return nil, nil, nil, nil, nil, err
 	}
 	paths := artifacts.NewLocalStore(cfg.Pipeline.Workspace.Root).SessionPathsFor(cfg.Session.Campaign, cfg.Session.SessionID)
 	m, err := loadLocalManifest(ctx, paths.ManifestPath)
 	if err != nil {
-		return nil, nil, nil, nil, err
+		return nil, nil, nil, nil, nil, err
 	}
-	return cfg, store, locks, m, nil
+	release = false
+	return cfg, store, locks, m, func() { _ = loaded.Close() }, nil
 }
 
 func objectStoreIfConfigured(ctx context.Context, cfg *config.Config) (storage.ObjectStore, error) {

internal/app/operator_helpers_test.go

@@ -3,10 +3,12 @@ package app
 import (
 	"bytes"
 	"context"
+	"errors"
 	"fmt"
 	"os"
 	"path/filepath"
 	"strings"
+	"sync"
 	"testing"
 	"time"
 
@@ -189,8 +191,8 @@ func TestExecuteSessionInitRemoteLoadsSecretsBeforeObjectStoreInit(t *testing.T)
 	secretKeyEnv := "NARRATIO_TEST_SESSION_INIT_OBJECT_SECRET"
 	restoreEnvAfterTest(t, accessKeyEnv, secretKeyEnv)
 	secretsDir := t.TempDir()
-	mustWriteTestFile(t, filepath.Join(secretsDir, accessKeyEnv), "test-key-id\n")
-	mustWriteTestFile(t, filepath.Join(secretsDir, secretKeyEnv), "test-secret\n")
+	mustWriteSecretFile(t, filepath.Join(secretsDir, accessKeyEnv), "test-key-id\n")
+	mustWriteSecretFile(t, filepath.Join(secretsDir, secretKeyEnv), "test-secret\n")
 	addSecretsToPipelineConfig(t, pipelinePath, secretsDir, accessKeyEnv, secretKeyEnv)
 
 	fake := &storage.FakeBackend{}
@@ -417,8 +419,8 @@ func TestExecuteSessionValidateLoadsSecretsBeforeObjectStoreInit(t *testing.T) {
 	secretKeyEnv := "NARRATIO_TEST_VALIDATE_OBJECT_SECRET"
 	restoreEnvAfterTest(t, accessKeyEnv, secretKeyEnv)
 	secretsDir := t.TempDir()
-	mustWriteTestFile(t, filepath.Join(secretsDir, accessKeyEnv), "test-key-id\n")
-	mustWriteTestFile(t, filepath.Join(secretsDir, secretKeyEnv), "test-secret\n")
+	mustWriteSecretFile(t, filepath.Join(secretsDir, accessKeyEnv), "test-key-id\n")
+	mustWriteSecretFile(t, filepath.Join(secretsDir, secretKeyEnv), "test-secret\n")
 	addSecretsToPipelineConfig(t, pipelinePath, secretsDir, accessKeyEnv, secretKeyEnv)
 	if err := os.WriteFile(sessionPath, []byte(`session_id: 2026-05-03
 inputs:
@@ -522,6 +524,123 @@ func TestExecuteLocksAddListAndRemoveUseRemoteLockStore(t *testing.T) {
 	}
 }
 
+func TestMutateRemoteLockStoreRetainsConcurrentUpdates(t *testing.T) {
+	cfg := &config.Config{
+		Pipeline: &config.PipelineConfig{Storage: config.StorageConfig{S3: &config.StorageS3Config{Bucket: "bucket", RootPrefix: "root"}}},
+		Session:  &config.SessionConfig{Campaign: "campaign", SessionID: "session"},
+	}
+	fake := &storage.FakeBackend{}
+	arrived := make(chan struct{}, 2)
+	release := make(chan struct{})
+	var hookMu sync.Mutex
+	hookCalls := 0
+	fake.UploadHook = func(storage.FakeUploadCall) error {
+		hookMu.Lock()
+		hookCalls++
+		call := hookCalls
+		hookMu.Unlock()
+		if call <= 2 {
+			arrived <- struct{}{}
+			<-release
+		}
+		return nil
+	}
+
+	mutate := func(source string) error {
+		return mutateRemoteLockStore(context.Background(), cfg, fake, func(lockStore *config.PublishLockStore) error {
+			set := lockSourceSet(lockStore.Locks)
+			set[source] = config.PublishLockRule{Source: source}
+			lockStore.Locks = lockMapValues(set)
+			return nil
+		})
+	}
+	errs := make(chan error, 2)
+	go func() { errs <- mutate("narratio.transcript.final") }()
+	go func() { errs <- mutate("narratio.transcript.final_trimmed") }()
+	<-arrived
+	<-arrived
+	close(release)
+	if err := <-errs; err != nil {
+		t.Fatalf("first concurrent mutation error = %v", err)
+	}
+	if err := <-errs; err != nil {
+		t.Fatalf("second concurrent mutation error = %v", err)
+	}
+
+	locks, _, _, err := loadRemoteLockStore(context.Background(), cfg, fake)
+	if err != nil {
+		t.Fatalf("loadRemoteLockStore() error = %v", err)
+	}
+	if len(locks.Locks) != 2 || locks.Locks[0].Source != "narratio.transcript.final" || locks.Locks[1].Source != "narratio.transcript.final_trimmed" {
+		t.Fatalf("remote locks = %#v, want both concurrent updates", locks.Locks)
+	}
+}
+
+func TestLoadRemoteLockStoreAcceptsExactLimitAndRejectsLimitPlusOne(t *testing.T) {
+	cfg := &config.Config{
+		Pipeline: &config.PipelineConfig{Storage: config.StorageConfig{S3: &config.StorageS3Config{Bucket: "bucket", RootPrefix: "root"}}},
+		Session:  &config.SessionConfig{Campaign: "campaign", SessionID: "session"},
+	}
+	key, err := remoteLocksKey(cfg)
+	if err != nil {
+		t.Fatalf("remoteLocksKey() error = %v", err)
+	}
+	encoded, err := config.MarshalPublishLockStore(&config.PublishLockStore{})
+	if err != nil {
+		t.Fatalf("MarshalPublishLockStore() error = %v", err)
+	}
+	exact := append(append([]byte(nil), encoded...), bytes.Repeat([]byte(" "), int(MaxRemoteLockStoreBytes)-len(encoded))...)
+	store := &storage.FakeBackend{}
+	store.SeedObject(storage.FakeObject{Key: key, Data: exact, ETag: "lock-generation"})
+
+	locks, gotKey, generation, err := loadRemoteLockStore(context.Background(), cfg, store)
+	if err != nil {
+		t.Fatalf("loadRemoteLockStore() exact-limit error = %v", err)
+	}
+	if locks == nil || gotKey != key || generation != "lock-generation" {
+		t.Fatalf("loadRemoteLockStore() = (%#v, %q, %q), want decoded locks and opened generation", locks, gotKey, generation)
+	}
+	if len(store.Downloads) != 0 || len(store.Reads) != 1 || store.Reads[0].Key != key {
+		t.Fatalf("lock transfers reads=%#v downloads=%#v, want one direct read", store.Reads, store.Downloads)
+	}
+
+	store.SeedObject(storage.FakeObject{Key: key, Data: append(exact, ' '), ETag: "new-generation"})
+	_, _, _, err = loadRemoteLockStore(context.Background(), cfg, store)
+	if err == nil || !strings.Contains(err.Error(), "remote lock control object") || !strings.Contains(err.Error(), key) || !strings.Contains(err.Error(), fmt.Sprint(MaxRemoteLockStoreBytes)) {
+		t.Fatalf("loadRemoteLockStore() limit-plus-one error = %v, want category, key, and limit", err)
+	}
+}
+
+func TestLoadRemoteLockStoreRejectsMalformedYAML(t *testing.T) {
+	cfg := &config.Config{
+		Pipeline: &config.PipelineConfig{Storage: config.StorageConfig{S3: &config.StorageS3Config{Bucket: "bucket", RootPrefix: "root"}}},
+		Session:  &config.SessionConfig{Campaign: "campaign", SessionID: "session"},
+	}
+	key, err := remoteLocksKey(cfg)
+	if err != nil {
+		t.Fatalf("remoteLocksKey() error = %v", err)
+	}
+	store := &storage.FakeBackend{}
+	store.SeedObject(storage.FakeObject{Key: key, Data: []byte("locks: [\n"), ETag: "lock-generation"})
+
+	if _, _, _, err := loadRemoteLockStore(context.Background(), cfg, store); err == nil {
+		t.Fatal("loadRemoteLockStore() error = nil, want malformed YAML failure")
+	}
+}
+
+func TestMutateRemoteLockStoreHonorsCancellation(t *testing.T) {
+	cfg := &config.Config{
+		Pipeline: &config.PipelineConfig{Storage: config.StorageConfig{S3: &config.StorageS3Config{Bucket: "bucket", RootPrefix: "root"}}},
+		Session:  &config.SessionConfig{Campaign: "campaign", SessionID: "session"},
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	err := mutateRemoteLockStore(ctx, cfg, &storage.FakeBackend{}, func(*config.PublishLockStore) error { return nil })
+	if !errors.Is(err, context.Canceled) {
+		t.Fatalf("mutateRemoteLockStore() error = %v, want context cancellation", err)
+	}
+}
+
 func TestExecuteLocksAddDuplicateRequiresForce(t *testing.T) {
 	workspaceRoot := t.TempDir()
 	pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot)
@@ -979,9 +1098,6 @@ func TestExecuteStatusReportsRemoteArtifactCatalogErrorsWithoutFailing(t *testin
 	if !strings.Contains(out, "Remote outputs:") || !strings.Contains(out, "narratio.transcript.final_trimmed remote=error") {
 		t.Fatalf("stdout = %q, want remote output error state", out)
 	}
-	if !strings.Contains(out, "Publish locks: error:") {
-		t.Fatalf("stdout = %q, want publish locks error", out)
-	}
 }
 
 func TestExecuteStatusReportsMissingRemoteCurrentStateWithoutFailing(t *testing.T) {
@@ -1032,6 +1148,36 @@ func TestExecuteStatusReportsPreviousStateReadinessWithoutFailing(t *testing.T)
 	}
 }
 
+func TestExecuteStatusDetectsMissingRequiredPreviousArtifact(t *testing.T) {
+	workspaceRoot := t.TempDir()
+	pipelinePath, campaignPath, sessionPath := writeValidConfigFilesWithScriptoriumArtifacts(t, workspaceRoot)
+	replaceInFileOrFatal(t, pipelinePath, "source: narratio.artifact.session_recap", "source: narratio.previous_session.artifact.session_recap")
+	replaceInFileOrFatal(t, sessionPath, "session_id: 2026-05-03\n", "session_id: 2026-05-03\nprevious_session_id: 2026-04-26\n")
+	cfg, err := config.LoadWithSessionOptions(pipelinePath, campaignPath, sessionPath, config.SessionLoadOptions{})
+	if err != nil {
+		t.Fatalf("LoadWithSessionOptions() error = %v", err)
+	}
+	fake := &storage.FakeBackend{}
+	seedRestorePreviousCurrentManifestOnly(t, fake, cfg)
+	var storeInitCalls int
+	restoreAppConfigTestGlobals(t, fake, &storeInitCalls, []string{sessionPath})
+
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	code := Execute([]string{
+		"session", "status", "2026-05-03",
+		"--config", pipelinePath,
+		"--campaign-file", campaignPath,
+		"--session", sessionPath,
+	}, &stdout, &stderr)
+	if code != 0 {
+		t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
+	}
+	if !strings.Contains(stdout.String(), `Previous-session artifacts: unavailable: remote required previous-session artifact "session_recap" object missing`) {
+		t.Fatalf("stdout = %q, want missing required previous artifact", stdout.String())
+	}
+}
+
 func TestExecuteSessionValidateReportsPreviousStateFindingAndReturnsFindingError(t *testing.T) {
 	workspaceRoot := t.TempDir()
 	pipelinePath, campaignPath, sessionPath := writeValidConfigFilesWithScriptoriumArtifacts(t, workspaceRoot)
@@ -1140,8 +1286,10 @@ func writeOperatorExtractionManifest(t *testing.T, workspaceRoot string) string
 	bundleRoot := filepath.Join(paths.ArtifactsDir, "notarius", "extract-run-1")
 	lanePath := filepath.Join(bundleRoot, "lanes", "encounters.json")
 	indexPath := filepath.Join(bundleRoot, "index.json")
+	trimmedPath := filepath.Join(paths.Root, filepath.FromSlash(artifacts.TranscriptPathFinalTrimmed))
 	mustWriteTestFile(t, lanePath, `{"secret":"DO_NOT_PRINT"}`)
 	mustWriteTestFile(t, indexPath, `{"lanes":[]}`)
+	mustWriteTestFile(t, trimmedPath, `{"segments":[]}`)
 	laneChecksum, err := artifacts.SHA256File(lanePath)
 	if err != nil {
 		t.Fatal(err)
@@ -1152,11 +1300,22 @@ func writeOperatorExtractionManifest(t *testing.T, workspaceRoot string) string
 	}
 	m := manifest.New("2026-05-03", time.Now().UTC())
 	m.Campaign = "sample-campaign"
+	m.Stages["trim"] = &manifest.StageRecord{
+		Name: "trim", Status: manifest.StatusSucceeded,
+		Outputs: []manifest.ArtifactRecord{{
+			Kind: artifactmodel.TranscriptOutputKindFinalTrimmed, LocalPath: trimmedPath, ProducerRunID: "trim-run-1",
+		}},
+	}
+	input, err := artifacts.ResolveExtractionInputIdentity(paths, m)
+	if err != nil {
+		t.Fatal(err)
+	}
 	m.Stages["extract"] = &manifest.StageRecord{
 		Name: "extract", Status: manifest.StatusSucceeded,
 		Metadata: map[string]any{
 			"narratio_run_id": "extract-run-1", "bundle_root": bundleRoot,
-			"receipt": map[string]any{"run_id": "notarius-run-1", "pipeline_id": "campaign.extract"},
+			"receipt":      map[string]any{"run_id": "notarius-run-1", "pipeline_id": "campaign.extract"},
+			"direct_input": input.Metadata(),
 		},
 		Outputs: []manifest.ArtifactRecord{
 			{

internal/app/operator_inspection.go

@@ -2,6 +2,7 @@ package app
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"os"
 	"path"
@@ -12,6 +13,7 @@ import (
 	"gitea.maximumdirect.net/eric/narratio/internal/adapters/storage"
 	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
 	"gitea.maximumdirect.net/eric/narratio/internal/config"
+	"gitea.maximumdirect.net/eric/narratio/internal/previouscache"
 )
 
 type stableInputCheck struct {
@@ -34,9 +36,9 @@ type remoteAudioCheck struct {
 }
 
 type previousArtifactReadiness struct {
-	Requirements []artifacts.PreviousArtifactRequirement
-	MissingID    bool
-	Err          error
+	Requirements   []artifacts.PreviousArtifactRequirement
+	SkippedMissing []string
+	Err            error
 }
 
 type remoteCurrentStateCheck struct {
@@ -152,23 +154,27 @@ func inspectPreviousArtifactReadiness(
 	if len(requirements) == 0 {
 		return out
 	}
-	if strings.TrimSpace(cfg.Session.PreviousSessionID) == "" {
-		out.MissingID = true
+	if cfg == nil || cfg.Pipeline == nil || cfg.Session == nil {
+		out.Err = fmt.Errorf("resolved config with pipeline/session is required")
 		return out
 	}
-	if store == nil {
-		out.Err = fmt.Errorf("previous-session artifacts cannot be checked because storage is unavailable")
+	paths := artifacts.NewLocalStore(cfg.Pipeline.Workspace.Root).SessionPathsFor(cfg.Session.Campaign, cfg.Session.SessionID)
+	plan, err := previouscache.Resolve(ctx, cfg, paths, requirements, store)
+	if err != nil {
+		var pointerMissing *artifacts.CurrentRunPointerMissingError
+		var manifestMissing *artifacts.CurrentManifestMissingError
+		if errors.As(err, &pointerMissing) {
+			out.Err = fmt.Errorf("remote %w", pointerMissing)
+			return out
+		}
+		if errors.As(err, &manifestMissing) {
+			out.Err = fmt.Errorf("remote %w", manifestMissing)
+			return out
+		}
+		out.Err = fmt.Errorf("remote %w", err)
 		return out
 	}
-
-	prefix := artifacts.S3SessionPrefix(cfg.Pipeline.Storage.S3.RootPrefix, cfg.Session.Campaign, cfg.Session.PreviousSessionID)
-	if _, err := artifacts.LoadCurrentState(ctx, store, prefix, artifacts.CurrentStateValidation{
-		ExpectedSessionID: strings.TrimSpace(cfg.Session.PreviousSessionID),
-		ExpectedCampaign:  strings.TrimSpace(cfg.Session.Campaign),
-		ValidateRunID:     true,
-	}); err != nil {
-		out.Err = fmt.Errorf("remote %v", err)
-	}
+	out.SkippedMissing = append([]string(nil), plan.SkippedMissing...)
 	return out
 }
 

internal/app/operator_locks.go

@@ -38,10 +38,11 @@ func LocksList(ctx context.Context, args []string, out io.Writer) error {
 	if strings.TrimSpace(flags.sessionID) == "" {
 		return fmt.Errorf("locks: session_id is required")
 	}
-	cfg, _, locks, _, err := loadHelperContext(ctx, flags, true)
+	cfg, _, locks, _, cleanup, err := loadHelperContext(ctx, flags, true)
 	if err != nil {
 		return fmt.Errorf("locks: %w", err)
 	}
+	defer cleanup()
 	writeLocks(out, cfg, locks)
 	return nil
 }
@@ -63,26 +64,31 @@ func LocksAdd(ctx context.Context, args []string, out io.Writer) error {
 	if strings.TrimSpace(flags.sessionID) == "" {
 		return fmt.Errorf("locks add: session_id is required")
 	}
-	cfg, store, locks, _, err := loadHelperContext(ctx, flags, true)
+	cfg, store, locks, _, cleanup, err := loadHelperContext(ctx, flags, true)
 	if err != nil {
 		return fmt.Errorf("locks add: %w", err)
 	}
+	defer cleanup()
 	if _, err := config.ValidatePublishLockRules([]config.PublishLockRule{{Source: source}}, cfg.Pipeline.Scriptorium, cfg.Pipeline.Notarius, "locks add"); err != nil {
 		return fmt.Errorf("locks add: %w", err)
 	}
 	if _, ok := lockSourceSet(locks.Static)[source]; ok {
 		return fmt.Errorf("locks add: source %q is locked by pipeline config and cannot be modified remotely", source)
 	}
-	remoteSet := lockSourceSet(locks.Remote)
-	if _, exists := remoteSet[source]; exists && !force {
-		return fmt.Errorf("locks add: remote lock for %q already exists; pass --force to update", source)
-	}
-	remoteSet[source] = config.PublishLockRule{Source: source, Reason: strings.TrimSpace(reason)}
-	remoteLocks := lockMapValues(remoteSet)
-	if _, err := config.ValidatePublishLockRules(remoteLocks, cfg.Pipeline.Scriptorium, cfg.Pipeline.Notarius, "locks"); err != nil {
-		return fmt.Errorf("locks add: %w", err)
-	}
-	if err := uploadRemoteLockStore(ctx, store, locks.Key, &config.PublishLockStore{Locks: remoteLocks}); err != nil {
+	if err := mutateRemoteLockStore(ctx, cfg, store, func(lockStore *config.PublishLockStore) error {
+		remoteSet := lockSourceSet(lockStore.Locks)
+		if _, exists := remoteSet[source]; exists && !force {
+			return fmt.Errorf("remote lock for %q already exists; pass --force to update", source)
+		}
+		remoteSet[source] = config.PublishLockRule{Source: source, Reason: strings.TrimSpace(reason)}
+		lockStore.Locks = lockMapValues(remoteSet)
+		normalized, err := config.ValidatePublishLockRules(lockStore.Locks, cfg.Pipeline.Scriptorium, cfg.Pipeline.Notarius, "locks")
+		if err != nil {
+			return err
+		}
+		lockStore.Locks = normalized
+		return nil
+	}); err != nil {
 		return fmt.Errorf("locks add: %w", err)
 	}
 	_, err = fmt.Fprintf(out, "narratio session locks add: locked %s\n", source)
@@ -102,23 +108,26 @@ func LocksRemove(ctx context.Context, args []string, out io.Writer) error {
 	if strings.TrimSpace(flags.sessionID) == "" {
 		return fmt.Errorf("locks remove: session_id is required")
 	}
-	cfg, store, locks, _, err := loadHelperContext(ctx, flags, true)
+	cfg, store, locks, _, cleanup, err := loadHelperContext(ctx, flags, true)
 	if err != nil {
 		return fmt.Errorf("locks remove: %w", err)
 	}
+	defer cleanup()
 	if _, err := config.ValidatePublishLockRules([]config.PublishLockRule{{Source: source}}, cfg.Pipeline.Scriptorium, cfg.Pipeline.Notarius, "locks remove"); err != nil {
 		return fmt.Errorf("locks remove: %w", err)
 	}
-	remoteSet := lockSourceSet(locks.Remote)
-	if _, ok := remoteSet[source]; !ok {
-		if _, static := lockSourceSet(locks.Static)[source]; static {
-			return fmt.Errorf("locks remove: source %q is locked by pipeline config and cannot be unlocked remotely", source)
+	if err := mutateRemoteLockStore(ctx, cfg, store, func(lockStore *config.PublishLockStore) error {
+		remoteSet := lockSourceSet(lockStore.Locks)
+		if _, ok := remoteSet[source]; !ok {
+			if _, static := lockSourceSet(locks.Static)[source]; static {
+				return fmt.Errorf("source %q is locked by pipeline config and cannot be unlocked remotely", source)
+			}
+			return fmt.Errorf("remote lock for %q does not exist", source)
 		}
-		return fmt.Errorf("locks remove: remote lock for %q does not exist", source)
-	}
-	delete(remoteSet, source)
-	remoteLocks := lockMapValues(remoteSet)
-	if err := uploadRemoteLockStore(ctx, store, locks.Key, &config.PublishLockStore{Locks: remoteLocks}); err != nil {
+		delete(remoteSet, source)
+		lockStore.Locks = lockMapValues(remoteSet)
+		return nil
+	}); err != nil {
 		return fmt.Errorf("locks remove: %w", err)
 	}
 	_, err = fmt.Fprintf(out, "narratio session locks remove: unlocked %s\n", source)

internal/app/operator_session_init_test.go

@@ -0,0 +1,52 @@
+package app
+
+import (
+	"bytes"
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestSessionInitRejectsRenderedTemplateThatOmitsExpectedPreviousSession(t *testing.T) {
+	workspaceRoot := t.TempDir()
+	pipelinePath, campaignPath, _ := writeValidConfigFiles(t, workspaceRoot)
+	campaignDir := filepath.Dir(campaignPath)
+	templatePath := filepath.Join(campaignDir, "session.template.yml")
+	template := `session_id: {{ session_id }}
+campaign: sample-campaign
+inputs:
+  audio_dir: ./audio
+`
+	if err := os.WriteFile(templatePath, []byte(template), 0o644); err != nil {
+		t.Fatalf("write session template: %v", err)
+	}
+	campaign := `campaign_id: sample-campaign
+session_template_file: session.template.yml
+inputs:
+  speakers_file: ./speakers.yml
+  autocorrect_file: ./autocorrect.yml
+  glossary_file: ./glossary.yml
+  players_file: ./players.yml
+  party_file: ./party.yml
+`
+	if err := os.WriteFile(campaignPath, []byte(campaign), 0o644); err != nil {
+		t.Fatalf("write campaign config: %v", err)
+	}
+
+	var out bytes.Buffer
+	err := SessionInit(context.Background(), []string{
+		"2026-05-03",
+		"--config", pipelinePath,
+		"--campaign-file", campaignPath,
+		"--output", filepath.Join(t.TempDir(), "session.yml"),
+		"--previous-session-id", "2026-04-26",
+	}, &out)
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	if !strings.Contains(err.Error(), "unused template variable value(s): previous_session_id") {
+		t.Fatalf("SessionInit() error = %q, want missing previous-session template error", err.Error())
+	}
+}

internal/app/operator_session_validate.go

@@ -25,11 +25,13 @@ func SessionValidate(ctx context.Context, args []string, out io.Writer) error {
 	}
 
 	findings := []finding{}
-	cfg, err := loadCommandConfig(ctx, flags.pipelinePath, flags.campaignPath, flags.campaignFilePath, flags.sessionPath, flags.sessionOptions())
+	loaded, err := loadCommandConfig(ctx, flags.pipelinePath, flags.campaignPath, flags.campaignFilePath, flags.sessionPath, flags.sessionOptions())
 	if err != nil {
 		findings = append(findings, errorFinding("config", err.Error()))
 		return renderFindings(out, "", "", findings)
 	}
+	defer func() { _ = loaded.Close() }()
+	cfg := loaded.Config
 	if err := config.Validate(cfg); err != nil {
 		findings = append(findings, errorFinding("config", err.Error()))
 	} else {
@@ -53,16 +55,23 @@ func SessionValidate(ctx context.Context, args []string, out io.Writer) error {
 		}
 	}
 
-	requirements := artifacts.CollectPreviousArtifactRequirements(configuredScriptoriumArtifacts(cfg))
+	effective, effectiveErr := resolveEffectiveArtifacts(cfg, nil)
+	if effectiveErr != nil {
+		findings = append(findings, errorFinding("config", effectiveErr.Error()))
+		return renderFindings(out, cfg.Session.Campaign, cfg.Session.SessionID, findings)
+	}
+	requirements := artifacts.CollectPreviousArtifactRequirements(configuredScriptoriumArtifacts(cfg), effective)
 	previous := inspectPreviousArtifactReadiness(ctx, cfg, store, requirements)
 	if len(previous.Requirements) == 0 {
 		findings = append(findings, okFinding("previous", "no previous-session artifacts required"))
-	} else if previous.MissingID {
-		findings = append(findings, errorFinding("previous", "previous_session_id is required by configured previous-session artifacts"))
 	} else if previous.Err != nil {
 		findings = append(findings, errorFinding("previous", previous.Err.Error()))
 	} else {
 		for _, req := range previous.Requirements {
+			if !req.Required && previousRequirementSkipped(previous.SkippedMissing, req.Name) {
+				findings = append(findings, okFinding("previous", fmt.Sprintf("%s required=false unavailable", req.Name)))
+				continue
+			}
 			findings = append(findings, okFinding("previous", fmt.Sprintf("%s required=%t", req.Name, req.Required)))
 		}
 	}
@@ -82,3 +91,12 @@ func SessionValidate(ctx context.Context, args []string, out io.Writer) error {
 	}
 	return renderFindings(out, cfg.Session.Campaign, cfg.Session.SessionID, findings)
 }
+
+func previousRequirementSkipped(values []string, name string) bool {
+	for _, value := range values {
+		if value == name {
+			return true
+		}
+	}
+	return false
+}

internal/app/operator_status.go

@@ -26,10 +26,12 @@ func Status(ctx context.Context, args []string, out io.Writer) error {
 	if strings.TrimSpace(flags.sessionID) == "" {
 		return fmt.Errorf("status: session_id is required")
 	}
-	cfg, err := loadCommandConfig(ctx, flags.pipelinePath, flags.campaignPath, flags.campaignFilePath, flags.sessionPath, flags.sessionOptions())
+	loaded, err := loadCommandConfig(ctx, flags.pipelinePath, flags.campaignPath, flags.campaignFilePath, flags.sessionPath, flags.sessionOptions())
 	if err != nil {
 		return fmt.Errorf("status: %w", err)
 	}
+	defer func() { _ = loaded.Close() }()
+	cfg := loaded.Config
 	if err := config.Validate(cfg); err != nil {
 		return fmt.Errorf("status: %w", err)
 	}
@@ -53,6 +55,7 @@ func Status(ctx context.Context, args []string, out io.Writer) error {
 	}
 
 	store, storeErr := objectStoreIfConfigured(ctx, cfg)
+	var remoteCurrent *RemoteCurrentState
 	if storeErr != nil {
 		fmt.Fprintf(out, "Remote publish: unavailable: %v\n", storeErr)
 	} else if store != nil {
@@ -60,16 +63,21 @@ func Status(ctx context.Context, args []string, out io.Writer) error {
 		if current.Err != nil {
 			fmt.Fprintf(out, "Remote publish: missing or unavailable: %v\n", current.Err)
 		} else {
+			remoteCurrent = current.State
 			fmt.Fprintf(out, "Remote publish: current run %s\n", current.State.RunID)
 			fmt.Fprintf(out, "Remote manifest: %s\n", current.State.CurrentManifestKey)
 		}
 	}
 	writeStatusRemoteAudio(ctx, out, cfg, store, storeErr)
+	effective, effectiveErr := resolveEffectiveArtifacts(cfg, nil)
+	if effectiveErr != nil {
+		return fmt.Errorf("status: resolve effective artifacts: %w", effectiveErr)
+	}
 	writeStatusPreviousArtifacts(out, inspectPreviousArtifactReadiness(
 		ctx,
 		cfg,
 		store,
-		artifacts.CollectPreviousArtifactRequirements(configuredScriptoriumArtifacts(cfg)),
+		artifacts.CollectPreviousArtifactRequirements(configuredScriptoriumArtifacts(cfg), effective),
 	))
 
 	lockChecks := inspectEffectiveLocks(ctx, cfg, store)
@@ -87,7 +95,7 @@ func Status(ctx context.Context, args []string, out io.Writer) error {
 		}
 		publishedRemoteState := map[string]string{}
 		if store != nil {
-			publishedRemoteState = remotePublishedOutputAvailability(ctx, cfg, store, catalog)
+			publishedRemoteState = remotePublishedOutputAvailabilityForCurrent(ctx, cfg, store, catalog, remoteCurrent)
 		}
 		fmt.Fprintln(out, "Remote outputs:")
 		writeArtifactList(out, cfg, catalog, catalogLocks, publishedRemoteState)
@@ -152,10 +160,6 @@ func writeStatusPreviousArtifacts(out io.Writer, readiness previousArtifactReadi
 		fmt.Fprintln(out, "Previous-session artifacts: not required")
 		return
 	}
-	if readiness.MissingID {
-		fmt.Fprintln(out, "Previous-session artifacts: unavailable: previous_session_id is required by configured previous-session artifacts")
-		return
-	}
 	if readiness.Err != nil {
 		fmt.Fprintf(out, "Previous-session artifacts: unavailable: %v\n", readiness.Err)
 		return
@@ -165,5 +169,9 @@ func writeStatusPreviousArtifacts(out io.Writer, readiness previousArtifactReadi
 		names = append(names, fmt.Sprintf("%s(required=%t)", req.Name, req.Required))
 	}
 	sort.Strings(names)
+	if len(readiness.SkippedMissing) > 0 {
+		fmt.Fprintf(out, "Previous-session artifacts: ready: %s; optional unavailable: %s\n", strings.Join(names, ", "), strings.Join(readiness.SkippedMissing, ", "))
+		return
+	}
 	fmt.Fprintf(out, "Previous-session artifacts: ready: %s\n", strings.Join(names, ", "))
 }

internal/app/paths_test_helpers_test.go

@@ -0,0 +1,16 @@
+package app
+
+import (
+	"testing"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
+)
+
+func mustPreviousArtifactPathForCampaign(t *testing.T, root, campaign, sessionID, relative string) string {
+	t.Helper()
+	path, err := artifacts.SessionPreviousArtifactPathForCampaign(root, campaign, sessionID, relative)
+	if err != nil {
+		t.Fatalf("SessionPreviousArtifactPathForCampaign() error = %v", err)
+	}
+	return path
+}

internal/app/plan.go

@@ -30,10 +30,12 @@ func Plan(ctx context.Context, args []string, out io.Writer) error {
 	if flags.sessionID == "" {
 		return fmt.Errorf("plan: session_id is required")
 	}
-	cfg, err := loadCommandConfig(ctx, flags.pipelinePath, flags.campaignPath, flags.campaignFilePath, flags.sessionPath, flags.sessionOptions())
+	loaded, err := loadCommandConfig(ctx, flags.pipelinePath, flags.campaignPath, flags.campaignFilePath, flags.sessionPath, flags.sessionOptions())
 	if err != nil {
 		return fmt.Errorf("plan: %w", err)
 	}
+	defer func() { _ = loaded.Close() }()
+	cfg := loaded.Config
 	if err := config.Validate(cfg); err != nil {
 		return fmt.Errorf("plan: %w", err)
 	}

internal/app/plan_test.go

@@ -109,7 +109,7 @@ seriatim:
 audita:
   binary: audita
 notification:
-  timeout: 10s
+  mode: noop
 `
 	sessionYAML := `session_id: 2026-05-03
 campaign: sample-campaign
@@ -133,8 +133,8 @@ inputs:
 	if err == nil {
 		t.Fatal("expected error, got nil")
 	}
-	if !strings.Contains(err.Error(), "read secrets env_dir") {
-		t.Fatalf("error = %q, want secrets read error context", err.Error())
+	if !strings.Contains(err.Error(), "validate secrets env_dir") {
+		t.Fatalf("error = %q, want secrets validation error context", err.Error())
 	}
 }
 

internal/app/post_publish_cleanup.go

@@ -3,113 +3,113 @@ package app
 import (
 	"context"
 	"fmt"
-	"os"
 	"path/filepath"
 	"strings"
 
 	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
 	"gitea.maximumdirect.net/eric/narratio/internal/config"
+	"gitea.maximumdirect.net/eric/narratio/internal/fileops"
 	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
 )
 
+var removeRunScopedDirFn = removeRunScopedDir
+
 func runPostPublishCleanup(ctx context.Context, env *Env, manifestPath string, m *manifest.Manifest, executed []string) error {
 	if env == nil || env.Config == nil || env.Config.Pipeline == nil || m == nil {
 		return nil
 	}
 
-	spoolRequested := env.Config.Pipeline.Spool.DeleteAudioAfterPublish
-	workRequested := env.Config.Pipeline.Workspace.CleanupAfterPublish
-	if !spoolRequested && !workRequested {
-		return nil
-	}
-
-	sr := publishStageRecordForCleanup(m, executed)
-	if sr == nil {
-		return nil
-	}
-	if sr.Metadata == nil {
-		sr.Metadata = map[string]any{}
-	}
-	sr.Metadata["spool_cleanup_requested"] = spoolRequested
-	sr.Metadata["workdir_cleanup_requested"] = workRequested
-
-	eligible, reason := publishCleanupEligible(env.Config, sr)
-	if !eligible {
-		sr.Metadata["cleanup_skipped"] = true
-		sr.Metadata["cleanup_skipped_reason"] = reason
-		if err := env.ManifestStore.Save(ctx, manifestPath, m); err != nil {
-			return fmt.Errorf("save manifest cleanup skip metadata %q: %w", manifestPath, err)
+	cleanup := m.PostPublishCleanup
+	if cleanup == nil {
+		var err error
+		cleanup, err = createPostPublishCleanup(env.Config, m, executed)
+		if err != nil {
+			return err
 		}
-		return nil
+		if cleanup == nil {
+			return nil
+		}
+		m.PostPublishCleanup = cleanup
+		if err := env.ManifestStore.Save(ctx, manifestPath, m); err != nil {
+			return fmt.Errorf("persist post-publish cleanup obligation %q: %w", manifestPath, err)
+		}
+	}
+
+	for index := range cleanup.Targets {
+		target := &cleanup.Targets[index]
+		if target.Completed {
+			continue
+		}
+		if err := removeRunScopedDirFn(target.Root, target.Path, target.Policy); err != nil {
+			return fmt.Errorf("complete post-publish cleanup for %q: %w", target.Path, err)
+		}
+		target.Completed = true
+		if err := env.ManifestStore.Save(ctx, manifestPath, m); err != nil {
+			target.Completed = false
+			return fmt.Errorf("persist post-publish cleanup completion %q: %w", manifestPath, err)
+		}
+	}
+	return nil
+}
+
+func createPostPublishCleanup(cfg *config.Config, m *manifest.Manifest, executed []string) (*manifest.PostPublishCleanup, error) {
+	spoolRequested := cfg.Pipeline.Spool.DeleteAudioAfterPublish
+	workRequested := cfg.Pipeline.Workspace.CleanupAfterPublish
+	if !spoolRequested && !workRequested {
+		return nil, nil
+	}
+
+	sr := publishStageRecordForCleanup(m)
+	publishedRunID, eligible, _ := publishCleanupEligible(cfg, m, sr, executed)
+	if !eligible {
+		return nil, nil
 	}
 
 	spoolDir := strings.TrimSpace(m.LocalSpoolDir)
 	if spoolDir == "" {
 		spoolDir = artifacts.SessionSpoolAudioDir(
-			env.Config.Pipeline.Spool.Root,
-			strings.TrimSpace(env.Config.Session.Campaign),
-			strings.TrimSpace(env.Config.Session.SessionID),
-			strings.TrimSpace(m.RunID),
+			cfg.Pipeline.Spool.Root,
+			strings.TrimSpace(m.Campaign),
+			strings.TrimSpace(m.SessionID),
+			publishedRunID,
 		)
 	}
 	workDir := strings.TrimSpace(m.LocalWorkDir)
 	if workDir == "" {
 		workDir = artifacts.SessionRunRootForCampaign(
-			env.Config.Pipeline.Workspace.Root,
-			strings.TrimSpace(env.Config.Session.Campaign),
-			strings.TrimSpace(env.Config.Session.SessionID),
-			strings.TrimSpace(m.RunID),
+			cfg.Pipeline.Workspace.Root,
+			strings.TrimSpace(m.Campaign),
+			strings.TrimSpace(m.SessionID),
+			publishedRunID,
 		)
 	}
 
+	cleanup := &manifest.PostPublishCleanup{
+		CommittedRunID:          publishedRunID,
+		RemoteCommitKey:         strings.TrimSpace(asString(sr.Metadata["remote_commit_key"])),
+		CurrentCommitPointerKey: strings.TrimSpace(asString(sr.Metadata["current_commit_pointer_key"])),
+	}
 	if spoolRequested {
-		if err := removeRunScopedDir(strings.TrimSpace(env.Config.Pipeline.Spool.Root), spoolDir, "pipeline.spool.delete_audio_after_publish"); err != nil {
-			sr.Metadata["cleanup_failed"] = true
-			sr.Metadata["cleanup_failed_policy"] = "pipeline.spool.delete_audio_after_publish"
-			sr.Metadata["cleanup_failed_path"] = spoolDir
-			_ = env.ManifestStore.Save(ctx, manifestPath, m)
-			return err
-		}
-		sr.Metadata["spool_cleanup_deleted"] = filepath.Clean(spoolDir)
+		cleanup.Targets = append(cleanup.Targets, manifest.CleanupTarget{
+			Policy: "pipeline.spool.delete_audio_after_publish",
+			Root:   strings.TrimSpace(cfg.Pipeline.Spool.Root),
+			Path:   filepath.Clean(spoolDir),
+		})
 	}
-
-	if !workRequested {
-		sr.Metadata["cleanup_completed"] = true
-		sr.Metadata["cleanup_skipped"] = false
-		if err := env.ManifestStore.Save(ctx, manifestPath, m); err != nil {
-			return fmt.Errorf("save manifest cleanup metadata %q: %w", manifestPath, err)
-		}
-		return nil
+	if workRequested {
+		cleanup.Targets = append(cleanup.Targets, manifest.CleanupTarget{
+			Policy: "pipeline.workspace.cleanup_after_publish",
+			Root:   strings.TrimSpace(cfg.Pipeline.Workspace.Root),
+			Path:   filepath.Clean(workDir),
+		})
 	}
-
-	if err := removeRunScopedDir(strings.TrimSpace(env.Config.Pipeline.Workspace.Root), workDir, "pipeline.workspace.cleanup_after_publish"); err != nil {
-		sr.Metadata["cleanup_failed"] = true
-		sr.Metadata["cleanup_failed_policy"] = "pipeline.workspace.cleanup_after_publish"
-		sr.Metadata["cleanup_failed_path"] = workDir
-		_ = env.ManifestStore.Save(ctx, manifestPath, m)
-		return err
-	}
-
-	sr.Metadata["workdir_cleanup_deleted"] = filepath.Clean(workDir)
-	sr.Metadata["cleanup_completed"] = true
-	sr.Metadata["cleanup_skipped"] = false
-	return nil
+	return cleanup, nil
 }
 
-func publishStageRecordForCleanup(m *manifest.Manifest, executed []string) *manifest.StageRecord {
+func publishStageRecordForCleanup(m *manifest.Manifest) *manifest.StageRecord {
 	if m == nil {
 		return nil
 	}
-	publishRan := false
-	for _, name := range executed {
-		if name == "publish" {
-			publishRan = true
-			break
-		}
-	}
-	if !publishRan {
-		return nil
-	}
 	sr := m.Stages["publish"]
 	if sr == nil || sr.Status != manifest.StatusSucceeded {
 		return nil
@@ -117,40 +117,56 @@ func publishStageRecordForCleanup(m *manifest.Manifest, executed []string) *mani
 	return sr
 }
 
-func publishCleanupEligible(cfg *config.Config, sr *manifest.StageRecord) (bool, string) {
+func publishCleanupEligible(cfg *config.Config, m *manifest.Manifest, sr *manifest.StageRecord, executed []string) (string, bool, string) {
 	if cfg == nil || cfg.Pipeline == nil || cfg.Pipeline.Publish == nil {
-		return false, "publish configuration is missing"
+		return "", false, "publish configuration is missing"
 	}
 	enabled := true
 	if cfg.Pipeline.Publish.Enabled != nil {
 		enabled = *cfg.Pipeline.Publish.Enabled
 	}
 	if !enabled {
-		return false, "publish.enabled is false"
+		return "", false, "publish.enabled is false"
 	}
 	uploadRun := true
 	if cfg.Pipeline.Publish.UploadRun != nil {
 		uploadRun = *cfg.Pipeline.Publish.UploadRun
 	}
 	if !uploadRun {
-		return false, "publish.upload_run is false"
+		return "", false, "publish.upload_run is false"
 	}
 	if sr == nil || sr.Metadata == nil {
-		return false, "publish metadata is missing"
+		return "", false, "publish metadata is missing"
 	}
 	if skipped, _ := sr.Metadata["skipped"].(bool); skipped {
-		return false, "publish stage was skipped"
+		return "", false, "publish stage was skipped"
 	}
 	if uploaded, _ := sr.Metadata["uploaded"].(bool); !uploaded {
-		return false, "publish did not upload run record"
+		return "", false, "publish did not upload run record"
 	}
-	if pointer, _ := sr.Metadata["current_pointer_written"].(bool); !pointer {
-		return false, "publish did not write current pointer"
+	if strings.TrimSpace(asString(sr.Metadata["remote_commit_key"])) == "" {
+		return "", false, "publish remote commit key is missing"
 	}
-	if strings.TrimSpace(asString(sr.Metadata["current_run_id_key"])) == "" {
-		return false, "publish current run pointer key is missing"
+	if strings.TrimSpace(asString(sr.Metadata["current_commit_pointer_key"])) == "" {
+		return "", false, "publish current commit pointer key is missing"
 	}
-	return true, ""
+	publishedRunID := strings.TrimSpace(asString(sr.Metadata["published_run_id"]))
+	if publishedRunID == "" && containsStage(executed, "publish") && m != nil {
+		publishedRunID = strings.TrimSpace(m.RunID)
+	}
+	if publishedRunID == "" {
+		return "", false, "publish run id is missing"
+	}
+	return publishedRunID, true, ""
+}
+
+func containsStage(names []string, target string) bool {
+	for _, name := range names {
+		if name == target {
+			return true
+		}
+	}
+	return false
 }
 
 type scopedDir struct {
@@ -167,7 +183,7 @@ func removeRunScopedDir(root, target, policy string) error {
 	if !dir.Exists {
 		return nil
 	}
-	if err := os.RemoveAll(dir.TargetAbs); err != nil {
+	if err := fileops.RemoveAllUnderRoot(dir.RootAbs, dir.TargetAbs); err != nil {
 		return fmt.Errorf("cleanup policy %s: remove %q: %w", policy, dir.TargetAbs, err)
 	}
 	return nil

internal/app/post_publish_cleanup_test.go

@@ -3,6 +3,7 @@ package app
 import (
 	"context"
 	"errors"
+	"io"
 	"os"
 	"path/filepath"
 	"strings"
@@ -18,16 +19,33 @@ import (
 
 type publishSuccessStage struct {
 	metadata map[string]any
+	targets  *cleanupSeed
 }
 
-func (publishSuccessStage) Name() string           { return "publish" }
-func (publishSuccessStage) Declares() stage.IODecl { return stage.IODecl{} }
-func (s publishSuccessStage) Run(_ context.Context, _ *stage.Env, _ *manifest.Manifest) (*stage.StageResult, error) {
+func (publishSuccessStage) Name() string { return "publish" }
+func (s publishSuccessStage) Run(_ context.Context, _ *stage.Env, m *manifest.Manifest) (*stage.StageResult, error) {
+	if s.targets != nil {
+		s.targets.runWorkDir = m.LocalWorkDir
+		s.targets.spoolAudioDir = m.LocalSpoolDir
+		if err := os.MkdirAll(filepath.Join(m.LocalWorkDir, "logs"), 0o755); err != nil {
+			return nil, err
+		}
+		if err := os.WriteFile(filepath.Join(m.LocalWorkDir, "logs", "stage.log"), []byte("log\n"), 0o644); err != nil {
+			return nil, err
+		}
+		if err := os.MkdirAll(m.LocalSpoolDir, 0o755); err != nil {
+			return nil, err
+		}
+		if err := os.WriteFile(filepath.Join(m.LocalSpoolDir, "speaker.flac"), []byte("flac\n"), 0o644); err != nil {
+			return nil, err
+		}
+	}
 	md := map[string]any{
-		"stage":                   "publish",
-		"uploaded":                true,
-		"current_pointer_written": true,
-		"current_run_id_key":      "dnd/campaigns/sample-campaign/sessions/2026-05-03/current/run_id.txt",
+		"stage":                      "publish",
+		"uploaded":                   true,
+		"published_run_id":           m.RunID,
+		"remote_commit_key":          "dnd/campaigns/sample-campaign/sessions/2026-05-03/runs/20260519T010203Z-a1b2c3d4/commit.json",
+		"current_commit_pointer_key": "dnd/campaigns/sample-campaign/sessions/2026-05-03/current/commit-pointer.json",
 	}
 	for k, v := range s.metadata {
 		md[k] = v
@@ -37,8 +55,7 @@ func (s publishSuccessStage) Run(_ context.Context, _ *stage.Env, _ *manifest.Ma
 
 type notifyFailStage struct{}
 
-func (notifyFailStage) Name() string           { return "notify" }
-func (notifyFailStage) Declares() stage.IODecl { return stage.IODecl{} }
+func (notifyFailStage) Name() string { return "notify" }
 func (notifyFailStage) Run(_ context.Context, _ *stage.Env, _ *manifest.Manifest) (*stage.StageResult, error) {
 	return nil, errors.New("notify failed")
 }
@@ -48,7 +65,7 @@ func TestPostPublishCleanupDisabledKeepsLocalDirs(t *testing.T) {
 	cfg.Pipeline.Spool.DeleteAudioAfterPublish = false
 	cfg.Pipeline.Workspace.CleanupAfterPublish = false
 
-	if _, err := executeStages(context.Background(), cfg, []stage.Stage{publishSuccessStage{}}, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}}); err != nil {
+	if _, err := executeStages(context.Background(), cfg, []stage.Stage{publishSuccessStage{targets: &seed}}, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}}); err != nil {
 		t.Fatalf("executeStages() error = %v", err)
 	}
 
@@ -62,7 +79,7 @@ func TestPostPublishCleanupSpoolOnly(t *testing.T) {
 	cfg.Pipeline.Spool.DeleteAudioAfterPublish = true
 	cfg.Pipeline.Workspace.CleanupAfterPublish = false
 
-	if _, err := executeStages(context.Background(), cfg, []stage.Stage{publishSuccessStage{}}, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}}); err != nil {
+	if _, err := executeStages(context.Background(), cfg, []stage.Stage{publishSuccessStage{targets: &seed}}, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}}); err != nil {
 		t.Fatalf("executeStages() error = %v", err)
 	}
 
@@ -76,7 +93,7 @@ func TestPostPublishCleanupWorkdirOnly(t *testing.T) {
 	cfg.Pipeline.Spool.DeleteAudioAfterPublish = false
 	cfg.Pipeline.Workspace.CleanupAfterPublish = true
 
-	if _, err := executeStages(context.Background(), cfg, []stage.Stage{publishSuccessStage{}}, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}}); err != nil {
+	if _, err := executeStages(context.Background(), cfg, []stage.Stage{publishSuccessStage{targets: &seed}}, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}}); err != nil {
 		t.Fatalf("executeStages() error = %v", err)
 	}
 
@@ -92,7 +109,7 @@ func TestPostPublishCleanupBothPolicies(t *testing.T) {
 	cfg.Pipeline.Spool.DeleteAudioAfterPublish = true
 	cfg.Pipeline.Workspace.CleanupAfterPublish = true
 
-	if _, err := executeStages(context.Background(), cfg, []stage.Stage{publishSuccessStage{}}, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}}); err != nil {
+	if _, err := executeStages(context.Background(), cfg, []stage.Stage{publishSuccessStage{targets: &seed}}, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}}); err != nil {
 		t.Fatalf("executeStages() error = %v", err)
 	}
 
@@ -102,6 +119,115 @@ func TestPostPublishCleanupBothPolicies(t *testing.T) {
 	assertExists(t, seed.previousCachePath)
 }
 
+func TestPostPublishCleanupRetriesWhenInitialObligationSaveFails(t *testing.T) {
+	cfg, seed := cleanupFixtureConfig(t)
+	cfg.Pipeline.Spool.DeleteAudioAfterPublish = true
+	cfg.Pipeline.Workspace.CleanupAfterPublish = false
+
+	failed := false
+	store := &cleanupFailingManifestStore{
+		delegate: &manifest.LocalStore{},
+		fail: func(m *manifest.Manifest) error {
+			if !failed && m.PostPublishCleanup != nil {
+				failed = true
+				return errors.New("injected obligation save failure")
+			}
+			return nil
+		},
+	}
+	_, err := executeStages(context.Background(), cfg, []stage.Stage{publishSuccessStage{targets: &seed}}, RunOptions{
+		Env: &Env{ManifestStore: store, ObjectStore: &storage.FakeBackend{}},
+	})
+	if err == nil || !strings.Contains(err.Error(), "post-publish cleanup incomplete") {
+		t.Fatalf("executeStages() error = %v, want incomplete cleanup", err)
+	}
+	assertExists(t, seed.spoolAudioDir)
+	assertCleanupPending(t, cfg)
+
+	store.fail = nil
+	if _, err := executeStages(context.Background(), cfg, nil, RunOptions{Env: &Env{ManifestStore: store, ObjectStore: &storage.FakeBackend{}}}); err != nil {
+		t.Fatalf("retry executeStages() error = %v", err)
+	}
+	assertMissing(t, seed.spoolAudioDir)
+	assertCleanupComplete(t, cfg)
+}
+
+func TestPostPublishCleanupRetriesFailedDeletionWithoutTouchingOtherRuns(t *testing.T) {
+	cfg, seed := cleanupFixtureConfig(t)
+	cfg.Pipeline.Spool.DeleteAudioAfterPublish = true
+	cfg.Pipeline.Workspace.CleanupAfterPublish = true
+
+	originalRemove := removeRunScopedDirFn
+	removeRunScopedDirFn = func(root, target, policy string) error {
+		if policy == "pipeline.workspace.cleanup_after_publish" {
+			return errors.New("injected deletion failure")
+		}
+		return originalRemove(root, target, policy)
+	}
+	t.Cleanup(func() { removeRunScopedDirFn = originalRemove })
+
+	_, err := executeStages(context.Background(), cfg, []stage.Stage{publishSuccessStage{targets: &seed}}, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}})
+	if err == nil || !strings.Contains(err.Error(), "post-publish cleanup incomplete") {
+		t.Fatalf("executeStages() error = %v, want incomplete cleanup", err)
+	}
+	assertMissing(t, seed.spoolAudioDir)
+	assertExists(t, seed.runWorkDir)
+	assertCleanupPending(t, cfg)
+	assertExists(t, seed.otherRunDir)
+	assertExists(t, seed.previousCachePath)
+
+	removeRunScopedDirFn = originalRemove
+	if _, err := executeStages(context.Background(), cfg, nil, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}}); err != nil {
+		t.Fatalf("retry executeStages() error = %v", err)
+	}
+	assertMissing(t, seed.runWorkDir)
+	assertExists(t, seed.otherRunDir)
+	assertExists(t, seed.previousCachePath)
+	assertCleanupComplete(t, cfg)
+}
+
+func TestPostPublishCleanupRetriesWhenCompletionEvidenceSaveFails(t *testing.T) {
+	cfg, seed := cleanupFixtureConfig(t)
+	cfg.Pipeline.Spool.DeleteAudioAfterPublish = true
+	cfg.Pipeline.Workspace.CleanupAfterPublish = false
+
+	failed := false
+	store := &cleanupFailingManifestStore{
+		delegate: &manifest.LocalStore{},
+		fail: func(m *manifest.Manifest) error {
+			if m.PostPublishCleanup == nil {
+				return nil
+			}
+			for _, target := range m.PostPublishCleanup.Targets {
+				if !failed && target.Completed {
+					failed = true
+					return errors.New("injected completion evidence failure")
+				}
+			}
+			return nil
+		},
+	}
+	_, err := executeStages(context.Background(), cfg, []stage.Stage{publishSuccessStage{targets: &seed}}, RunOptions{
+		Env: &Env{ManifestStore: store, ObjectStore: &storage.FakeBackend{}},
+	})
+	if err == nil || !strings.Contains(err.Error(), "post-publish cleanup incomplete") {
+		t.Fatalf("executeStages() error = %v, want incomplete cleanup", err)
+	}
+	assertMissing(t, seed.spoolAudioDir)
+	assertCleanupPending(t, cfg)
+
+	store.fail = nil
+	if _, err := executeStages(context.Background(), cfg, nil, RunOptions{Env: &Env{ManifestStore: store, ObjectStore: &storage.FakeBackend{}}}); err != nil {
+		t.Fatalf("retry executeStages() error = %v", err)
+	}
+	assertCleanupComplete(t, cfg)
+
+	if _, err := executeStages(context.Background(), cfg, nil, RunOptions{Env: &Env{ManifestStore: store, ObjectStore: &storage.FakeBackend{}}}); err != nil {
+		t.Fatalf("idempotent retry executeStages() error = %v", err)
+	}
+	assertMissing(t, seed.spoolAudioDir)
+}
+
 func TestPostPublishCleanupNotRunWhenPublishFails(t *testing.T) {
 	cfg, seed := cleanupFixtureConfig(t)
 	cfg.Pipeline.Spool.DeleteAudioAfterPublish = true
@@ -121,7 +247,7 @@ func TestPostPublishCleanupNotRunWhenPublishSkipped(t *testing.T) {
 	cfg.Pipeline.Spool.DeleteAudioAfterPublish = true
 	cfg.Pipeline.Workspace.CleanupAfterPublish = true
 
-	if _, err := executeStages(context.Background(), cfg, []stage.Stage{publishSuccessStage{metadata: map[string]any{"skipped": true}}}, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}}); err != nil {
+	if _, err := executeStages(context.Background(), cfg, []stage.Stage{publishSuccessStage{metadata: map[string]any{"skipped": true}, targets: &seed}}, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}}); err != nil {
 		t.Fatalf("executeStages() error = %v", err)
 	}
 
@@ -129,12 +255,12 @@ func TestPostPublishCleanupNotRunWhenPublishSkipped(t *testing.T) {
 	assertExists(t, seed.runWorkDir)
 }
 
-func TestPostPublishCleanupNotRunWhenCurrentPointerMissing(t *testing.T) {
+func TestPostPublishCleanupNotRunWhenCommitPointerMissing(t *testing.T) {
 	cfg, seed := cleanupFixtureConfig(t)
 	cfg.Pipeline.Spool.DeleteAudioAfterPublish = true
 	cfg.Pipeline.Workspace.CleanupAfterPublish = true
 
-	if _, err := executeStages(context.Background(), cfg, []stage.Stage{publishSuccessStage{metadata: map[string]any{"current_pointer_written": false}}}, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}}); err != nil {
+	if _, err := executeStages(context.Background(), cfg, []stage.Stage{publishSuccessStage{metadata: map[string]any{"current_commit_pointer_key": ""}, targets: &seed}}, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}}); err != nil {
 		t.Fatalf("executeStages() error = %v", err)
 	}
 
@@ -148,7 +274,7 @@ func TestPostPublishCleanupNotRunWhenPublishUploadDisabled(t *testing.T) {
 	cfg.Pipeline.Workspace.CleanupAfterPublish = true
 	cfg.Pipeline.Publish.UploadRun = boolPtr(false)
 
-	if _, err := executeStages(context.Background(), cfg, []stage.Stage{publishSuccessStage{}}, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}}); err != nil {
+	if _, err := executeStages(context.Background(), cfg, []stage.Stage{publishSuccessStage{targets: &seed}}, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}}); err != nil {
 		t.Fatalf("executeStages() error = %v", err)
 	}
 
@@ -181,12 +307,28 @@ func TestPostPublishCleanupFailsOnUnsafePath(t *testing.T) {
 	if err != nil {
 		t.Fatalf("Load() error = %v", err)
 	}
-	m.LocalSpoolDir = filepath.Join(filepath.Dir(cfg.Pipeline.Spool.Root), "outside-spool")
+	m.MarkStageSucceeded("publish", time.Now().UTC(), nil)
+	m.Stages["publish"].Metadata = map[string]any{
+		"uploaded":                   true,
+		"published_run_id":           m.RunID,
+		"remote_commit_key":          "dnd/campaigns/sample-campaign/sessions/2026-05-03/runs/20260516T010203Z-1a2b3c4d/commit.json",
+		"current_commit_pointer_key": "dnd/campaigns/sample-campaign/sessions/2026-05-03/current/commit-pointer.json",
+	}
+	m.PostPublishCleanup = &manifest.PostPublishCleanup{
+		CommittedRunID:          m.RunID,
+		RemoteCommitKey:         m.Stages["publish"].Metadata["remote_commit_key"].(string),
+		CurrentCommitPointerKey: m.Stages["publish"].Metadata["current_commit_pointer_key"].(string),
+		Targets: []manifest.CleanupTarget{{
+			Policy: "pipeline.spool.delete_audio_after_publish",
+			Root:   cfg.Pipeline.Spool.Root,
+			Path:   filepath.Join(filepath.Dir(cfg.Pipeline.Spool.Root), "outside-spool"),
+		}},
+	}
 	if err := store.Save(context.Background(), manifestPath, m); err != nil {
 		t.Fatalf("Save() error = %v", err)
 	}
 
-	_, err = executeStages(context.Background(), cfg, []stage.Stage{publishSuccessStage{}}, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}})
+	_, err = executeStages(context.Background(), cfg, nil, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}})
 	if err == nil || !strings.Contains(err.Error(), "refusing to delete path outside root") {
 		t.Fatalf("executeStages() error = %v, want safe-path failure", err)
 	}
@@ -215,32 +357,33 @@ func TestPostPublishCleanupNotRunWhenOutputIsMissing(t *testing.T) {
 	assertExists(t, artifacts.SessionRunRootForCampaign(cfg.Pipeline.Workspace.Root, cfg.Session.Campaign, cfg.Session.SessionID, runID))
 }
 
-func TestPostPublishCleanupNotRunWhenCurrentManifestUploadFails(t *testing.T) {
+func TestPostPublishCleanupNotRunWhenCommittedManifestUploadFails(t *testing.T) {
 	cfg, seed, _ := publishStageCleanupFixture(t)
 	cfg.Pipeline.Spool.DeleteAudioAfterPublish = true
 	cfg.Pipeline.Workspace.CleanupAfterPublish = true
-	failKey := seed.sessionPrefix + "current/manifest.json"
 
 	publishStageImpl, err := stage.Select("publish")
 	if err != nil {
 		t.Fatalf("Select(publish) error = %v", err)
 	}
 	_, err = executeStages(context.Background(), cfg, []stage.Stage{publishStageImpl}, RunOptions{
-		Env: &Env{ObjectStore: &failKeyStore{delegate: &storage.FakeBackend{}, failKey: failKey}},
+		Env: &Env{ObjectStore: &failKeyStore{delegate: &storage.FakeBackend{}, fail: func(key string) bool {
+			return strings.HasSuffix(key, "/session-manifest.json")
+		}}},
 	})
-	if err == nil || !strings.Contains(err.Error(), "current manifest") {
-		t.Fatalf("executeStages() error = %v, want current-manifest failure", err)
+	if err == nil || !strings.Contains(err.Error(), "immutable object") {
+		t.Fatalf("executeStages() error = %v, want committed-manifest failure", err)
 	}
 
 	assertExists(t, seed.spoolAudioDir)
 	assertExists(t, seed.runWorkDir)
 }
 
-func TestPostPublishCleanupNotRunWhenCurrentPointerUploadFails(t *testing.T) {
+func TestPostPublishCleanupNotRunWhenCommitPointerUploadFails(t *testing.T) {
 	cfg, seed, _ := publishStageCleanupFixture(t)
 	cfg.Pipeline.Spool.DeleteAudioAfterPublish = true
 	cfg.Pipeline.Workspace.CleanupAfterPublish = true
-	failKey := seed.sessionPrefix + "current/run_id.txt"
+	failKey := artifacts.S3CurrentCommitPointerKey(seed.sessionPrefix)
 
 	publishStageImpl, err := stage.Select("publish")
 	if err != nil {
@@ -249,8 +392,8 @@ func TestPostPublishCleanupNotRunWhenCurrentPointerUploadFails(t *testing.T) {
 	_, err = executeStages(context.Background(), cfg, []stage.Stage{publishStageImpl}, RunOptions{
 		Env: &Env{ObjectStore: &failKeyStore{delegate: &storage.FakeBackend{}, failKey: failKey}},
 	})
-	if err == nil || !strings.Contains(err.Error(), "current run pointer") {
-		t.Fatalf("executeStages() error = %v, want current-run-pointer failure", err)
+	if err == nil || !strings.Contains(err.Error(), "current commit pointer") {
+		t.Fatalf("executeStages() error = %v, want current-commit-pointer failure", err)
 	}
 
 	assertExists(t, seed.spoolAudioDir)
@@ -258,6 +401,7 @@ func TestPostPublishCleanupNotRunWhenCurrentPointerUploadFails(t *testing.T) {
 }
 
 type cleanupSeed struct {
+	runID             string
 	runWorkDir        string
 	otherRunDir       string
 	spoolAudioDir     string
@@ -266,6 +410,28 @@ type cleanupSeed struct {
 	sessionPrefix     string
 }
 
+type cleanupFailingManifestStore struct {
+	delegate manifest.Store
+	fail     func(*manifest.Manifest) error
+}
+
+func (s *cleanupFailingManifestStore) Create(ctx context.Context, sessionID string) (*manifest.Manifest, error) {
+	return s.delegate.Create(ctx, sessionID)
+}
+
+func (s *cleanupFailingManifestStore) Load(ctx context.Context, path string) (*manifest.Manifest, error) {
+	return s.delegate.Load(ctx, path)
+}
+
+func (s *cleanupFailingManifestStore) Save(ctx context.Context, path string, m *manifest.Manifest) error {
+	if s.fail != nil {
+		if err := s.fail(m); err != nil {
+			return err
+		}
+	}
+	return s.delegate.Save(ctx, path, m)
+}
+
 func cleanupFixtureConfig(t *testing.T) (*config.Config, cleanupSeed) {
 	t.Helper()
 
@@ -277,7 +443,7 @@ func cleanupFixtureConfig(t *testing.T) (*config.Config, cleanupSeed) {
 	runWorkDir := artifacts.SessionRunRootForCampaign(cfg.Pipeline.Workspace.Root, cfg.Session.Campaign, cfg.Session.SessionID, runID)
 	otherRunDir := artifacts.SessionRunRootForCampaign(cfg.Pipeline.Workspace.Root, cfg.Session.Campaign, cfg.Session.SessionID, "20260516T010204Z-5e6f7a8b")
 	spoolAudioDir := artifacts.SessionSpoolAudioDir(cfg.Pipeline.Spool.Root, cfg.Session.Campaign, cfg.Session.SessionID, runID)
-	previousCachePath := artifacts.SessionPreviousArtifactPathForCampaign(
+	previousCachePath := mustPreviousArtifactPathForCampaign(t,
 		cfg.Pipeline.Workspace.Root,
 		cfg.Session.Campaign,
 		cfg.Session.SessionID,
@@ -311,6 +477,7 @@ func cleanupFixtureConfig(t *testing.T) (*config.Config, cleanupSeed) {
 	}
 
 	return cfg, cleanupSeed{
+		runID:             runID,
 		runWorkDir:        runWorkDir,
 		otherRunDir:       otherRunDir,
 		spoolAudioDir:     spoolAudioDir,
@@ -385,23 +552,46 @@ func writePublishFixtureRunFiles(t *testing.T, runWorkDir, sessionRoot string) {
 type failKeyStore struct {
 	delegate *storage.FakeBackend
 	failKey  string
+	fail     func(string) bool
+}
+
+func (s *failKeyStore) fails(key string) bool {
+	return strings.TrimSpace(key) == strings.TrimSpace(s.failKey) || (s.fail != nil && s.fail(key))
 }
 
 func (s *failKeyStore) List(ctx context.Context, prefix string) ([]storage.ObjectInfo, error) {
 	return s.delegate.List(ctx, prefix)
 }
 
+func (s *failKeyStore) Read(ctx context.Context, key string) (storage.ObjectInfo, io.ReadCloser, error) {
+	return s.delegate.Read(ctx, key)
+}
+
 func (s *failKeyStore) Download(ctx context.Context, key, localPath string) error {
 	return s.delegate.Download(ctx, key, localPath)
 }
 
 func (s *failKeyStore) Upload(ctx context.Context, localPath, key string, opts storage.UploadOptions) (storage.ObjectInfo, error) {
-	if strings.TrimSpace(key) == strings.TrimSpace(s.failKey) {
+	if s.fails(key) {
 		return storage.ObjectInfo{}, errors.New("forced upload failure")
 	}
 	return s.delegate.Upload(ctx, localPath, key, opts)
 }
 
+func (s *failKeyStore) UploadReader(ctx context.Context, source io.Reader, key string, opts storage.UploadOptions) (storage.ObjectInfo, error) {
+	if s.fails(key) {
+		return storage.ObjectInfo{}, errors.New("forced upload failure")
+	}
+	return s.delegate.UploadReader(ctx, source, key, opts)
+}
+
+func (s *failKeyStore) UploadConditional(ctx context.Context, source io.Reader, key string, opts storage.UploadOptions, condition storage.WriteCondition) (storage.ObjectInfo, error) {
+	if s.fails(key) {
+		return storage.ObjectInfo{}, errors.New("forced upload failure")
+	}
+	return s.delegate.UploadConditional(ctx, source, key, opts, condition)
+}
+
 func (s *failKeyStore) Exists(ctx context.Context, key string) (bool, error) {
 	return s.delegate.Exists(ctx, key)
 }
@@ -419,3 +609,36 @@ func assertMissing(t *testing.T, path string) {
 		t.Fatalf("expected path to be removed %q, stat err=%v", path, err)
 	}
 }
+
+func assertCleanupPending(t *testing.T, cfg *config.Config) {
+	t.Helper()
+	m, err := (&manifest.LocalStore{}).Load(context.Background(), manifestPathFor(cfg))
+	if err != nil {
+		t.Fatalf("Load() error = %v", err)
+	}
+	if m.PostPublishCleanup == nil {
+		t.Fatal("expected a persisted cleanup obligation")
+	}
+	for _, target := range m.PostPublishCleanup.Targets {
+		if !target.Completed {
+			return
+		}
+	}
+	t.Fatal("expected at least one cleanup target to remain incomplete")
+}
+
+func assertCleanupComplete(t *testing.T, cfg *config.Config) {
+	t.Helper()
+	m, err := (&manifest.LocalStore{}).Load(context.Background(), manifestPathFor(cfg))
+	if err != nil {
+		t.Fatalf("Load() error = %v", err)
+	}
+	if m.PostPublishCleanup == nil {
+		t.Fatal("expected a persisted cleanup obligation")
+	}
+	for _, target := range m.PostPublishCleanup.Targets {
+		if !target.Completed {
+			t.Fatalf("cleanup target remains incomplete: %#v", target)
+		}
+	}
+}

internal/app/remote_locks.go

@@ -1,7 +1,9 @@
 package app
 
 import (
+	"bytes"
 	"context"
+	"errors"
 	"fmt"
 	"os"
 	"path/filepath"
@@ -10,6 +12,7 @@ import (
 	"gitea.maximumdirect.net/eric/narratio/internal/adapters/storage"
 	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
 	"gitea.maximumdirect.net/eric/narratio/internal/config"
+	"gitea.maximumdirect.net/eric/narratio/internal/fileops"
 )
 
 type effectiveLocks struct {
@@ -19,6 +22,12 @@ type effectiveLocks struct {
 	Key    string
 }
 
+const (
+	remoteLockMutationAttempts = 4
+	// MaxRemoteLockStoreBytes bounds the mutable remote publish-lock document.
+	MaxRemoteLockStoreBytes int64 = 1 << 20
+)
+
 func remoteLocksKey(cfg *config.Config) (string, error) {
 	if cfg == nil || cfg.Pipeline == nil || cfg.Session == nil {
 		return "", fmt.Errorf("resolved config is required")
@@ -34,32 +43,33 @@ func remoteLocksKey(cfg *config.Config) (string, error) {
 	return artifacts.S3SessionLocksKey(sessionPrefix), nil
 }
 
-func loadRemoteLockStore(ctx context.Context, cfg *config.Config, store storage.ObjectStore) (*config.PublishLockStore, string, error) {
+func loadRemoteLockStore(ctx context.Context, cfg *config.Config, store storage.ObjectStore) (*config.PublishLockStore, string, string, error) {
 	key, err := remoteLocksKey(cfg)
 	if err != nil {
-		return nil, "", err
+		return nil, "", "", err
 	}
-	exists, err := store.Exists(ctx, key)
+	if store == nil {
+		return nil, key, "", fmt.Errorf("remote lock store is required")
+	}
+	info, data, err := storage.ReadObjectBounded(ctx, store, key, MaxRemoteLockStoreBytes)
 	if err != nil {
-		return nil, key, fmt.Errorf("check remote locks %q: %w", key, err)
+		if errors.Is(err, os.ErrNotExist) {
+			return &config.PublishLockStore{}, key, "", nil
+		}
+		var limitErr *storage.ReadLimitError
+		if errors.As(err, &limitErr) {
+			return nil, key, "", fmt.Errorf("read remote lock control object %q with %d-byte limit: %w", key, MaxRemoteLockStoreBytes, err)
+		}
+		return nil, key, "", fmt.Errorf("read remote locks %q: %w", key, err)
 	}
-	if !exists {
-		return &config.PublishLockStore{}, key, nil
-	}
-	tmp, err := storage.DownloadObjectToTemp(ctx, store, key, "narratio-locks-*.yml")
-	if err != nil {
-		return nil, key, fmt.Errorf("download remote locks %q: %w", key, err)
-	}
-	defer func() { _ = os.Remove(tmp) }()
-	data, err := os.ReadFile(tmp)
-	if err != nil {
-		return nil, key, fmt.Errorf("read remote locks %q: %w", key, err)
+	if strings.TrimSpace(info.ETag) == "" {
+		return nil, key, "", fmt.Errorf("read remote locks %q: object has no generation", key)
 	}
 	lockStore, err := config.LoadPublishLockStoreBytes("s3://"+s3BucketName(cfg.Pipeline)+"/"+key, data, cfg.Pipeline.Scriptorium, cfg.Pipeline.Notarius)
 	if err != nil {
-		return nil, key, err
+		return nil, key, "", err
 	}
-	return lockStore, key, nil
+	return lockStore, key, info.ETag, nil
 }
 
 func loadEffectiveLocks(ctx context.Context, cfg *config.Config, store storage.ObjectStore) (*effectiveLocks, error) {
@@ -70,7 +80,7 @@ func loadEffectiveLocks(ctx context.Context, cfg *config.Config, store storage.O
 			All:    append([]config.PublishLockRule(nil), staticLocks...),
 		}, nil
 	}
-	lockStore, key, err := loadRemoteLockStore(ctx, cfg, store)
+	lockStore, key, _, err := loadRemoteLockStore(ctx, cfg, store)
 	if err != nil {
 		return nil, err
 	}
@@ -100,28 +110,38 @@ func applyEffectiveLocks(cfg *config.Config, locks []config.PublishLockRule) {
 	cfg.Pipeline.Publish.Locks = append([]config.PublishLockRule(nil), locks...)
 }
 
-func uploadRemoteLockStore(ctx context.Context, store storage.ObjectStore, key string, lockStore *config.PublishLockStore) error {
-	data, err := config.MarshalPublishLockStore(lockStore)
-	if err != nil {
+func mutateRemoteLockStore(ctx context.Context, cfg *config.Config, store storage.ObjectStore, mutate func(*config.PublishLockStore) error) error {
+	for attempt := 0; attempt < remoteLockMutationAttempts; attempt++ {
+		if err := ctx.Err(); err != nil {
+			return err
+		}
+		lockStore, key, generation, err := loadRemoteLockStore(ctx, cfg, store)
+		if err != nil {
+			return err
+		}
+		if err := mutate(lockStore); err != nil {
+			return err
+		}
+		data, err := config.MarshalPublishLockStore(lockStore)
+		if err != nil {
+			return err
+		}
+		condition := storage.WriteCondition{MatchETag: generation}
+		if generation == "" {
+			condition = storage.WriteCondition{RequireAbsent: true}
+		}
+		_, err = store.UploadConditional(ctx, bytes.NewReader(data), key, storage.UploadOptions{ContentType: "application/x-yaml; charset=utf-8"}, condition)
+		if err == nil {
+			return nil
+		}
+		if !errors.Is(err, storage.ErrConditionNotMet) {
+			return fmt.Errorf("upload remote locks %q: %w", key, err)
+		}
+	}
+	if err := ctx.Err(); err != nil {
 		return err
 	}
-	tmp, err := os.CreateTemp("", "narratio-locks-upload-*.yml")
-	if err != nil {
-		return fmt.Errorf("create lock store temp file: %w", err)
-	}
-	tmpPath := tmp.Name()
-	defer func() { _ = os.Remove(tmpPath) }()
-	if _, err := tmp.Write(data); err != nil {
-		_ = tmp.Close()
-		return fmt.Errorf("write lock store temp file: %w", err)
-	}
-	if err := tmp.Close(); err != nil {
-		return fmt.Errorf("close lock store temp file: %w", err)
-	}
-	if _, err := store.Upload(ctx, tmpPath, key, storage.UploadOptions{ContentType: "application/x-yaml; charset=utf-8"}); err != nil {
-		return fmt.Errorf("upload remote locks %q: %w", key, err)
-	}
-	return nil
+	return fmt.Errorf("update remote locks: concurrent updates prevented a conditional write after %d attempts", remoteLockMutationAttempts)
 }
 
 func lockSourceSet(locks []config.PublishLockRule) map[string]config.PublishLockRule {
@@ -150,8 +170,11 @@ func writeLocalFile(path string, data []byte, force bool) error {
 			return fmt.Errorf("check output file %q: %w", cleaned, err)
 		}
 	}
-	if err := os.MkdirAll(filepath.Dir(cleaned), 0o755); err != nil {
+	if err := fileops.EnsureWorkspaceDirectory(filepath.Dir(cleaned)); err != nil {
 		return fmt.Errorf("create output directory: %w", err)
 	}
-	return os.WriteFile(cleaned, data, 0o644)
+	if err := os.WriteFile(cleaned, data, fileops.WorkspaceFileMode); err != nil {
+		return err
+	}
+	return os.Chmod(cleaned, fileops.WorkspaceFileMode)
 }

internal/app/remote_session_test.go

@@ -13,6 +13,7 @@ import (
 	"gitea.maximumdirect.net/eric/narratio/internal/adapters/storage"
 	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
 	"gitea.maximumdirect.net/eric/narratio/internal/config"
+	"gitea.maximumdirect.net/eric/narratio/internal/stage"
 )
 
 func TestExecuteRemoteSessionFallbackLoadsFromObjectStore(t *testing.T) {
@@ -44,6 +45,146 @@ inputs:
 	}
 }
 
+func TestRemoteSessionConfigIsRemovedAfterEveryCommandExit(t *testing.T) {
+	tests := []struct {
+		name           string
+		sessionYAML    string
+		command        []string
+		configureRun   func()
+		wantSuccessful bool
+	}{
+		{
+			name: "success",
+			sessionYAML: `session_id: 2026-05-03
+inputs:
+  audio_s3:
+    prefix: audio/
+`,
+			command:        []string{"session", "plan", "2026-05-03"},
+			wantSuccessful: true,
+		},
+		{
+			name: "validation failure",
+			sessionYAML: `session_id: 2026-05-03
+`,
+			command: []string{"session", "plan", "2026-05-03"},
+		},
+		{
+			name: "load failure",
+			sessionYAML: `session_id: 2026-05-03
+unknown: true
+`,
+			command: []string{"session", "plan", "2026-05-03"},
+		},
+		{
+			name: "adapter failure",
+			sessionYAML: `session_id: 2026-05-03
+inputs:
+  audio_s3:
+    prefix: audio/
+`,
+			command: []string{"run", "2026-05-03"},
+			configureRun: func() {
+				executeStagesFn = func(context.Context, *config.Config, []stage.Stage, RunOptions) (*RunSummary, error) {
+					return nil, errors.New("adapter failed")
+				}
+			},
+		},
+		{
+			name: "cancellation",
+			sessionYAML: `session_id: 2026-05-03
+inputs:
+  audio_s3:
+    prefix: audio/
+`,
+			command: []string{"run", "2026-05-03"},
+			configureRun: func() {
+				executeStagesFn = func(context.Context, *config.Config, []stage.Stage, RunOptions) (*RunSummary, error) {
+					return nil, context.Canceled
+				}
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			workspaceRoot := t.TempDir()
+			pipelinePath, campaignPath, _ := writeValidConfigFiles(t, workspaceRoot)
+			fake := &storage.FakeBackend{}
+			seedRemoteSessionConfig(t, fake, "2026-05-03", tt.sessionYAML)
+			var storeInitCalls int
+			restoreAppConfigTestGlobals(t, fake, &storeInitCalls, []string{filepath.Join(t.TempDir(), "session.yml")})
+
+			var downloadedPath string
+			captureRemoteSessionTempPath(t, &downloadedPath)
+			if tt.configureRun != nil {
+				origExecuteStagesFn := executeStagesFn
+				t.Cleanup(func() { executeStagesFn = origExecuteStagesFn })
+				tt.configureRun()
+			}
+
+			args := append(append([]string(nil), tt.command...), "--config", pipelinePath, "--campaign-file", campaignPath)
+			var stdout bytes.Buffer
+			var stderr bytes.Buffer
+			code := Execute(args, &stdout, &stderr)
+			if tt.wantSuccessful && code != 0 {
+				t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
+			}
+			if !tt.wantSuccessful && code == 0 {
+				t.Fatal("exit code = 0, want non-zero")
+			}
+			if downloadedPath == "" {
+				t.Fatal("remote session download path was not captured")
+			}
+			if _, err := os.Stat(downloadedPath); !errors.Is(err, os.ErrNotExist) {
+				t.Fatalf("downloaded remote session path still exists or could not be inspected: %q, err=%v", downloadedPath, err)
+			}
+		})
+	}
+}
+
+func TestRemoteSessionConfigCloseIsIdempotent(t *testing.T) {
+	workspaceRoot := t.TempDir()
+	pipelinePath, campaignPath, _ := writeValidConfigFiles(t, workspaceRoot)
+	fake := &storage.FakeBackend{}
+	seedRemoteSessionConfig(t, fake, "2026-05-03", `session_id: 2026-05-03
+inputs:
+  audio_s3:
+    prefix: audio/
+`)
+	var storeInitCalls int
+	restoreAppConfigTestGlobals(t, fake, &storeInitCalls, []string{filepath.Join(t.TempDir(), "session.yml")})
+
+	var downloadedPath string
+	captureRemoteSessionTempPath(t, &downloadedPath)
+	loaded, err := loadCommandConfig(context.Background(), pipelinePath, "", campaignPath, "", config.SessionLoadOptions{SessionID: "2026-05-03"})
+	if err != nil {
+		t.Fatalf("loadCommandConfig() error = %v", err)
+	}
+	if err := loaded.Close(); err != nil {
+		t.Fatalf("first Close() error = %v", err)
+	}
+	if err := loaded.Close(); err != nil {
+		t.Fatalf("second Close() error = %v", err)
+	}
+	if _, err := os.Stat(downloadedPath); !errors.Is(err, os.ErrNotExist) {
+		t.Fatalf("downloaded remote session path still exists or could not be inspected: %q, err=%v", downloadedPath, err)
+	}
+}
+
+func captureRemoteSessionTempPath(t *testing.T, destination *string) {
+	t.Helper()
+	original := downloadObjectToTempFn
+	downloadObjectToTempFn = func(ctx context.Context, store storage.ObjectStore, key, pattern string) (string, error) {
+		path, err := original(ctx, store, key, pattern)
+		if err == nil {
+			*destination = path
+		}
+		return path, err
+	}
+	t.Cleanup(func() { downloadObjectToTempFn = original })
+}
+
 func TestExecuteRemoteSessionFallbackLoadsSecretsBeforeObjectStoreInit(t *testing.T) {
 	workspaceRoot := t.TempDir()
 	pipelinePath, campaignPath, _ := writeValidConfigFiles(t, workspaceRoot)
@@ -51,8 +192,8 @@ func TestExecuteRemoteSessionFallbackLoadsSecretsBeforeObjectStoreInit(t *testin
 	secretKeyEnv := "NARRATIO_TEST_REMOTE_SESSION_SECRET"
 	restoreEnvAfterTest(t, accessKeyEnv, secretKeyEnv)
 	secretsDir := t.TempDir()
-	mustWriteTestFile(t, filepath.Join(secretsDir, accessKeyEnv), "remote-session-key-id\n")
-	mustWriteTestFile(t, filepath.Join(secretsDir, secretKeyEnv), "remote-session-secret\n")
+	mustWriteSecretFile(t, filepath.Join(secretsDir, accessKeyEnv), "remote-session-key-id\n")
+	mustWriteSecretFile(t, filepath.Join(secretsDir, secretKeyEnv), "remote-session-secret\n")
 	addSecretsToPipelineConfig(t, pipelinePath, secretsDir, accessKeyEnv, secretKeyEnv)
 
 	fake := &storage.FakeBackend{}

internal/app/restore.go

@@ -22,7 +22,7 @@ var buildRestorePlanFn = buildRestorePlan
 var executeRestorePlanFn = executeRestorePlan
 
 // Restore validates restore CLI/config inputs and storage preflight for future restore phases.
-func Restore(ctx context.Context, args []string, out io.Writer) error {
+func Restore(ctx context.Context, args []string, out io.Writer) (resultErr error) {
 	positionalSessionID, args := pullLeadingSessionID(args)
 	fs := flag.NewFlagSet("restore", flag.ContinueOnError)
 	fs.SetOutput(out)
@@ -54,10 +54,12 @@ func Restore(ctx context.Context, args []string, out io.Writer) error {
 	if strings.TrimSpace(flags.sessionID) == "" {
 		return fmt.Errorf("restore: session_id is required")
 	}
-	cfg, err := loadCommandConfig(ctx, flags.pipelinePath, flags.campaignPath, flags.campaignFilePath, flags.sessionPath, flags.sessionOptions())
+	loaded, err := loadCommandConfig(ctx, flags.pipelinePath, flags.campaignPath, flags.campaignFilePath, flags.sessionPath, flags.sessionOptions())
 	if err != nil {
 		return fmt.Errorf("restore: %w", err)
 	}
+	defer func() { _ = loaded.Close() }()
+	cfg := loaded.Config
 	if err := config.Validate(cfg); err != nil {
 		return fmt.Errorf("restore: %w", err)
 	}
@@ -69,23 +71,23 @@ func Restore(ctx context.Context, args []string, out io.Writer) error {
 	if err != nil {
 		return fmt.Errorf("restore: %w", err)
 	}
-	plan, err := buildRestorePlanFn(ctx, cfg, current, objectStore, RestorePlanOptions{
-		IncludeAudio: includeAudio,
-		Force:        force,
-		DryRun:       dryRun,
-	})
-	if err != nil {
-		return fmt.Errorf("restore: %w", err)
-	}
-	report, err := newRestoreReport(current, plan, RestorePlanOptions{
-		IncludeAudio: includeAudio,
-		Force:        force,
-		DryRun:       dryRun,
-	})
-	if err != nil {
-		return fmt.Errorf("restore: %w", err)
-	}
 	if dryRun {
+		plan, err := buildRestorePlanFn(ctx, cfg, current, objectStore, RestorePlanOptions{
+			IncludeAudio: includeAudio,
+			Force:        force,
+			DryRun:       true,
+		})
+		if err != nil {
+			return fmt.Errorf("restore: %w", err)
+		}
+		report, err := newRestoreReport(current, plan, RestorePlanOptions{
+			IncludeAudio: includeAudio,
+			Force:        force,
+			DryRun:       true,
+		})
+		if err != nil {
+			return fmt.Errorf("restore: %w", err)
+		}
 		if err := writeRestoreDryRunSummary(out, report); err != nil {
 			return fmt.Errorf("restore: write plan output: %w", err)
 		}
@@ -96,27 +98,54 @@ func Restore(ctx context.Context, args []string, out io.Writer) error {
 	if _, err := artifactStore.EnsureLayoutFor(cfg.Session.Campaign, cfg.Session.SessionID); err != nil {
 		return fmt.Errorf("restore: prepare workdir: %w", err)
 	}
-	lock, err := artifactStore.AcquireSessionLockFor(cfg.Session.Campaign, cfg.Session.SessionID)
+	lock, err := artifactStore.AcquireSessionLockForContext(ctx, cfg.Session.Campaign, cfg.Session.SessionID)
 	if err != nil {
 		return fmt.Errorf("restore: acquire session lock: %w", err)
 	}
 	defer func() {
-		_ = artifactStore.ReleaseSessionLock(lock)
+		if releaseErr := artifactStore.ReleaseSessionLock(lock); releaseErr != nil {
+			if resultErr == nil {
+				resultErr = fmt.Errorf("restore: release session lock: %w", releaseErr)
+			} else {
+				resultErr = errors.Join(resultErr, fmt.Errorf("restore: release session lock: %w", releaseErr))
+			}
+		}
 	}()
 
-	if plan.ConflictCount > 0 && !force {
+	// Classification and installation share the same transition lock as a
+	// runner. This prevents a runner from making reuse decisions against state
+	// that restore is about to replace.
+	plan, err := buildRestorePlanFn(ctx, cfg, current, objectStore, RestorePlanOptions{
+		IncludeAudio: includeAudio,
+		Force:        force,
+	})
+	if err != nil {
+		return fmt.Errorf("restore: %w", err)
+	}
+	report, err := newRestoreReport(current, plan, RestorePlanOptions{
+		IncludeAudio: includeAudio,
+		Force:        force,
+	})
+	if err != nil {
+		return fmt.Errorf("restore: %w", err)
+	}
+
+	if plan.ConflictCount > 0 {
 		report.setFailed(fmt.Errorf("conflict: %d conflicting path(s)", plan.ConflictCount))
 		if _, reportErr := persistRestoreReport(artifactStore, cfg, report); reportErr != nil {
 			return fmt.Errorf("restore: report failure: %w", reportErr)
 		}
 		return fmt.Errorf(
-			"restore conflict: %d conflicting path(s); rerun with --force to overwrite (download=%d skip_same=%d conflicts=%d)",
+			"restore conflict: %d conflicting path(s); --force can replace eligible regular files but not unresolved conflicts (download=%d skip_same=%d conflicts=%d)",
 			plan.ConflictCount,
 			plan.DownloadCount,
 			plan.SkipSameCount,
 			plan.ConflictCount,
 		)
 	}
+	if err := writeRestoreMarker(artifactStore.SessionPathsFor(cfg.Session.Campaign, cfg.Session.SessionID)); err != nil {
+		return fmt.Errorf("restore: mark incomplete restore: %w", err)
+	}
 
 	result, err := executeRestorePlanFn(ctx, cfg, current, plan, report, objectStore)
 	if err != nil {
@@ -128,6 +157,9 @@ func Restore(ctx context.Context, args []string, out io.Writer) error {
 	}
 	report.Execution.Downloaded = result.DownloadedCount
 	report.setSucceeded()
+	if err := clearRestoreMarker(artifactStore.SessionPathsFor(cfg.Session.Campaign, cfg.Session.SessionID)); err != nil {
+		return fmt.Errorf("restore: clear incomplete restore marker: %w", err)
+	}
 	if _, err := persistRestoreReport(artifactStore, cfg, report); err != nil {
 		return fmt.Errorf("restore: write report: %w", err)
 	}

internal/app/restore_commit_test.go

@@ -0,0 +1,308 @@
+package app
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/adapters/storage"
+	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
+	"gitea.maximumdirect.net/eric/narratio/internal/config"
+	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
+)
+
+func TestCommittedRestorePlanUsesOnlyDeclaredObjects(t *testing.T) {
+	cfg := restorePlanConfig(t)
+	fake := &storage.FakeBackend{}
+	current := seedCommittedRestoreSnapshot(t, cfg, fake, "20260519T010203Z-a1b2c3d4", map[string][]byte{
+		"transcripts/full.json": []byte(`{"segments":[1]}`),
+	})
+	fake.SeedObject(storage.FakeObject{Key: current.SessionPrefix + "artifacts/stale.md", Data: []byte("stale")})
+	fake.SeedObject(storage.FakeObject{Key: artifacts.S3RunRelativeDestinationKey(artifacts.S3RunPrefix(current.SessionPrefix, "20260519T010204Z-e5f6a7b8"), "transcripts/other.json"), Data: []byte("other")})
+
+	plan, err := buildRestorePlan(context.Background(), cfg, current, fake, RestorePlanOptions{})
+	if err != nil {
+		t.Fatalf("buildRestorePlan() error = %v", err)
+	}
+	got := actionRelPaths(plan.Actions)
+	want := []string{"manifest.json", "transcripts/full.json"}
+	if len(got) != len(want) {
+		t.Fatalf("action paths = %#v, want %#v", got, want)
+	}
+	for index := range want {
+		if got[index] != want[index] {
+			t.Fatalf("action paths = %#v, want %#v", got, want)
+		}
+	}
+}
+
+func TestCommittedRestoreReusesVerifiedManifestCandidate(t *testing.T) {
+	cfg := restorePlanConfig(t)
+	fake := &storage.FakeBackend{}
+	current := seedCommittedRestoreSnapshot(t, cfg, fake, "20260519T010203Z-a1b2c3d4", nil)
+
+	plan, err := buildRestorePlan(context.Background(), cfg, current, fake, RestorePlanOptions{})
+	if err != nil {
+		t.Fatalf("buildRestorePlan() error = %v", err)
+	}
+	if _, err := executeRestorePlan(context.Background(), cfg, current, plan, nil, fake); err != nil {
+		t.Fatalf("executeRestorePlan() error = %v", err)
+	}
+	if got := fakeReadCount(fake, current.CurrentManifestKey); got != 1 {
+		t.Fatalf("manifest reads = %d, want one discovery read reused by restore", got)
+	}
+	if got := fakeDownloadCount(fake, current.CurrentManifestKey); got != 0 {
+		t.Fatalf("manifest downloads = %d, want no temporary download", got)
+	}
+}
+
+func TestCommittedRestoreRejectsChangedGenerationForVerifiedManifestCandidate(t *testing.T) {
+	cfg := restorePlanConfig(t)
+	fake := &storage.FakeBackend{}
+	current := seedCommittedRestoreSnapshot(t, cfg, fake, "20260519T010203Z-a1b2c3d4", nil)
+	plan, err := buildRestorePlan(context.Background(), cfg, current, fake, RestorePlanOptions{})
+	if err != nil {
+		t.Fatalf("buildRestorePlan() error = %v", err)
+	}
+	fake.SeedObject(storage.FakeObject{Key: current.CurrentManifestKey, Data: []byte("changed manifest"), ETag: "changed-generation"})
+
+	_, err = executeRestorePlan(context.Background(), cfg, current, plan, nil, fake)
+	if err == nil || !strings.Contains(err.Error(), "generation mismatch") {
+		t.Fatalf("executeRestorePlan() error = %v, want generation mismatch", err)
+	}
+	if got := fakeReadCount(fake, current.CurrentManifestKey); got != 1 {
+		t.Fatalf("manifest reads = %d, want no second transfer for rejected candidate", got)
+	}
+}
+
+func TestCommittedStatusReportsOnlyDeclaredPublishedOutputs(t *testing.T) {
+	cfg := restorePlanConfig(t)
+	cfg.Pipeline.Publish = &config.PublishConfig{Outputs: []config.PublishOutputRule{{
+		Source: "narratio.transcript.final_trimmed",
+		Dest:   "transcripts/full.json",
+	}}}
+	fake := &storage.FakeBackend{}
+	current := seedCommittedRestoreSnapshot(t, cfg, fake, "20260519T010203Z-a1b2c3d4", map[string][]byte{
+		"transcripts/full.json": []byte("declared\n"),
+	})
+	fake.SeedObject(storage.FakeObject{Key: current.SessionPrefix + "transcripts/full.json", Data: []byte("mutable stale copy\n")})
+
+	availability := remotePublishedOutputAvailabilityForCurrent(context.Background(), cfg, fake, nil, current)
+	key := publishedOutputRemoteStateKey("narratio.transcript.final_trimmed", "transcripts/full.json")
+	if availability[key] != "remote=published" {
+		t.Fatalf("availability = %#v, want committed published output", availability)
+	}
+}
+
+func TestCommittedRestoreKeepsSelectedSnapshotWhenPointerChanges(t *testing.T) {
+	cfg := restorePlanConfig(t)
+	fake := &storage.FakeBackend{}
+	first := seedCommittedRestoreSnapshot(t, cfg, fake, "20260519T010203Z-a1b2c3d4", map[string][]byte{
+		"transcripts/full.json": []byte("from first commit\n"),
+	})
+	plan, err := buildRestorePlan(context.Background(), cfg, first, fake, RestorePlanOptions{})
+	if err != nil {
+		t.Fatalf("buildRestorePlan() error = %v", err)
+	}
+	_ = seedCommittedRestoreSnapshot(t, cfg, fake, "20260519T010204Z-e5f6a7b8", map[string][]byte{
+		"transcripts/full.json": []byte("from second commit\n"),
+	})
+
+	if _, err := executeRestorePlan(context.Background(), cfg, first, plan, nil, fake); err != nil {
+		t.Fatalf("executeRestorePlan() error = %v", err)
+	}
+	root := artifacts.SessionWorkDirForCampaign(cfg.Pipeline.Workspace.Root, cfg.Session.Campaign, cfg.Session.SessionID)
+	mustReadEquals(t, filepath.Join(root, "transcripts", "full.json"), "from first commit\n")
+	restored, err := (&manifest.LocalStore{}).Load(context.Background(), filepath.Join(root, "manifest.json"))
+	if err != nil {
+		t.Fatalf("load restored manifest: %v", err)
+	}
+	if restored.RunID != first.RunID {
+		t.Fatalf("restored run id = %q, want %q", restored.RunID, first.RunID)
+	}
+}
+
+func TestCommittedRestoreRejectsChangedDeclaredObjectBeforeManifestInstall(t *testing.T) {
+	cfg := restorePlanConfig(t)
+	fake := &storage.FakeBackend{}
+	current := seedCommittedRestoreSnapshot(t, cfg, fake, "20260519T010203Z-a1b2c3d4", map[string][]byte{
+		"transcripts/full.json": []byte("committed bytes\n"),
+	})
+	plan, err := buildRestorePlan(context.Background(), cfg, current, fake, RestorePlanOptions{})
+	if err != nil {
+		t.Fatalf("buildRestorePlan() error = %v", err)
+	}
+	key := artifacts.S3RunRelativeDestinationKey(artifacts.S3RunPrefix(current.SessionPrefix, current.RunID), "transcripts/full.json")
+	fake.SeedObject(storage.FakeObject{Key: key, Data: []byte("changed bytes\n")})
+
+	if _, err := executeRestorePlan(context.Background(), cfg, current, plan, nil, fake); err == nil {
+		t.Fatal("executeRestorePlan() error = nil, want committed-object verification failure")
+	}
+	root := artifacts.SessionWorkDirForCampaign(cfg.Pipeline.Workspace.Root, cfg.Session.Campaign, cfg.Session.SessionID)
+	if _, err := os.Stat(filepath.Join(root, "manifest.json")); !os.IsNotExist(err) {
+		t.Fatalf("manifest should not be installed after failed restore; stat err=%v", err)
+	}
+}
+
+func TestCommittedRestoreRejectsChangedDeclaredObjectGeneration(t *testing.T) {
+	cfg := restorePlanConfig(t)
+	fake := &storage.FakeBackend{}
+	current := seedCommittedRestoreSnapshot(t, cfg, fake, "20260519T010203Z-a1b2c3d4", map[string][]byte{
+		"transcripts/full.json": []byte("committed bytes\n"),
+	})
+	plan, err := buildRestorePlan(context.Background(), cfg, current, fake, RestorePlanOptions{})
+	if err != nil {
+		t.Fatalf("buildRestorePlan() error = %v", err)
+	}
+	key := artifacts.S3RunRelativeDestinationKey(artifacts.S3RunPrefix(current.SessionPrefix, current.RunID), "transcripts/full.json")
+	fake.SeedObject(storage.FakeObject{Key: key, Data: []byte("committed bytes\n"), ETag: "replacement-generation"})
+
+	if _, err := executeRestorePlan(context.Background(), cfg, current, plan, nil, fake); err == nil {
+		t.Fatal("executeRestorePlan() error = nil, want generation verification failure")
+	}
+	root := artifacts.SessionWorkDirForCampaign(cfg.Pipeline.Workspace.Root, cfg.Session.Campaign, cfg.Session.SessionID)
+	if _, err := os.Stat(filepath.Join(root, "manifest.json")); !os.IsNotExist(err) {
+		t.Fatalf("manifest should not be installed after failed restore; stat err=%v", err)
+	}
+}
+
+func TestCommittedRestoreRejectsMissingDeclaredObjectBeforeManifestInstall(t *testing.T) {
+	cfg := restorePlanConfig(t)
+	fake := &storage.FakeBackend{}
+	current := seedCommittedRestoreSnapshot(t, cfg, fake, "20260519T010203Z-a1b2c3d4", map[string][]byte{
+		"transcripts/full.json": []byte("committed bytes\n"),
+	})
+	plan, err := buildRestorePlan(context.Background(), cfg, current, fake, RestorePlanOptions{})
+	if err != nil {
+		t.Fatalf("buildRestorePlan() error = %v", err)
+	}
+	missingKey := artifacts.S3RunRelativeDestinationKey(artifacts.S3RunPrefix(current.SessionPrefix, current.RunID), "transcripts/full.json")
+	fake.DownloadHook = func(call storage.FakeDownloadCall) error {
+		if call.Key == missingKey {
+			return os.ErrNotExist
+		}
+		return nil
+	}
+
+	if _, err := executeRestorePlan(context.Background(), cfg, current, plan, nil, fake); err == nil {
+		t.Fatal("executeRestorePlan() error = nil, want missing-object failure")
+	}
+	root := artifacts.SessionWorkDirForCampaign(cfg.Pipeline.Workspace.Root, cfg.Session.Campaign, cfg.Session.SessionID)
+	if _, err := os.Stat(filepath.Join(root, "manifest.json")); !os.IsNotExist(err) {
+		t.Fatalf("manifest should not be installed after failed restore; stat err=%v", err)
+	}
+}
+
+func TestCommittedRestoreForceRetainsDirectoryConflict(t *testing.T) {
+	cfg := restorePlanConfig(t)
+	fake := &storage.FakeBackend{}
+	current := seedCommittedRestoreSnapshot(t, cfg, fake, "20260519T010203Z-a1b2c3d4", map[string][]byte{
+		"transcripts/full.json": []byte("committed bytes\n"),
+	})
+	root := artifacts.SessionWorkDirForCampaign(cfg.Pipeline.Workspace.Root, cfg.Session.Campaign, cfg.Session.SessionID)
+	if err := os.MkdirAll(filepath.Join(root, "transcripts", "full.json"), 0o755); err != nil {
+		t.Fatalf("MkdirAll() error = %v", err)
+	}
+
+	plan, err := buildRestorePlan(context.Background(), cfg, current, fake, RestorePlanOptions{Force: true})
+	if err != nil {
+		t.Fatalf("buildRestorePlan() error = %v", err)
+	}
+	if plan.ConflictCount != 1 {
+		t.Fatalf("ConflictCount = %d, want 1", plan.ConflictCount)
+	}
+	for _, action := range plan.Actions {
+		if action.LocalRelativePath == "transcripts/full.json" && action.ConflictKind != RestoreConflictDirectory {
+			t.Fatalf("ConflictKind = %q, want %q", action.ConflictKind, RestoreConflictDirectory)
+		}
+	}
+}
+
+func seedCommittedRestoreSnapshot(t *testing.T, cfg *config.Config, fake *storage.FakeBackend, runID string, outputs map[string][]byte) *RemoteCurrentState {
+	t.Helper()
+	sessionPrefix := artifacts.S3SessionPrefix("dnd", cfg.Session.Campaign, cfg.Session.SessionID)
+	remoteManifest := manifest.New(cfg.Session.SessionID, time.Now().UTC())
+	remoteManifest.Campaign = cfg.Session.Campaign
+	remoteManifest.RunID = runID
+	manifestData, err := json.Marshal(remoteManifest)
+	if err != nil {
+		t.Fatalf("marshal manifest: %v", err)
+	}
+	manifestData = append(manifestData, '\n')
+	manifestKey := artifacts.S3RunSessionManifestKey(sessionPrefix, runID)
+	fake.SeedObject(storage.FakeObject{Key: manifestKey, Data: manifestData})
+	artifactsByKey := []artifacts.RemoteArtifact{remoteRestoreArtifact(fake, artifacts.RemoteArtifactTypeSessionManifest, "session.manifest", manifestKey)}
+
+	paths := make([]string, 0, len(outputs))
+	for relative := range outputs {
+		paths = append(paths, relative)
+	}
+	sort.Strings(paths)
+	for _, relative := range paths {
+		key := artifacts.S3RunRelativeDestinationKey(artifacts.S3RunPrefix(sessionPrefix, runID), relative)
+		fake.SeedObject(storage.FakeObject{Key: key, Data: outputs[relative]})
+		artifactsByKey = append(artifactsByKey, remoteRestoreArtifact(fake, artifacts.RemoteArtifactTypePublishedOutput, "narratio.test", key))
+	}
+	commit := artifacts.RemoteCommitManifest{
+		FormatVersion: artifacts.RemoteCommitFormatVersion,
+		Campaign:      cfg.Session.Campaign,
+		SessionID:     cfg.Session.SessionID,
+		RunID:         runID,
+		Artifacts:     artifactsByKey,
+	}
+	commitData, err := artifacts.EncodeRemoteCommitManifest(commit)
+	if err != nil {
+		t.Fatalf("encode remote commit: %v", err)
+	}
+	commitKey := artifacts.S3RunCommitKey(sessionPrefix, runID)
+	fake.SeedObject(storage.FakeObject{Key: commitKey, Data: commitData})
+	commitObject := fake.Objects[commitKey]
+	pointerData, err := artifacts.EncodeCurrentCommitPointer(artifacts.CurrentCommitPointer{
+		FormatVersion:    artifacts.RemoteCommitFormatVersion,
+		Campaign:         cfg.Session.Campaign,
+		SessionID:        cfg.Session.SessionID,
+		RunID:            runID,
+		CommitKey:        commitKey,
+		CommitSHA256:     restoreCommitSHA256(commitData),
+		CommitSize:       int64(len(commitData)),
+		CommitGeneration: commitObject.ETag,
+	})
+	if err != nil {
+		t.Fatalf("encode current pointer: %v", err)
+	}
+	fake.SeedObject(storage.FakeObject{Key: artifacts.S3CurrentCommitPointerKey(sessionPrefix), Data: pointerData})
+	current, err := discoverRemoteCurrentState(context.Background(), cfg, fake)
+	if err != nil {
+		t.Fatalf("discoverRemoteCurrentState() error = %v", err)
+	}
+	return current
+}
+
+func remoteRestoreArtifact(fake *storage.FakeBackend, artifactType artifacts.RemoteArtifactType, source, key string) artifacts.RemoteArtifact {
+	object := fake.Objects[key]
+	return artifacts.RemoteArtifact{
+		Type: artifactType, Source: source, DestinationKey: key, SHA256: restoreCommitSHA256(object.Data), Size: int64(len(object.Data)), Generation: object.ETag,
+	}
+}
+
+func fakeReadCount(fake *storage.FakeBackend, key string) int {
+	count := 0
+	for _, call := range fake.Reads {
+		if call.Key == key {
+			count++
+		}
+	}
+	return count
+}
+
+func restoreCommitSHA256(data []byte) string {
+	sum := sha256.Sum256(data)
+	return hex.EncodeToString(sum[:])
+}

internal/app/restore_discovery.go

@@ -21,6 +21,8 @@ type RemoteCurrentState struct {
 	SessionID          string
 	Campaign           string
 	Manifest           *manifest.Manifest
+	ManifestData       []byte
+	Commit             *artifacts.RemoteCommitManifest
 }
 
 func discoverRemoteCurrentState(ctx context.Context, cfg *config.Config, store storage.ObjectStore) (*RemoteCurrentState, error) {
@@ -39,13 +41,12 @@ func discoverRemoteCurrentState(ctx context.Context, cfg *config.Config, store s
 	if err != nil {
 		return nil, fmt.Errorf("resolve publish session prefix: %w", err)
 	}
-	currentManifestKey, currentRunIDKey := artifacts.ResolveCurrentStateKeys(sessionPrefix)
-
 	requestedSession := strings.TrimSpace(cfg.Session.SessionID)
 	requestedCampaign := strings.TrimSpace(cfg.Session.Campaign)
 	current, err := artifacts.LoadCurrentState(ctx, store, sessionPrefix, artifacts.CurrentStateValidation{
 		ExpectedSessionID: requestedSession,
 		ExpectedCampaign:  requestedCampaign,
+		ValidateRunID:     true,
 	})
 	if err != nil {
 		return nil, fmt.Errorf("remote %w", err)
@@ -54,11 +55,13 @@ func discoverRemoteCurrentState(ctx context.Context, cfg *config.Config, store s
 	return &RemoteCurrentState{
 		Bucket:             bucket,
 		SessionPrefix:      sessionPrefix,
-		CurrentRunIDKey:    currentRunIDKey,
-		CurrentManifestKey: currentManifestKey,
+		CurrentRunIDKey:    current.CurrentRunIDKey,
+		CurrentManifestKey: current.CurrentManifestKey,
 		RunID:              current.RunID,
 		SessionID:          strings.TrimSpace(current.Manifest.SessionID),
 		Campaign:           strings.TrimSpace(current.Manifest.Campaign),
 		Manifest:           current.Manifest,
+		ManifestData:       append([]byte(nil), current.ManifestData...),
+		Commit:             current.Commit,
 	}, nil
 }

internal/app/restore_discovery_test.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"io"
 	"strings"
 	"testing"
 	"time"
@@ -151,23 +152,18 @@ func TestDiscoverRemoteCurrentStateUsesCurrentKeysUnderSessionPrefix(t *testing.
 
 	expectedRunKey := fmt.Sprintf("%scurrent/run_id.txt", sessionPrefix)
 	expectedManifestKey := fmt.Sprintf("%scurrent/manifest.json", sessionPrefix)
-	if !containsString(store.existsKeys, expectedRunKey) {
-		t.Fatalf("exists keys = %#v, want run pointer key %q", store.existsKeys, expectedRunKey)
+	if !containsString(store.readKeys, expectedRunKey) {
+		t.Fatalf("read keys = %#v, want run pointer key %q", store.readKeys, expectedRunKey)
 	}
-	if !containsString(store.existsKeys, expectedManifestKey) {
-		t.Fatalf("exists keys = %#v, want manifest key %q", store.existsKeys, expectedManifestKey)
-	}
-	if !containsString(store.downloadKeys, expectedRunKey) {
-		t.Fatalf("download keys = %#v, want run pointer key %q", store.downloadKeys, expectedRunKey)
-	}
-	if !containsString(store.downloadKeys, expectedManifestKey) {
-		t.Fatalf("download keys = %#v, want manifest key %q", store.downloadKeys, expectedManifestKey)
+	if !containsString(store.readKeys, expectedManifestKey) {
+		t.Fatalf("read keys = %#v, want manifest key %q", store.readKeys, expectedManifestKey)
 	}
 }
 
 type captureObjectStore struct {
 	delegate     storage.ObjectStore
 	existsKeys   []string
+	readKeys     []string
 	downloadKeys []string
 }
 
@@ -175,6 +171,11 @@ func (s *captureObjectStore) List(ctx context.Context, prefix string) ([]storage
 	return s.delegate.List(ctx, prefix)
 }
 
+func (s *captureObjectStore) Read(ctx context.Context, key string) (storage.ObjectInfo, io.ReadCloser, error) {
+	s.readKeys = append(s.readKeys, key)
+	return s.delegate.Read(ctx, key)
+}
+
 func (s *captureObjectStore) Download(ctx context.Context, key, localPath string) error {
 	s.downloadKeys = append(s.downloadKeys, key)
 	return s.delegate.Download(ctx, key, localPath)
@@ -184,6 +185,10 @@ func (s *captureObjectStore) Upload(ctx context.Context, localPath, key string,
 	return s.delegate.Upload(ctx, localPath, key, opts)
 }
 
+func (s *captureObjectStore) UploadConditional(ctx context.Context, source io.Reader, key string, opts storage.UploadOptions, condition storage.WriteCondition) (storage.ObjectInfo, error) {
+	return s.delegate.UploadConditional(ctx, source, key, opts, condition)
+}
+
 func (s *captureObjectStore) Exists(ctx context.Context, key string) (bool, error) {
 	s.existsKeys = append(s.existsKeys, key)
 	return s.delegate.Exists(ctx, key)
@@ -218,6 +223,7 @@ func restoreManifestJSON(t *testing.T, sessionID, campaign string) []byte {
 	payload := map[string]any{
 		"session_id": sessionID,
 		"campaign":   campaign,
+		"run_id":     "20260519T010203Z-a1b2c3d4",
 		"created_at": now,
 		"updated_at": now,
 		"stages":     map[string]any{},

internal/app/restore_execute.go

@@ -1,9 +1,12 @@
 package app
 
 import (
+	"bytes"
 	"context"
+	"crypto/sha256"
+	"encoding/hex"
 	"fmt"
-	"os"
+	"io"
 	"path/filepath"
 	"strings"
 
@@ -98,31 +101,110 @@ func executeRestoreDownloadAction(
 		return executeRestoreAudioAction(ctx, cfg, safeLocalPath, action, store)
 	}
 
-	tmpPath, err := downloadObjectToSiblingTemp(ctx, store, action.RemoteKey, safeLocalPath)
+	if err := fileops.EnsureWorkspaceDirectory(filepath.Dir(safeLocalPath)); err != nil {
+		return fmt.Errorf("create destination directory: %w", err)
+	}
+	temporary, err := fileops.DownloadToSiblingTemp(safeLocalPath, func(destination io.Writer) error {
+		if len(action.VerifiedContent) > 0 {
+			_, err := io.Copy(destination, bytes.NewReader(action.VerifiedContent))
+			return err
+		}
+		return storage.DownloadTo(ctx, store, action.RemoteKey, destination)
+	})
 	if err != nil {
 		return fmt.Errorf("download to temp file: %w", err)
 	}
-	removeTmp := true
-	defer func() {
-		if removeTmp {
-			_ = os.Remove(tmpPath)
-		}
-	}()
-
-	if action.LocalRelativePath == config.PathManifestFile {
-		if err := validateRestoredManifest(ctx, cfg, current, tmpPath); err != nil {
-			return err
-		}
+	defer func() { _ = temporary.Cleanup() }()
+	if err := verifyRestoredObject(ctx, store, action, temporary); err != nil {
+		return err
 	}
 
-	if err := fileops.InstallDownloadedTempFile(tmpPath, safeLocalPath, 0o644); err != nil {
+	if isRestoreManifest(action.LocalRelativePath) {
+		file, err := temporary.Open()
+		if err != nil {
+			return fmt.Errorf("open restored manifest: %w", err)
+		}
+		destinationRoot := sessionRoot
+		requireCurrentIdentity := action.LocalRelativePath == config.PathManifestFile
+		if !requireCurrentIdentity {
+			destinationRoot = filepath.Dir(safeLocalPath)
+		}
+		restored, prepareErr := prepareRestoredManifest(ctx, cfg, current, file, destinationRoot, requireCurrentIdentity)
+		closeErr := file.Close()
+		if prepareErr != nil {
+			return prepareErr
+		}
+		if closeErr != nil {
+			return fmt.Errorf("close restored manifest: %w", closeErr)
+		}
+		if err := (&manifest.LocalStore{}).Save(ctx, safeLocalPath, restored); err != nil {
+			return fmt.Errorf("install rebased manifest atomically: %w", err)
+		}
+		return nil
+	}
+
+	if err := temporary.Install(filepath.Base(safeLocalPath), fileops.WorkspaceFileMode); err != nil {
 		return fmt.Errorf("install file atomically: %w", err)
 	}
-	removeTmp = false
 
 	return nil
 }
 
+func isRestoreManifest(relativePath string) bool {
+	clean := filepath.ToSlash(filepath.Clean(strings.TrimSpace(relativePath)))
+	return clean == config.PathManifestFile || clean == config.PathPreviousDirSegment+"/"+config.PathManifestFile
+}
+
+func verifyRestoredObject(ctx context.Context, store storage.ObjectStore, action RestoreAction, temporary *fileops.DownloadedTempFile) error {
+	if strings.TrimSpace(action.SHA256) == "" && strings.TrimSpace(action.Generation) == "" {
+		return nil
+	}
+	if strings.TrimSpace(action.SHA256) == "" || strings.TrimSpace(action.Generation) == "" {
+		return fmt.Errorf("committed object identity for %q is incomplete", action.RemoteKey)
+	}
+	file, err := temporary.Open()
+	if err != nil {
+		return fmt.Errorf("open downloaded object for verification: %w", err)
+	}
+	digest := sha256.New()
+	count, copyErr := io.Copy(digest, file)
+	closeErr := file.Close()
+	if copyErr != nil {
+		return fmt.Errorf("checksum downloaded object: %w", copyErr)
+	}
+	if closeErr != nil {
+		return fmt.Errorf("close downloaded object: %w", closeErr)
+	}
+	if count != action.Size {
+		return fmt.Errorf("committed object size mismatch for %q: got %d, want %d", action.RemoteKey, count, action.Size)
+	}
+	if got := hex.EncodeToString(digest.Sum(nil)); got != action.SHA256 {
+		return fmt.Errorf("committed object checksum mismatch for %q: got %s, want %s", action.RemoteKey, got, action.SHA256)
+	}
+	objects, err := store.List(ctx, action.RemoteKey)
+	if err != nil {
+		return fmt.Errorf("read committed object identity for %q: %w", action.RemoteKey, err)
+	}
+	var found *storage.ObjectInfo
+	for _, object := range objects {
+		if normalizeRemoteKey(object.Key) != normalizeRemoteKey(action.RemoteKey) {
+			continue
+		}
+		if found != nil {
+			return fmt.Errorf("committed object %q is ambiguous", action.RemoteKey)
+		}
+		copy := object
+		found = &copy
+	}
+	if found == nil {
+		return fmt.Errorf("committed object %q is missing", action.RemoteKey)
+	}
+	if found.Size != action.Size || strings.TrimSpace(found.ETag) != action.Generation {
+		return fmt.Errorf("committed object generation mismatch for %q", action.RemoteKey)
+	}
+	return nil
+}
+
 func executeRestoreAudioAction(
 	ctx context.Context,
 	cfg *config.Config,
@@ -154,62 +236,3 @@ func executeRestoreAudioAction(
 	}
 	return nil
 }
-
-func downloadObjectToSiblingTemp(ctx context.Context, store storage.ObjectStore, remoteKey, destPath string) (string, error) {
-	if strings.TrimSpace(destPath) == "" {
-		return "", fmt.Errorf("destination path is required")
-	}
-	dir := filepath.Dir(destPath)
-	if err := os.MkdirAll(dir, 0o755); err != nil {
-		return "", fmt.Errorf("create destination directory: %w", err)
-	}
-	base := filepath.Base(destPath)
-	tmp, err := os.CreateTemp(dir, "."+base+".restore-*.tmp")
-	if err != nil {
-		return "", fmt.Errorf("create temp file: %w", err)
-	}
-	tmpPath := tmp.Name()
-	if err := tmp.Close(); err != nil {
-		_ = os.Remove(tmpPath)
-		return "", fmt.Errorf("close temp file: %w", err)
-	}
-
-	if err := store.Download(ctx, remoteKey, tmpPath); err != nil {
-		_ = os.Remove(tmpPath)
-		return "", err
-	}
-
-	return tmpPath, nil
-}
-
-func validateRestoredManifest(ctx context.Context, cfg *config.Config, current *RemoteCurrentState, path string) error {
-	manifestStore := &manifest.LocalStore{}
-	m, err := manifestStore.Load(ctx, path)
-	if err != nil {
-		return fmt.Errorf("validate manifest decode: %w", err)
-	}
-
-	requestedSession := strings.TrimSpace(cfg.Session.SessionID)
-	requestedCampaign := strings.TrimSpace(cfg.Session.Campaign)
-	manifestSession := strings.TrimSpace(m.SessionID)
-	manifestCampaign := strings.TrimSpace(m.Campaign)
-	if manifestSession != requestedSession {
-		return fmt.Errorf("manifest session_id %q does not match requested session_id %q", manifestSession, requestedSession)
-	}
-	if manifestCampaign == "" {
-		return fmt.Errorf("manifest campaign is required")
-	}
-	if manifestCampaign != requestedCampaign {
-		return fmt.Errorf("manifest campaign %q does not match requested campaign %q", manifestCampaign, requestedCampaign)
-	}
-	if current != nil {
-		if expected := strings.TrimSpace(current.SessionID); expected != "" && manifestSession != expected {
-			return fmt.Errorf("manifest session_id %q does not match discovered session_id %q", manifestSession, expected)
-		}
-		if expected := strings.TrimSpace(current.Campaign); expected != "" && manifestCampaign != expected {
-			return fmt.Errorf("manifest campaign %q does not match discovered campaign %q", manifestCampaign, expected)
-		}
-	}
-
-	return nil
-}

internal/app/restore_execution_test.go

@@ -4,7 +4,6 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
-	"fmt"
 	"os"
 	"path/filepath"
 	"strings"
@@ -75,11 +74,13 @@ func TestExecuteRestoreRoundTripsPublishedExtractionAndManifestMetadata(t *testi
 	remoteManifest := manifest.New(cfg.Session.SessionID, time.Now().UTC())
 	remoteManifest.Campaign = cfg.Session.Campaign
 	remoteManifest.RunID = "20260519T010203Z-a1b2c3d4"
+	producerRoot := "/prior/workspace/work/sample-campaign/2026-05-03"
+	remoteManifest.LocalWorkDir = filepath.Join(producerRoot, "runs", remoteManifest.RunID)
 	remoteManifest.Stages["extract"] = &manifest.StageRecord{
 		Name: "extract", Status: manifest.StatusSucceeded,
 		Outputs: []manifest.ArtifactRecord{{
 			Kind: "notarius_lane", SourceID: artifacts.ExtractionArtifactSourceID("encounters"),
-			LocalPath: "/prior/workspace/artifacts/notarius/extract-run-1/lanes/encounters.json",
+			LocalPath: filepath.Join(producerRoot, "artifacts", "encounters.json"),
 			Contract: &artifactmodel.ContractMetadata{
 				MediaType: "application/json", SchemaID: "encounters", SchemaVersion: "1",
 			},
@@ -111,6 +112,9 @@ func TestExecuteRestoreRoundTripsPublishedExtractionAndManifestMetadata(t *testi
 	if lane.Contract == nil || lane.Contract.SchemaID != "encounters" || lane.ExternalProvenance == nil || lane.ExternalProvenance.RunID != "notarius-run-1" {
 		t.Fatalf("restored extraction metadata = %#v", lane)
 	}
+	if want := filepath.Join(sessionRoot, "artifacts", "encounters.json"); lane.LocalPath != want {
+		t.Fatalf("rebased extraction path = %q, want %q", lane.LocalPath, want)
+	}
 }
 
 func TestExecuteRestoreIncludeAudioRestoresAudio(t *testing.T) {
@@ -199,7 +203,7 @@ func TestExecuteRestoreRestoresPreviousCacheWhenPresent(t *testing.T) {
 	if err != nil {
 		t.Fatalf("read restored previous manifest: %v", err)
 	}
-	if !strings.Contains(string(previousManifestBytes), `"session_id":"2026-04-26"`) {
+	if !strings.Contains(string(previousManifestBytes), `"session_id": "2026-04-26"`) {
 		t.Fatalf("restored previous manifest = %q, want previous session id", string(previousManifestBytes))
 	}
 	mustReadEquals(t, filepath.Join(sessionRoot, "previous", "artifacts", "session_recap.md"), "# previous recap\n")
@@ -229,6 +233,9 @@ func TestExecuteRestoreDryRunReportsPreviousCacheWithoutWriting(t *testing.T) {
 	if !strings.Contains(stdout.String(), "previous/artifacts/session_recap.md") {
 		t.Fatalf("stdout = %q, want planned previous-cache artifact", stdout.String())
 	}
+	if !strings.Contains(stdout.String(), "may read remote data; no session files will be written") {
+		t.Fatalf("stdout = %q, want dry-run remote-read notice", stdout.String())
+	}
 
 	sessionRoot := artifacts.SessionWorkDirForCampaign(workspaceRoot, cfg.Session.Campaign, cfg.Session.SessionID)
 	if _, err := os.Stat(filepath.Join(sessionRoot, "previous", "artifacts", "session_recap.md")); !os.IsNotExist(err) {
@@ -292,6 +299,9 @@ func TestExecuteRestoreForceOverwritesDifferingFile(t *testing.T) {
 	if !report.Force {
 		t.Fatalf("report force = %v, want true", report.Force)
 	}
+	if _, err := os.Stat(artifacts.SessionRestoreMarkerPathForCampaign(workspaceRoot, cfg.Session.Campaign, cfg.Session.SessionID)); !os.IsNotExist(err) {
+		t.Fatalf("restore marker should be cleared after success; stat err=%v", err)
+	}
 }
 
 func TestExecuteRestoreForceOverwritesDifferingPreviousCacheFile(t *testing.T) {
@@ -334,14 +344,11 @@ func TestExecuteRestoreLockConflictFailsAndWritesNothing(t *testing.T) {
 
 	restoreWithStoreAndRealPhases(t, fake)
 
-	var stdout bytes.Buffer
-	var stderr bytes.Buffer
-	code := Execute([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &stdout, &stderr)
-	if code == 0 {
-		t.Fatal("exit code = 0, want non-zero")
-	}
-	if !strings.Contains(stderr.String(), "acquire session lock") {
-		t.Fatalf("stderr = %q, want lock failure", stderr.String())
+	ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
+	defer cancel()
+	err = Restore(ctx, []string{"2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &bytes.Buffer{})
+	if err == nil || !strings.Contains(err.Error(), "acquire session lock") {
+		t.Fatalf("Restore() error = %v, want lock failure", err)
 	}
 
 	sessionRoot := artifacts.SessionWorkDirForCampaign(workspaceRoot, cfg.Session.Campaign, cfg.Session.SessionID)
@@ -350,21 +357,77 @@ func TestExecuteRestoreLockConflictFailsAndWritesNothing(t *testing.T) {
 	}
 }
 
-func TestExecuteRestoreInvalidManifestDoesNotCorruptExistingManifest(t *testing.T) {
+func TestExecuteRestorePlanInvalidManifestDoesNotCorruptExistingManifest(t *testing.T) {
+	cfg := restorePlanConfig(t)
+	store := &storage.FakeBackend{}
+	current := seedCommittedRestoreSnapshot(t, cfg, store, "20260519T010203Z-a1b2c3d4", map[string][]byte{
+		"transcripts/full.json": []byte("remote-transcript"),
+	})
+	sessionRoot := artifacts.SessionWorkDirForCampaign(cfg.Pipeline.Workspace.Root, cfg.Session.Campaign, cfg.Session.SessionID)
+	existing := manifest.New(cfg.Session.SessionID, nowUTC())
+	existing.Campaign = cfg.Session.Campaign
+	existingPath := filepath.Join(sessionRoot, "manifest.json")
+	manifestStore := &manifest.LocalStore{}
+	if err := manifestStore.Save(context.Background(), existingPath, existing); err != nil {
+		t.Fatalf("save existing local manifest: %v", err)
+	}
+	existingData, err := os.ReadFile(existingPath)
+	if err != nil {
+		t.Fatalf("read existing local manifest: %v", err)
+	}
+
+	plan, err := buildRestorePlan(context.Background(), cfg, current, store, RestorePlanOptions{Force: true})
+	if err != nil {
+		t.Fatalf("buildRestorePlan() error = %v", err)
+	}
+	invalidManifest := []byte("{invalid json")
+	foundManifest := false
+	manifestKey := ""
+	manifestGeneration := ""
+	for index := range plan.Actions {
+		if plan.Actions[index].LocalRelativePath != config.PathManifestFile {
+			continue
+		}
+		foundManifest = true
+		plan.Actions[index].VerifiedContent = invalidManifest
+		plan.Actions[index].SHA256 = restoreCommitSHA256(invalidManifest)
+		plan.Actions[index].Size = int64(len(invalidManifest))
+		manifestKey = plan.Actions[index].RemoteKey
+		manifestGeneration = plan.Actions[index].Generation
+	}
+	if !foundManifest {
+		t.Fatal("restore plan has no manifest action")
+	}
+	store.SeedObject(storage.FakeObject{Key: manifestKey, Data: invalidManifest, ETag: manifestGeneration})
+	report, err := newRestoreReport(current, plan, RestorePlanOptions{Force: true})
+	if err != nil {
+		t.Fatalf("newRestoreReport() error = %v", err)
+	}
+	_, err = executeRestorePlan(context.Background(), cfg, current, plan, report, store)
+	if err == nil || !strings.Contains(err.Error(), "validate manifest decode") {
+		t.Fatalf("executeRestorePlan() error = %v, want manifest validation failure", err)
+	}
+	mustReadEquals(t, filepath.Join(sessionRoot, "transcripts", "full.json"), "remote-transcript")
+	afterData, err := os.ReadFile(existingPath)
+	if err != nil {
+		t.Fatalf("read local manifest after failure: %v", err)
+	}
+	if string(afterData) != string(existingData) {
+		t.Fatalf("local manifest changed after failed restore; before=%q after=%q", string(existingData), string(afterData))
+	}
+}
+
+func TestExecuteRestoreInvalidManifestReportsFailureAndRetainsRecoveryMarker(t *testing.T) {
 	workspaceRoot := t.TempDir()
 	pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot)
-
-	base := &storage.FakeBackend{}
-	cfg, sessionPrefix, manifestKey, _ := seedRestoreCommittedState(t, base, pipelinePath, campaignPath, sessionPath)
-	seedRestoreObject(base, sessionPrefix+"transcripts/full.json", []byte("remote-transcript"))
-
-	toggled := &stagedManifestDownloadStore{
-		delegate:       base,
-		manifestKey:    manifestKey,
-		firstManifest:  restoreManifestJSON(t, cfg.Session.SessionID, cfg.Session.Campaign),
-		secondManifest: []byte("{invalid json"),
-		manifestReads:  0,
+	cfg, err := config.LoadWithSessionOptions(pipelinePath, campaignPath, sessionPath, config.SessionLoadOptions{})
+	if err != nil {
+		t.Fatalf("LoadWithSessionOptions() error = %v", err)
 	}
+	store := &storage.FakeBackend{}
+	seedCommittedRestoreSnapshot(t, cfg, store, "20260519T010203Z-a1b2c3d4", map[string][]byte{
+		"transcripts/full.json": []byte("remote-transcript"),
+	})
 
 	sessionRoot := artifacts.SessionWorkDirForCampaign(workspaceRoot, cfg.Session.Campaign, cfg.Session.SessionID)
 	existing := manifest.New(cfg.Session.SessionID, nowUTC())
@@ -379,11 +442,35 @@ func TestExecuteRestoreInvalidManifestDoesNotCorruptExistingManifest(t *testing.
 		t.Fatalf("read existing local manifest: %v", err)
 	}
 
-	restoreWithStoreAndRealPhases(t, toggled)
+	restoreWithStoreAndRealPhases(t, store)
+	realBuildRestorePlan := buildRestorePlanFn
+	buildRestorePlanFn = func(ctx context.Context, cfg *config.Config, current *RemoteCurrentState, objectStore storage.ObjectStore, opts RestorePlanOptions) (*RestorePlan, error) {
+		plan, err := realBuildRestorePlan(ctx, cfg, current, objectStore, opts)
+		if err != nil {
+			return nil, err
+		}
+		invalidManifest := []byte("{invalid json")
+		for index := range plan.Actions {
+			if plan.Actions[index].LocalRelativePath != config.PathManifestFile {
+				continue
+			}
+			plan.Actions[index].VerifiedContent = invalidManifest
+			plan.Actions[index].SHA256 = restoreCommitSHA256(invalidManifest)
+			plan.Actions[index].Size = int64(len(invalidManifest))
+			store.SeedObject(storage.FakeObject{
+				Key:  plan.Actions[index].RemoteKey,
+				Data: invalidManifest,
+				ETag: plan.Actions[index].Generation,
+			})
+			return plan, nil
+		}
+		t.Fatal("restore plan has no manifest action")
+		return nil, nil
+	}
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute([]string{"session", "restore", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--force"}, &stdout, &stderr)
+	code := Execute([]string{"session", "restore", cfg.Session.SessionID, "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--force"}, &stdout, &stderr)
 	if code == 0 {
 		t.Fatal("exit code = 0, want non-zero")
 	}
@@ -405,6 +492,10 @@ func TestExecuteRestoreInvalidManifestDoesNotCorruptExistingManifest(t *testing.
 	if string(afterData) != string(existingData) {
 		t.Fatalf("local manifest changed after failed restore; before=%q after=%q", string(existingData), string(afterData))
 	}
+	markerPath := artifacts.SessionRestoreMarkerPathForCampaign(workspaceRoot, cfg.Session.Campaign, cfg.Session.SessionID)
+	if _, err := os.Stat(markerPath); err != nil {
+		t.Fatalf("incomplete restore marker should remain after failed forced restore: %v", err)
+	}
 }
 
 func TestExecuteRestorePlanPathMismatchFails(t *testing.T) {
@@ -550,41 +641,3 @@ func fakeDownloadCount(fake *storage.FakeBackend, key string) int {
 	}
 	return count
 }
-
-type stagedManifestDownloadStore struct {
-	delegate       *storage.FakeBackend
-	manifestKey    string
-	firstManifest  []byte
-	secondManifest []byte
-	manifestReads  int
-}
-
-func (s *stagedManifestDownloadStore) List(ctx context.Context, prefix string) ([]storage.ObjectInfo, error) {
-	return s.delegate.List(ctx, prefix)
-}
-
-func (s *stagedManifestDownloadStore) Download(ctx context.Context, key, localPath string) error {
-	if strings.TrimSpace(key) == strings.TrimSpace(s.manifestKey) {
-		s.manifestReads++
-		payload := s.secondManifest
-		if s.manifestReads <= 1 {
-			payload = s.firstManifest
-		}
-		if err := os.MkdirAll(filepath.Dir(localPath), 0o755); err != nil {
-			return fmt.Errorf("download staged manifest: create parent: %w", err)
-		}
-		if err := os.WriteFile(localPath, payload, 0o644); err != nil {
-			return fmt.Errorf("download staged manifest: write local file: %w", err)
-		}
-		return nil
-	}
-	return s.delegate.Download(ctx, key, localPath)
-}
-
-func (s *stagedManifestDownloadStore) Upload(ctx context.Context, localPath, key string, opts storage.UploadOptions) (storage.ObjectInfo, error) {
-	return s.delegate.Upload(ctx, localPath, key, opts)
-}
-
-func (s *stagedManifestDownloadStore) Exists(ctx context.Context, key string) (bool, error) {
-	return s.delegate.Exists(ctx, key)
-}

internal/app/restore_manifest_paths.go

@@ -0,0 +1,216 @@
+package app
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"path"
+	"path/filepath"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/config"
+	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
+)
+
+func prepareRestoredManifest(
+	ctx context.Context,
+	cfg *config.Config,
+	current *RemoteCurrentState,
+	source io.Reader,
+	destinationRoot string,
+	requireCurrentIdentity bool,
+) (*manifest.Manifest, error) {
+	manifestStore := &manifest.LocalStore{}
+	m, err := manifestStore.LoadReader(ctx, source)
+	if err != nil {
+		return nil, fmt.Errorf("validate manifest decode: %w", err)
+	}
+	if requireCurrentIdentity {
+		if err := validateRestoredManifestIdentity(cfg, current, m); err != nil {
+			return nil, err
+		}
+	}
+	if err := rebaseRestoredManifestPaths(cfg, m, destinationRoot); err != nil {
+		return nil, err
+	}
+	return m, nil
+}
+
+func validateRestoredManifestIdentity(cfg *config.Config, current *RemoteCurrentState, m *manifest.Manifest) error {
+	if cfg == nil || cfg.Session == nil {
+		return fmt.Errorf("resolved session config is required")
+	}
+	requestedSession := strings.TrimSpace(cfg.Session.SessionID)
+	requestedCampaign := strings.TrimSpace(cfg.Session.Campaign)
+	manifestSession := strings.TrimSpace(m.SessionID)
+	manifestCampaign := strings.TrimSpace(m.Campaign)
+	if manifestSession != requestedSession {
+		return fmt.Errorf("manifest session_id %q does not match requested session_id %q", manifestSession, requestedSession)
+	}
+	if manifestCampaign == "" {
+		return fmt.Errorf("manifest campaign is required")
+	}
+	if manifestCampaign != requestedCampaign {
+		return fmt.Errorf("manifest campaign %q does not match requested campaign %q", manifestCampaign, requestedCampaign)
+	}
+	if current != nil {
+		if expected := strings.TrimSpace(current.SessionID); expected != "" && manifestSession != expected {
+			return fmt.Errorf("manifest session_id %q does not match discovered session_id %q", manifestSession, expected)
+		}
+		if expected := strings.TrimSpace(current.Campaign); expected != "" && manifestCampaign != expected {
+			return fmt.Errorf("manifest campaign %q does not match discovered campaign %q", manifestCampaign, expected)
+		}
+		if expected := strings.TrimSpace(current.RunID); expected != "" && strings.TrimSpace(m.RunID) != expected {
+			return fmt.Errorf("manifest run_id %q does not match discovered run_id %q", strings.TrimSpace(m.RunID), expected)
+		}
+	}
+	return nil
+}
+
+func rebaseRestoredManifestPaths(cfg *config.Config, m *manifest.Manifest, destinationRoot string) error {
+	if cfg == nil || cfg.Pipeline == nil || m == nil {
+		return fmt.Errorf("resolved config and manifest are required")
+	}
+	destinationRoot = filepath.Clean(strings.TrimSpace(destinationRoot))
+	if destinationRoot == "" || destinationRoot == "." {
+		return fmt.Errorf("restored manifest destination root is required")
+	}
+	producerRoot, hasProducerRoot := restoredManifestSessionRoot(m)
+	rebase := func(field, value string) (string, error) {
+		return rebaseRestoredLocalReference(field, value, producerRoot, hasProducerRoot, destinationRoot)
+	}
+
+	for i := range m.Inputs {
+		value, err := rebase("inputs.path", m.Inputs[i].Path)
+		if err != nil {
+			return err
+		}
+		m.Inputs[i].Path = value
+		// Spool and cache locations are host-local implementation details. They
+		// are deliberately not authoritative after a restore.
+		m.Inputs[i].SpoolPath = ""
+		m.Inputs[i].CachePath = ""
+	}
+	for i := range m.Artifacts {
+		value, err := rebase("artifacts.local_path", m.Artifacts[i].LocalPath)
+		if err != nil {
+			return err
+		}
+		m.Artifacts[i].LocalPath = value
+	}
+	for stageName, record := range m.Stages {
+		if record == nil {
+			continue
+		}
+		for i := range record.Outputs {
+			value, err := rebase("stages."+stageName+".outputs.local_path", record.Outputs[i].LocalPath)
+			if err != nil {
+				return err
+			}
+			record.Outputs[i].LocalPath = value
+		}
+		// Logs and generated configuration files are invocation-local diagnostics,
+		// not restored artifacts. Dropping them prevents a producer-machine path
+		// from becoming a usable local reference.
+		record.Logs = nil
+		record.GeneratedConfigs = nil
+	}
+
+	if runID := strings.TrimSpace(m.RunID); runID != "" {
+		m.LocalWorkDir = filepath.Join(destinationRoot, config.PathRunsDirSegment, runID)
+	} else {
+		m.LocalWorkDir = destinationRoot
+	}
+	m.LocalSpoolDir = ""
+	// A post-publish cleanup record is authority to delete producer-local
+	// directories. It must never cross a restore boundary.
+	m.PostPublishCleanup = nil
+	return nil
+}
+
+func restoredManifestSessionRoot(m *manifest.Manifest) (string, bool) {
+	if m == nil {
+		return "", false
+	}
+	runRoot := portableCleanPath(m.LocalWorkDir)
+	runID := strings.TrimSpace(m.RunID)
+	if !portableAbsolutePath(runRoot) || runID == "" || path.Base(runRoot) != runID {
+		return "", false
+	}
+	runsDir := path.Dir(runRoot)
+	if path.Base(runsDir) != config.PathRunsDirSegment {
+		return "", false
+	}
+	return path.Dir(runsDir), true
+}
+
+func rebaseRestoredLocalReference(field, value, producerRoot string, hasProducerRoot bool, destinationRoot string) (string, error) {
+	value = strings.TrimSpace(value)
+	if value == "" {
+		return "", nil
+	}
+	if portableDrivePath(value) && !portableAbsolutePath(value) {
+		return "", fmt.Errorf("%s has an unsafe relative path %q", field, value)
+	}
+	if portableAbsolutePath(value) {
+		if !hasProducerRoot {
+			return "", fmt.Errorf("%s has an absolute path without a producer session root", field)
+		}
+		relative, ok := portableRelativeWithinRoot(producerRoot, value)
+		if !ok || relative == "" {
+			return "", fmt.Errorf("%s absolute path is outside the producer session root", field)
+		}
+		resolved, err := joinWithinSessionRoot(destinationRoot, relative)
+		if err != nil {
+			return "", fmt.Errorf("%s: %w", field, err)
+		}
+		return resolved, nil
+	}
+	resolved, err := joinWithinSessionRoot(destinationRoot, strings.ReplaceAll(value, "\\", "/"))
+	if err != nil {
+		return "", fmt.Errorf("%s has an unsafe relative path: %w", field, err)
+	}
+	return resolved, nil
+}
+
+func portableRelativeWithinRoot(root, candidate string) (string, bool) {
+	root = strings.TrimSuffix(portableCleanPath(root), "/")
+	candidate = portableCleanPath(candidate)
+	if root == "" || candidate == "" {
+		return "", false
+	}
+	compareRoot, compareCandidate := root, candidate
+	if portableDrivePath(root) || portableDrivePath(candidate) || strings.HasPrefix(root, "//") || strings.HasPrefix(candidate, "//") {
+		compareRoot = strings.ToLower(compareRoot)
+		compareCandidate = strings.ToLower(compareCandidate)
+	}
+	if compareCandidate == compareRoot {
+		return "", true
+	}
+	if !strings.HasPrefix(compareCandidate, compareRoot+"/") {
+		return "", false
+	}
+	return strings.TrimPrefix(candidate, root+"/"), true
+}
+
+func portableCleanPath(value string) string {
+	value = strings.ReplaceAll(strings.TrimSpace(value), "\\", "/")
+	if value == "" {
+		return ""
+	}
+	return path.Clean(value)
+}
+
+func portableAbsolutePath(value string) bool {
+	value = strings.TrimSpace(value)
+	return strings.HasPrefix(value, "/") || strings.HasPrefix(value, "\\") || (len(value) >= 3 && isASCIIAlpha(value[0]) && value[1] == ':' && (value[2] == '/' || value[2] == '\\'))
+}
+
+func portableDrivePath(value string) bool {
+	value = strings.TrimSpace(value)
+	return len(value) >= 2 && isASCIIAlpha(value[0]) && value[1] == ':'
+}
+
+func isASCIIAlpha(value byte) bool {
+	return (value >= 'a' && value <= 'z') || (value >= 'A' && value <= 'Z')
+}

internal/app/restore_plan.go

@@ -27,18 +27,31 @@ const (
 	RestoreActionConflict RestoreActionKind = "conflict"
 )
 
+// RestoreConflictKind identifies why a local target cannot be restored safely.
+type RestoreConflictKind string
+
+const (
+	RestoreConflictContentMismatch RestoreConflictKind = "content_mismatch"
+	RestoreConflictDirectory       RestoreConflictKind = "directory"
+	RestoreConflictNonRegular      RestoreConflictKind = "non_regular"
+)
+
 // RestoreAction is one deterministic planner action.
 type RestoreAction struct {
 	Kind              RestoreActionKind
 	RemoteKey         string
 	LocalRelativePath string
 	LocalPath         string
+	SHA256            string
+	Generation        string
 	Size              int64
 	ETag              string
 	ExistsLocal       bool
 	SameLocal         bool
 	Conflict          bool
+	ConflictKind      RestoreConflictKind
 	Reason            string
+	VerifiedContent   []byte
 }
 
 // RestorePlan is the deterministic output of restore planning.
@@ -66,55 +79,10 @@ func buildRestorePlan(ctx context.Context, cfg *config.Config, current *RemoteCu
 	if store == nil {
 		return nil, fmt.Errorf("remote object store is required")
 	}
-	prefix := normalizeRemoteKey(current.SessionPrefix)
-	if strings.TrimSpace(prefix) == "" {
-		return nil, fmt.Errorf("remote session prefix is required")
-	}
-	if !strings.HasSuffix(prefix, "/") {
-		prefix += "/"
-	}
-
 	sessionPaths := artifacts.NewLocalStore(cfg.Pipeline.Workspace.Root).SessionPathsFor(cfg.Session.Campaign, cfg.Session.SessionID)
-	objects, err := store.List(ctx, prefix)
+	actions, err := buildCurrentRestoreActions(ctx, current, store, sessionPaths, opts)
 	if err != nil {
-		return nil, fmt.Errorf("list remote session objects under %q: %w", prefix, err)
-	}
-
-	candidates := make(map[string]storage.ObjectInfo, len(objects)+1)
-	for _, obj := range objects {
-		key := normalizeRemoteKey(obj.Key)
-		if key == "" {
-			continue
-		}
-		obj.Key = key
-		candidates[key] = obj
-	}
-	if strings.TrimSpace(current.CurrentManifestKey) != "" {
-		key := normalizeRemoteKey(current.CurrentManifestKey)
-		if _, ok := candidates[key]; !ok {
-			candidates[key] = storage.ObjectInfo{Key: key}
-		}
-	}
-
-	actions := make([]RestoreAction, 0, len(candidates))
-	for key, obj := range candidates {
-		rel, include, err := restoreLocalRelativePathForKey(prefix, normalizeRemoteKey(current.CurrentManifestKey), key, opts.IncludeAudio)
-		if err != nil {
-			return nil, fmt.Errorf("map remote key %q: %w", key, err)
-		}
-		if !include {
-			continue
-		}
-		localPath, err := joinWithinSessionRoot(sessionPaths.Root, rel)
-		if err != nil {
-			return nil, fmt.Errorf("map remote key %q: %w", key, err)
-		}
-
-		action, err := classifyRestoreAction(ctx, store, obj, rel, localPath, opts.Force)
-		if err != nil {
-			return nil, fmt.Errorf("classify remote key %q: %w", key, err)
-		}
-		actions = append(actions, action)
+		return nil, err
 	}
 
 	previousActions, err := buildPreviousCacheRestoreActions(ctx, cfg, sessionPaths, store, opts.Force)
@@ -146,6 +114,141 @@ func buildRestorePlan(ctx context.Context, cfg *config.Config, current *RemoteCu
 	return plan, nil
 }
 
+func buildCurrentRestoreActions(
+	ctx context.Context,
+	current *RemoteCurrentState,
+	store storage.ObjectStore,
+	sessionPaths artifacts.SessionPaths,
+	opts RestorePlanOptions,
+) ([]RestoreAction, error) {
+	if current != nil && current.Commit != nil {
+		return buildCommittedRestoreActions(ctx, current, store, sessionPaths, opts)
+	}
+	return buildLegacyRestoreActions(ctx, current, store, sessionPaths, opts)
+}
+
+func buildCommittedRestoreActions(
+	ctx context.Context,
+	current *RemoteCurrentState,
+	store storage.ObjectStore,
+	sessionPaths artifacts.SessionPaths,
+	opts RestorePlanOptions,
+) ([]RestoreAction, error) {
+	if current == nil || current.Commit == nil {
+		return nil, fmt.Errorf("committed remote current state is required")
+	}
+	runPrefix := artifacts.S3RunPrefix(current.SessionPrefix, current.RunID)
+	if runPrefix == "" {
+		return nil, fmt.Errorf("committed run prefix is required")
+	}
+	actions := make([]RestoreAction, 0, len(current.Commit.Artifacts))
+	for _, artifact := range current.Commit.Artifacts {
+		rel, include, err := restoreLocalRelativePathForCommittedArtifact(runPrefix, artifact, opts.IncludeAudio)
+		if err != nil {
+			return nil, fmt.Errorf("map committed object %q: %w", artifact.DestinationKey, err)
+		}
+		if !include {
+			continue
+		}
+		localPath, err := joinWithinSessionRoot(sessionPaths.Root, rel)
+		if err != nil {
+			return nil, fmt.Errorf("map committed object %q: %w", artifact.DestinationKey, err)
+		}
+		action, err := classifyRestoreAction(ctx, store, storage.ObjectInfo{
+			Key: artifact.DestinationKey, Size: artifact.Size, ETag: artifact.Generation,
+		}, artifact.SHA256, rel, localPath, opts.Force)
+		if err != nil {
+			return nil, fmt.Errorf("classify committed object %q: %w", artifact.DestinationKey, err)
+		}
+		if artifact.Type == artifacts.RemoteArtifactTypeSessionManifest && artifact.DestinationKey == current.CurrentManifestKey {
+			action.VerifiedContent = append([]byte(nil), current.ManifestData...)
+		}
+		actions = append(actions, action)
+	}
+	return actions, nil
+}
+
+func buildLegacyRestoreActions(
+	ctx context.Context,
+	current *RemoteCurrentState,
+	store storage.ObjectStore,
+	sessionPaths artifacts.SessionPaths,
+	opts RestorePlanOptions,
+) ([]RestoreAction, error) {
+	prefix := normalizeRemoteKey(current.SessionPrefix)
+	if strings.TrimSpace(prefix) == "" {
+		return nil, fmt.Errorf("remote session prefix is required")
+	}
+	if !strings.HasSuffix(prefix, "/") {
+		prefix += "/"
+	}
+	objects, err := store.List(ctx, prefix)
+	if err != nil {
+		return nil, fmt.Errorf("list remote session objects under %q: %w", prefix, err)
+	}
+	candidates := make(map[string]storage.ObjectInfo, len(objects)+1)
+	for _, obj := range objects {
+		key := normalizeRemoteKey(obj.Key)
+		if key != "" {
+			obj.Key = key
+			candidates[key] = obj
+		}
+	}
+	if key := normalizeRemoteKey(current.CurrentManifestKey); key != "" {
+		if _, ok := candidates[key]; !ok {
+			candidates[key] = storage.ObjectInfo{Key: key}
+		}
+	}
+	actions := make([]RestoreAction, 0, len(candidates))
+	for key, object := range candidates {
+		rel, include, err := restoreLocalRelativePathForKey(prefix, normalizeRemoteKey(current.CurrentManifestKey), key, opts.IncludeAudio)
+		if err != nil {
+			return nil, fmt.Errorf("map remote key %q: %w", key, err)
+		}
+		if !include {
+			continue
+		}
+		localPath, err := joinWithinSessionRoot(sessionPaths.Root, rel)
+		if err != nil {
+			return nil, fmt.Errorf("map remote key %q: %w", key, err)
+		}
+		action, err := classifyRestoreAction(ctx, store, object, "", rel, localPath, opts.Force)
+		if err != nil {
+			return nil, fmt.Errorf("classify remote key %q: %w", key, err)
+		}
+		actions = append(actions, action)
+	}
+	return actions, nil
+}
+
+func restoreLocalRelativePathForCommittedArtifact(runPrefix string, artifact artifacts.RemoteArtifact, includeAudio bool) (string, bool, error) {
+	if artifact.Type == artifacts.RemoteArtifactTypeSessionManifest {
+		return config.PathManifestFile, true, nil
+	}
+	if artifact.Type != artifacts.RemoteArtifactTypePublishedOutput {
+		return "", false, nil
+	}
+	key := normalizeRemoteKey(artifact.DestinationKey)
+	if !strings.HasPrefix(key, runPrefix) {
+		return "", false, fmt.Errorf("object is outside committed run prefix %q", runPrefix)
+	}
+	rel := strings.TrimPrefix(key, runPrefix)
+	cleanRel, err := pathsafe.NormalizeRelativeDestination(rel)
+	if err != nil {
+		return "", false, fmt.Errorf("committed destination is unsafe: %w", err)
+	}
+	if cleanRel == config.PathManifestFile {
+		return "", false, fmt.Errorf("published output conflicts with the session manifest path")
+	}
+	if strings.HasPrefix(cleanRel, config.PathTranscriptsSegment+"/") || strings.HasPrefix(cleanRel, config.PathArtifactsDirSegment+"/") {
+		return cleanRel, true, nil
+	}
+	if includeAudio && strings.HasPrefix(cleanRel, config.PathAudioDirSegment+"/") {
+		return cleanRel, true, nil
+	}
+	return "", false, nil
+}
+
 func normalizeRemoteKey(v string) string {
 	return strings.Trim(strings.ReplaceAll(strings.TrimSpace(v), "\\", "/"), "/")
 }
@@ -240,20 +343,27 @@ func buildPreviousCacheRestoreActions(
 	if cfg == nil || cfg.Pipeline == nil || cfg.Pipeline.Scriptorium == nil {
 		return nil, nil
 	}
-	requirements := artifacts.CollectPreviousArtifactRequirements(cfg.Pipeline.Scriptorium.Artifacts)
+	effective, err := resolveEffectiveArtifacts(cfg, nil)
+	if err != nil {
+		return nil, err
+	}
+	requirements := artifacts.CollectPreviousArtifactRequirements(cfg.Pipeline.Scriptorium.Artifacts, effective)
 	if len(requirements) == 0 {
 		return nil, nil
 	}
-	plan, err := previouscache.BuildPlan(ctx, cfg, sessionPaths, requirements, store)
+	plan, err := previouscache.Resolve(ctx, cfg, sessionPaths, requirements, store)
 	if err != nil {
 		return nil, fmt.Errorf("plan previous-session cache restore: %w", err)
 	}
 	actions := make([]RestoreAction, 0, len(plan.Records))
 	for _, record := range plan.Records {
-		action, err := classifyRestoreAction(ctx, store, storage.ObjectInfo{Key: record.RemoteKey}, record.LocalRelativePath, record.LocalPath, force)
+		action, err := classifyRestoreAction(ctx, store, storage.ObjectInfo{
+			Key: record.RemoteKey, Size: record.Size, ETag: record.Generation,
+		}, record.SHA256, record.LocalRelativePath, record.LocalPath, force)
 		if err != nil {
 			return nil, fmt.Errorf("classify previous-session cache object %q: %w", record.RemoteKey, err)
 		}
+		action.VerifiedContent = append([]byte(nil), record.VerifiedContent...)
 		actions = append(actions, action)
 	}
 	return actions, nil
@@ -263,6 +373,7 @@ func classifyRestoreAction(
 	ctx context.Context,
 	store storage.ObjectStore,
 	object storage.ObjectInfo,
+	expectedSHA256 string,
 	localRelPath string,
 	localPath string,
 	force bool,
@@ -271,9 +382,13 @@ func classifyRestoreAction(
 		RemoteKey:         normalizeRemoteKey(object.Key),
 		LocalRelativePath: localRelPath,
 		LocalPath:         localPath,
+		SHA256:            strings.TrimSpace(expectedSHA256),
 		Size:              object.Size,
 		ETag:              object.ETag,
 	}
+	if action.SHA256 != "" {
+		action.Generation = strings.TrimSpace(object.ETag)
+	}
 
 	info, err := os.Stat(localPath)
 	if err != nil {
@@ -289,36 +404,50 @@ func classifyRestoreAction(
 	if info.IsDir() {
 		action.Kind = RestoreActionConflict
 		action.Conflict = true
+		action.ConflictKind = RestoreConflictDirectory
 		action.Reason = "local path is a directory"
 		return action, nil
 	}
-
-	if restoreRelativePathIsAudio(localRelPath) {
-		if object.Size > 0 {
-			if info.Size() == object.Size {
-				action.Kind = RestoreActionSkipSame
-				action.SameLocal = true
-				action.Reason = "local audio size matches remote content"
-				return action, nil
-			}
-			if force {
-				action.Kind = RestoreActionDownload
-				action.Reason = "local audio differs (size mismatch); overwrite with --force"
-				return action, nil
-			}
-			action.Kind = RestoreActionConflict
-			action.Conflict = true
-			action.Reason = "local audio differs (size mismatch)"
+	if !info.Mode().IsRegular() {
+		action.Kind = RestoreActionConflict
+		action.Conflict = true
+		action.ConflictKind = RestoreConflictNonRegular
+		action.Reason = "local path is not a regular file"
+		return action, nil
+	}
+	if action.SHA256 != "" {
+		localDigest, err := artifacts.SHA256File(localPath)
+		if err != nil {
+			return RestoreAction{}, fmt.Errorf("checksum local file: %w", err)
+		}
+		if localDigest == action.SHA256 {
+			action.Kind = RestoreActionSkipSame
+			action.SameLocal = true
+			action.Reason = "local file matches committed content"
 			return action, nil
 		}
 		if force {
 			action.Kind = RestoreActionDownload
-			action.Reason = "local audio exists; remote size unavailable; overwrite with --force"
+			action.Reason = "local file differs from committed content; overwrite with --force"
 			return action, nil
 		}
 		action.Kind = RestoreActionConflict
 		action.Conflict = true
-		action.Reason = "local audio exists; remote size unavailable"
+		action.ConflictKind = RestoreConflictContentMismatch
+		action.Reason = "local file differs from committed content"
+		return action, nil
+	}
+
+	if restoreRelativePathIsAudio(localRelPath) {
+		if force {
+			action.Kind = RestoreActionDownload
+			action.Reason = "local audio identity requires verified replacement; overwrite with --force"
+			return action, nil
+		}
+		action.Kind = RestoreActionConflict
+		action.Conflict = true
+		action.ConflictKind = RestoreConflictContentMismatch
+		action.Reason = "local audio identity is not verified; use --force to replace it"
 		return action, nil
 	}
 
@@ -330,6 +459,7 @@ func classifyRestoreAction(
 		}
 		action.Kind = RestoreActionConflict
 		action.Conflict = true
+		action.ConflictKind = RestoreConflictContentMismatch
 		action.Reason = "local file differs (size mismatch)"
 		return action, nil
 	}
@@ -364,6 +494,7 @@ func classifyRestoreAction(
 
 	action.Kind = RestoreActionConflict
 	action.Conflict = true
+	action.ConflictKind = RestoreConflictContentMismatch
 	action.Reason = "local file differs"
 	return action, nil
 }