Remove redundant prepared input APIs

.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,13 +38,32 @@ 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.
-- Stable files (`speakers_file`, `autocorrect_file`, `glossary_file`, `players_file`, `party_file`) resolve from session overrides when provided, otherwise from campaign defaults.
+- Required stable files (`speakers_file`, `autocorrect_file`, `glossary_file`,
+  `players_file`, `party_file`) and the optional `spell_catalog_file` resolve
+  from session overrides when provided, otherwise from campaign defaults. An
+  empty or omitted session spell-catalog value inherits the campaign value.
 - Exactly one audio mode must be configured in session input:
   - local (`audio_dir` or `audio_files`), or
   - S3 (`audio_s3.prefix`).
@@ -85,7 +104,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 +160,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.backend` | string | No | `local`; supported values are `local` and `s3` (case-insensitive) |
-| `pipeline.storage.s3.bucket` | string | Conditional | required for S3 session-audio and for publish upload when backend is `s3` |
+| `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 +181,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` |
@@ -205,6 +230,7 @@ Rules:
 | `pipeline.notarius.pipeline_id` | string | Conditional | required when enabled |
 | `pipeline.notarius.timeout` | duration | No | `3h`; must be positive |
 | `pipeline.notarius.working_directory` | string | No | directory containing resolved `config_path`; relative paths resolve from the pipeline file directory |
+| `pipeline.notarius.references` | map[string]string | No | empty; maps normalized Notarius selectors to supported prepared Narratio source IDs; maximum 256 entries |
 | `pipeline.notarius.outputs` | map | Conditional | at least one entry when enabled |
 | `pipeline.render.enabled` | bool | No | `true` |
 | `pipeline.render.format` | string | No | `markdown` (only supported value) |
@@ -217,9 +243,45 @@ 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.mode` | string | No | `noop`; the only supported notification mode until a provider is implemented |
-| `pipeline.notification.recipient` | string | No | empty |
+
-| `pipeline.notification.timeout` | duration | No | empty |
+### Notarius Reference Bindings
+
+`pipeline.notarius.references` maps a Notarius CLI selector to a prepared
+Narratio source, not to a filesystem path:
+
+```yaml
+notarius:
+  references:
+    glossary: narratio.input.glossary
+    party: narratio.input.party
+    players: narratio.input.players
+    spell_catalog: narratio.input.spell_catalog
+```
+
+Supported sources are `narratio.input.party`, `narratio.input.players`,
+`narratio.input.glossary`, and `narratio.input.spell_catalog`. Each map entry is
+required by its presence: omit a binding when the selected Notarius pipeline
+does not need it. A spell-catalog binding additionally requires an effective
+campaign or session `spell_catalog_file`.
+
+Selectors accept Notarius's `slot`, `chunk.slot`, `lane.slot`,
+`lane.extract.slot`, `lane.merge.slot`, and `lane.normalize.slot` forms.
+Narratio trims whitespace around
+selectors and their dot-separated components, rejects empty components and
+`=`, rejects duplicate normalized selectors, and limits the map to 256 entries.
+It validates only selector structure and the prepared source vocabulary;
+Notarius owns target-slot declarations and media compatibility.
+
+Before extraction, Narratio resolves every binding from the current prepared
+session manifest and streams it into a verified invocation-local snapshot whose
+absolute path is passed to Notarius. Missing, unsafe, empty,
+changed-during-copy, or checksum-inconsistent prepared evidence fails with
+guidance to force `prepare`. Bindings are sorted by normalized selector and are
+part of extraction fingerprint and resume identity. See the
+[Notarius integration contract](./integrations/notarius.md) for the subprocess
+boundary and the [complete example](../examples/pipeline.full.annotated.yml)
+for a copyable configuration.
 
 ### Notarius Output Entries
 
@@ -259,34 +321,54 @@ 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 |
 | `inputs.glossary_file` | string | Yes | stable input default |
 | `inputs.players_file` | string | Yes | stable input default |
 | `inputs.party_file` | string | Yes | stable input default |
+| `inputs.spell_catalog_file` | string | No | optional spell-catalog overlay default; required when a Notarius reference selects `narratio.input.spell_catalog` |
 
 ### Session
 
 | Field | Type | Required in session file | Notes |
 | --- | --- | --- | --- |
-| `session_id` | string | Yes | must match CLI session target when provided |
+| `session_id` | string | Yes | opaque identity; must match CLI session target when provided |
-| `previous_session_id` | string | No | must not equal `session_id` |
+| `previous_session_id` | string | No | opaque identity; must not equal `session_id` |
-| `campaign` | string | No | filled from `campaign_id` during resolve if omitted |
+| `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 |
@@ -294,6 +376,7 @@ For each artifact input `pipeline.scriptorium.artifacts.<name>.inputs.<input_nam
 | `inputs.glossary_file` | string | No | overrides campaign stable input |
 | `inputs.players_file` | string | No | overrides campaign stable input |
 | `inputs.party_file` | string | No | overrides campaign stable input |
+| `inputs.spell_catalog_file` | string | No | overrides the optional campaign spell catalog; empty or omitted inherits the campaign value |
 | `inputs.audio_dir` | string | Conditional | local audio mode |
 | `inputs.audio_files[]` | list[string] | Conditional | local audio mode |
 | `inputs.audio_s3.prefix` | string | Conditional | S3 audio mode |
@@ -301,6 +384,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
+Use focused package tests while iterating. Every pull request and push runs the
-change affects shared contracts, application behavior, or maintained
+following repository-wide checks before it can be accepted:
-documentation examples:
 
 ```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

@@ -7,12 +7,14 @@ lanes from the final trimmed Seriatim transcript. Narratio owns invocation,
 safe bundle discovery, lane selection, and its own artifact metadata. Notarius
 owns pipeline definitions, lane schemas, the receipt, and bundle formats.
 
-Canonical Notarius references:
+Canonical Notarius v0.6.0 references:
 
-- [Subprocess consumer contract](https://gitea.maximumdirect.net/eric/notarius/src/branch/main/docs/consumers/subprocess.md)
+- [CLI reference](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.6.0/docs/cli.md)
-- [D&D pipeline and lane contracts](https://gitea.maximumdirect.net/eric/notarius/src/branch/main/docs/consumers/dnd-pipeline.md)
+- [Subprocess consumer contract](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.6.0/docs/consumers/subprocess.md)
-- [Run-result receipt](https://gitea.maximumdirect.net/eric/notarius/src/branch/main/docs/integrations/run-result.md)
+- [D&D pipeline and lane contracts](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.6.0/docs/consumers/dnd-pipeline.md)
-- [JSON output bundle](https://gitea.maximumdirect.net/eric/notarius/src/branch/main/docs/integrations/json-output.md)
+- [Run-result receipt](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.6.0/docs/integrations/run-result.md)
+- [JSON output bundle](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.6.0/docs/integrations/json-output.md)
+- [D&D spell-catalog overlay](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.6.0/docs/integrations/dnd-spell-catalog-overlays.md)
 
 The [complete Narratio example](../../examples/pipeline.full.annotated.yml)
 records the exact current constraints for all ten D&D lanes. Treat the linked
@@ -23,39 +25,77 @@ duplicate the complete schemas.
 
 When `pipeline.notarius.enabled` is true, Narratio resolves the executable,
 configuration path, input path, output directory, and working directory to
-absolute paths and invokes:
+absolute paths. Narratio requires the Notarius v0.6.0 CLI contract when
+references are configured and invokes each binding as a separate argument
+before `--json`:
 
 ```text
-notarius run <pipeline_id> --config <config_path> --input <trimmed_json> --output-dir <staging_dir> --json
+notarius run <pipeline_id> --config <config_path> --input <trimmed_json> --output-dir <staging_dir> [--reference <selector>=<verified_snapshot_path>]... --json
 ```
 
+Reference paths are absolute invocation-local snapshots streamed from the
+manifest-verified canonical files prepared inside the current Narratio session
+workspace. Narratio verifies snapshot checksum and size before and after the
+subprocess, and passes only configured bindings, ordered lexically by normalized
+selector, as direct argument-vector entries without shell interpretation. A CLI
+binding takes precedence over a matching external path in Notarius
+configuration. Narratio never emits `--without-reference`.
+
+The maintained D&D boundary binds only the four campaign-owned external slots:
+
+```text
+notarius run dnd-session \
+  --config <absolute config path> \
+  --input <absolute trimmed transcript path> \
+  --output-dir <absolute staging directory> \
+  --reference glossary=<absolute verified glossary snapshot> \
+  --reference party=<absolute verified party snapshot> \
+  --reference players=<absolute verified players snapshot> \
+  --reference spell_catalog=<absolute verified spell catalog snapshot> \
+  --json
+```
+
+The spell-catalog binding is omitted when the campaign does not maintain that
+optional overlay. Registry, scene-description, combat-turn, and occurrence
+handoffs generated during the same Notarius run remain in Notarius pipeline
+composition and must not be emitted as CLI references. The linked CLI and D&D
+consumer documents own selector targeting, declared slots, media compatibility,
+and generated-handoff collision rules.
+
 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
+automatically; the configured working directory and Narratio's minimal child
-apply to the subprocess.
+environment apply to the subprocess.
 
 ## Accepted Result
 
-Narratio currently accepts receipt schema `notarius.run-result.v1`. The receipt
+Narratio's supported invocation baseline is Notarius v0.6.0. The accepted
+receipt remains `notarius.run-result.v2`; reference flags do not change the
+receipt or ten-lane output contract. The receipt
 must identify the configured pipeline, and its `index_file` must be exactly
 `index.json` beneath the reported bundle root. The production index must name
-the management files exactly as `manifest.json`, `rejected.json`, and
+the management files exactly as `manifest.json`, `rejected.json`,
-`warnings.json`. All receipt, index, and lane paths must stay inside that
+`warnings.json`, and `diagnostics.json`. All receipt, index, and lane paths must
-bundle; symlinks and non-regular lane payloads are rejected.
+stay inside that bundle; symlinks and non-regular lane payloads are rejected.
 
 Supported receipt and index shapes tolerate unknown fields for forward
 compatibility, while required identity, validation, count, manifest,
-rejection, warning, and lane-list fields remain mandatory. Narratio applies
+rejection, warning, diagnostic, and lane-list fields remain mandatory.
-bounded reads to the receipt, index, rejection, and warning documents. Optional
+Narratio applies bounded reads to the receipt, index, rejection, warning, and
-chunk-map and evidence-context descriptors must carry their complete generic
+diagnostic documents. Warning and diagnostic envelopes, group counts,
-contract metadata when present.
+occurrence counts, truncation state, framework-owned origins, and
+receipt-to-bundle counts must be internally consistent. Optional chunk-map and
+evidence-context descriptors must carry their complete generic contract
+metadata when present.
 
 For every entry in `pipeline.notarius.outputs`, Narratio requires exactly one
 index descriptor with the configured lane ID, media type, schema ID, schema
 version, and, when configured, module key. Missing, duplicate, rejected, or
-incompatible required lanes fail extraction even if Notarius exited zero.
+incompatible required lanes fail extraction even if Notarius exited zero. A
+configured lane whose v2 validation summary is `rejected` or `incomplete` also
+fails extraction.
 Unconfigured lanes may remain in the preserved bundle but do not become
 selectable Narratio sources.
 
@@ -72,10 +112,13 @@ only explicitly named lane sources; `--artifacts` never selects Notarius lanes.
   staged bundle is promoted to durable storage.
 - Contract and external provenance metadata are preserved on lane artifact
   records and through explicit publication.
+- Undeclared selectors, incompatible reference files, and external/generated
+  reference collisions are Notarius errors and fail extraction normally.
 
-Rejection and warning summaries retain structured stage, scope, lane, and
+Rejection, validation, warning, and diagnostic summaries retain bounded stable
-reason-code fields for diagnostics without exposing free-form external messages
+identity, category, origin, reason-code, status, and occurrence fields without
-or reading lane payload bodies.
+copying free-form external messages into Narratio manifest metadata or reading
+lane payload bodies.
 
 Configuration fields and defaults are in [Configuration](../config.md).
 Operator paths, rerun procedures, and bundle retention are in

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

@@ -46,7 +46,9 @@ Adapters do not own:
 - Object store only when required by selected stages/config.
 
 Notarius is composed only when extraction is enabled; the extract stage owns
-receipt, bundle, and configured-lane policy rather than the adapter.
+prepared reference resolution, receipt, bundle, and configured-lane policy.
+The adapter validates the ordered selector/absolute-path pairs and is the sole
+owner of serializing them as repeated `--reference` arguments before `--json`.
 
 Object-store construction goes through `newCommandObjectStore`, which loads
 configured filesystem secrets before adapter initialization.
@@ -56,6 +58,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,35 @@ 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
+All formats are validated by strict source-policy rules. Configured artifact and
-registered only from `pipeline.notarius.outputs`; the Notarius index has no
+extraction keys use `^[a-z][a-z0-9_]*$`; source parsers never normalize an
-selectable source ID.
+unrecognized token into a valid source. Extraction sources are registered only
+from `pipeline.notarius.outputs`; the Notarius index has no selectable source
+ID.
+
+Prepared stable source IDs are `narratio.input.players`,
+`narratio.input.party`, `narratio.input.glossary`, and
+`narratio.input.spell_catalog`. Artifact policy owns their canonical manifest
+kind and prepared filename vocabulary.
 
 ## 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`
@@ -61,13 +77,25 @@ Configured sources (`narratio.artifact.*`):
 
 - resolve only through runtime catalog availability.
 
+Prepared stable sources (`narratio.input.*`):
+
+- resolve only from the current manifest's exact prepared-input record;
+- require the policy-owned canonical path below the session root, a confined
+  non-symlink regular file, a non-empty payload, and a matching SHA-256
+  checksum; and
+- return an immutable source/path/checksum/size identity shared by extract and
+  analyze rather than falling back to campaign/session source paths.
+
 Extraction sources (`narratio.extraction.*`):
 
-- use the shared registration and manifest hydration path in
+- use the shared typed bundle evidence inspection in `extraction_evidence.go`;
-  `extraction_catalog.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 +104,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 +119,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 +130,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 +182,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 +211,13 @@ physical layout.
 
 - Registry and resolution: `internal/artifacts/artifact_resolver.go`,
   `internal/artifacts/catalog.go`, `internal/artifacts/transcripts.go`,
-  `internal/artifacts/extraction_catalog.go`
+  `internal/artifacts/extraction_catalog.go`,
-- Current state: `internal/artifacts/current_state.go`
+  `internal/artifacts/extraction_evidence.go`,
+  `internal/artifacts/extraction_input.go`,
+  `internal/artifacts/prepared_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
+Restore separates remote authority, local conflict policy, and filesystem
-policy, and filesystem mutation can be tested independently.
+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`
+For a non-dry-run restore, planning/classification happens only after acquiring
-when configured previous-session requirements exist.
+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
+`notify` currently has no persisted pipeline outputs and uses the explicit
-outputs; its default collaborator is a no-op sender. The focused stage
+`noop` notification mode. The focused stage documents own implementation
-documents own implementation mechanics. The
+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`
+  `narratio.input.glossary`, `narratio.input.spell_catalog`
 - configured artifacts: `narratio.artifact.<key>`
+- extraction lanes: `narratio.extraction.<key>`
 - previous-session cache: `narratio.previous_session.artifact.<key>`
 
 ## Outputs
@@ -24,12 +26,25 @@ Supported source families:
 
 ## Key Behavior
 
-- skips with metadata when Scriptorium config is missing or no executable artifacts remain.
+- when Scriptorium is absent or no configured artifact is executable, completes
-- builds runtime artifact catalog (built-ins + configured artifacts).
+  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.
-- resolves prepared stable input sources from `inputs/*.yml` materialized by `prepare`.
+- omits an unavailable optional input; an unavailable required input fails.
+- resolves prepared stable input sources through the shared manifest-authoritative
+  identity resolver; it does not accept incidental files or fall back to
+  campaign/session source paths.
 - resolves previous-session sources from local `previous/` cache only.
 - runs optional render-debug, then artifact execution.
 - validates non-empty output files and materializes canonical outputs.

docs/internal/stage-extract.md

@@ -17,21 +17,36 @@ procedures belong in [Operations](../operations.md).
 `internal/stage/extract.go`:
 
 1. resolves the final trimmed transcript from the shared artifact catalog;
-2. resolves and fingerprints the Notarius invocation contract;
+2. resolves every configured prepared reference through the shared
-3. creates a run-local staging directory and invokes the injected
+   manifest-authoritative identity resolver before creating run-local output;
+3. streams each verified reference into an invocation-local snapshot and
+   rejects any source change observed while copying;
+4. fingerprints the Notarius invocation contract, including sorted reference
+   identities;
+5. creates a run-local staging directory and invokes the injected
    `notarius.Runner`;
-4. validates the successful receipt, confined index, configured required lane
+6. revalidates the reference snapshots, then validates the v2 successful
-   descriptors, and regular payload files;
+   receipt, confined index, management documents, configured required lane
-5. atomically promotes the complete bundle to its immutable durable location;
+   descriptors, validation summaries, and regular payload files;
-6. records one non-selectable `notarius_index` output and one selectable
+7. atomically promotes the complete bundle to its immutable durable location;
+8. records one non-selectable `notarius_index` output and one selectable
    `notarius_lane` output per configured lane; and
-7. registers each lane as `narratio.extraction.<output_key>` for downstream
+9. registers each lane as `narratio.extraction.<output_key>` for downstream
    Scriptorium and publish resolution.
 
 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.
+Reference metadata contains only selector, source ID, canonical session-relative
+path, checksum, and size; adapter requests receive selector and absolute
+invocation-local snapshot path, never payload contents. Snapshot bytes must
+match the prepared identity both before and after Notarius runs, so a concurrent
+prepared-file replacement cannot make recorded provenance describe different
+bytes from those supplied to Notarius.
+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 +58,15 @@ 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, the current
+direct trimmed-transcript identity, and sorted prepared-reference identities.
+The same reference helper and transcript identity are resolved again for
+artifact evidence, so changing the current transcript bytes or producer
+identity makes the prior extraction obsolete.
+
+A valid prepared-reference change makes extraction non-resumable. Missing,
+unsafe, or checksum-inconsistent prepared evidence is a hard validation error
+with prepare-force guidance because an immediate extract rerun cannot succeed.
 
 The validator then checks the producing run identity, canonical immutable
 bundle root, path confinement and absence of symlink components, receipt
@@ -59,8 +82,10 @@ Operators must force extraction after changing any such input.
 ## Failure Behavior
 
 Adapter startup, timeout, nonzero exit, receipt decoding, path confinement,
-index compatibility, required-lane rejection, payload inspection, checksum, or
+index compatibility, inconsistent warning or diagnostic envelopes,
-promotion errors fail the stage through ordinary manifest transition handling.
+required-lane rejection or incomplete validation, payload inspection,
+checksum, or promotion errors fail the stage through ordinary manifest
+transition handling.
 Stdout receipt and stderr diagnostics remain separate. Downstream stages are
 not given selectable extraction sources unless the complete configured result
 has passed validation and promotion.

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

@@ -8,6 +8,7 @@ Materialize canonical current-session inputs before processing stages.
 
 - resolved campaign, session, and pipeline configuration
 - stable input files (`speakers`, `autocorrect`, `glossary`, `players`, `party`)
+- optional spell-catalog overlay
 - one resolved local or S3 audio source
 - enabled configured artifact input requirements for previous-session sources
 
@@ -21,6 +22,7 @@ Materialize canonical current-session inputs before processing stages.
 - `inputs/glossary.yml`
 - `inputs/players.yml`
 - `inputs/party.yml`
+- optional `inputs/spell_catalog.json`
 - `audio/*.flac`
 - optional `previous/manifest.json`
 - optional `previous/artifacts/**`
@@ -30,21 +32,29 @@ 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.
+- materializes a configured spell catalog with checksum and provenance, or
+  safely removes an obsolete canonical spell catalog and its manifest record
+  when the effective input is omitted.
 - scans enabled configured artifact inputs for `narratio.previous_session.artifact.*` requirements.
-- when previous requirements exist:
+- clears managed `previous/` state on every invocation, then, when requirements exist:
-  - clears managed `previous/` state;
+  - resolves the pointer-selected previous source through the shared resolver;
-  - builds previous-cache remote plan;
   - 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
+- immutable run-scoped commit manifest; and
-- remote current-run commit marker, written last.
+- 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
+- derives a deterministic run-archive allowlist from the validated run
-  `audio/**` and the run-local `extract/notarius-output/**` staging bundle.
+  `manifest.json`: declared run-local outputs, logs, generated configs, and the
-- keeps run-local Notarius receipt and stderr diagnostics eligible for the run
+  manifest itself. Unlisted workspace files are not archive candidates.
-  archive.
+- 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
+- remote commit and current-pointer key paths
-- `current_pointer_written`
+- the run identifier selected by the commit
 
 ## Invariants
 
-- `current/run_id.txt` is the remote commit marker and is written last.
+- `current/commit-pointer.json` is the remote commit marker and is written last.
-- run upload excludes `audio/**` and `extract/notarius-output/**`.
+- run files, selected outputs, previous-cache files, and the committed session
-- `extract/notarius.receipt.json` and `extract/notarius.stderr.log` remain
+  manifest are all declared by an immutable commit under the run prefix.
-  eligible run-record diagnostics.
+- run and previous uploads contain only manifest-declared regular files opened
-- publish locks are not overridden by `--force`.
+  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
+`internal/pathsafe` validates relative destinations. `internal/fileops` opens
-relative destinations and deletion targets.
+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`
+`artifacts.LocalStore` enforces the single-writer session lock via an
-(`ErrLockConflict` on contention).
+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;
+- is created only after a successful publish commit with complete publish
-- requires `uploaded=true` and `current_pointer_written=true` metadata;
+  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
+Manual cleanup uses the same root-confined deletion mechanism. Invocation
-deletion scope belong in [CLI](../cli.md#clean) and
+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`,
+- Workspace modes: `internal/fileops/modes.go`
-  `internal/app/post_publish_cleanup.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/fileops/directory_test.go`, `internal/fileops/modes_posix_test.go`,
-  `internal/app/cleanup_targets_test.go`,
+  `internal/fileops/cleanup_test.go`, `internal/app/cleanup_targets_test.go`,
   `internal/app/post_publish_cleanup_test.go`

docs/operations.md

@@ -36,7 +36,12 @@ narratio session init 2026-04-04 --remote --force
 
 If `campaign.yml` sets `session_template_file`, `session init` renders it. Template variables must resolve to concrete values.
 
-Campaigns must provide stable input files for speakers, autocorrect, glossary, players, and party. Session files may override those paths for one session. The `prepare` stage materializes them under `inputs/`; configured Scriptorium artifacts can reference prepared `players`, `party`, and `glossary` files with `narratio.input.players`, `narratio.input.party`, and `narratio.input.glossary`.
+Campaigns must provide stable input files for speakers, autocorrect, glossary,
+players, and party, and may provide an optional spell-catalog overlay. Session
+files may override those paths for one session. The `prepare` stage
+materializes them under `inputs/`; configured consumers use the prepared files,
+never the original campaign or session source paths. Field definitions and
+source IDs are in [Configuration](./config.md#notarius-reference-bindings).
 
 ## Standard Session Workflow
 
@@ -92,6 +97,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
@@ -127,29 +140,70 @@ The directory is immutable once promoted. Configured lanes become
 the bundle and `index.json` are retained for audit and resume validation but
 are not selectable or published implicitly.
 
+Configured Notarius references resolve only from the current manifest-backed
+prepared inputs. Their canonical locations are `inputs/party.yml`,
+`inputs/players.yml`, `inputs/glossary.yml`, and, when configured,
+`inputs/spell_catalog.json`. Extraction supplies Notarius with verified copies
+under `runs/<run_id>/extract/references/` so a concurrent refresh of canonical
+prepared files cannot change the bytes consumed by an in-flight invocation.
+Inspect the effective stable-input inventory and
+prepared-file readiness with:
+
+```bash
+narratio session status 2026-04-04
+narratio session validate 2026-04-04
+```
+
+Reference metadata records selector, source ID, session-relative path,
+checksum, and byte size, but never payload contents. Changing a prepared
+reference changes extraction identity: ordinary continuation rejects the old
+result, reruns Notarius, and marks successful downstream stages stale. If the
+prepared file is missing or inconsistent with its manifest checksum, repair
+the source configuration and refresh prepared state first:
+
+```bash
+narratio run-stage prepare 2026-04-04 --force
+```
+
 Starting a replacement clears the previous extraction payload from the current
 session-stage record. If that replacement fails or self-skips, the current
 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.
+Atomic Notarius bundle promotion is supported on Linux and macOS. On Windows
-On other operating systems, extraction fails before copying the bundle into a
+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
+The run-record upload is an allowlist derived from the validated run manifest,
-`extract/notarius-output/**` subtree. The receipt and stderr files remain
+not a workspace scan. Each declared source is opened without following
-eligible run-record diagnostics. The durable bundle is never scanned for
+symlinked ancestors or the leaf, verified as a regular file, and streamed from
-implicit publication; only lanes named by explicit `pipeline.publish.outputs`
+that verified descriptor. Unlisted files and unsafe entries are never uploaded.
-rules are 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:
 
@@ -157,11 +211,12 @@ To intentionally replace the current extraction result, run:
 narratio run-stage extract 2026-04-04 --force
 ```
 
-Narratio automatically reruns extraction when its recorded invocation contract
+Narratio automatically reruns extraction when its recorded invocation contract,
-or durable output validation changes. It cannot fingerprint configuration
+prepared Narratio reference identities, or durable output validation changes.
-files, profiles, prompts, modules, or references loaded transitively by
+It cannot fingerprint configuration files, profiles, prompts, modules, or
-Notarius. Force extraction after changing any of those inputs, even when the
+other references loaded transitively by Notarius itself. Force extraction after
-top-level Narratio and Notarius config paths remain the same. A forced extract
+changing any of those inputs, even when the top-level Narratio and Notarius
+config paths remain the same. A forced extract
 marks successful downstream stages stale. Ordinary extraction failures or
 outcome changes also stale affected downstream stages, while an identical
 repeated `notarius_disabled` self-skip does not repeatedly invalidate them.
@@ -184,13 +239,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
+- uploads configured published outputs and `previous/**` cache files into the
-  extraction lanes;
+  same immutable run scope, including only explicitly configured extraction
-- uploads `previous/**` cache files when present;
+  lanes;
-- writes `current/manifest.json`;
+- writes `{session_prefix}/runs/{run_id}/commit.json` after all declared
-- writes `current/run_id.txt` last.
+  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 +275,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 +308,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`
+- the committed session manifest and the committed transcript/artifact objects
-- `transcripts/**`
+  declared by the selected remote commit
-- `artifacts/**`
 - `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 +372,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 +429,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
+only after Narratio has successfully uploaded its immutable run-scoped objects,
-outputs, `current/manifest.json`, and finally `current/run_id.txt`.
+the immutable commit manifest, and finally the current commit pointer.
 
-`current/run_id.txt` is the commit marker and must be written last. Failed,
+`current/commit-pointer.json` is the sole mutable selector and must be written
-incomplete, skipped, or uncommitted publish attempts must not be presented as
+exactly once, last. Failed, incomplete, skipped, or uncommitted publish attempts
-current remote state. Publish locks remain authoritative and are not bypassed by
+must not be presented as current remote state. Publish locks remain authoritative
-a forced run.
+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
+Narratio distinguishes ordinary workspace data from credentials. Campaign and
-artifacts, reports, logs, manifests, and diagnostic files are potentially
+session material—including manifests, transcripts, prompts, generated
-sensitive.
+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/roadmap/notarius-v0.6-cli-references.md

@@ -0,0 +1,274 @@
+# Notarius v0.6 CLI Reference Integration
+
+## Status
+
+Accepted target state. Delivery sequencing and implementation status are owned
+by [implementation.md](implementation.md).
+
+## Purpose
+
+Upgrade Narratio's extraction boundary to the Notarius v0.6.0 subprocess
+contract and supply session reference documents explicitly with repeatable
+`--reference selector=path` arguments.
+
+The maintained D&D integration must make the prepared party roster, player
+context, glossary, and optional spell catalog available to every compatible
+Notarius target. Notarius must continue to own pipeline topology, reference-slot
+compatibility, generated artifact handoffs, prompts, and D&D schemas. Narratio
+owns selection and preparation of its external reference files, exact CLI
+invocation, provenance, and extraction reuse correctness.
+
+## Current State And Gap
+
+Narratio currently invokes Notarius as:
+
+```text
+notarius run <pipeline_id> --config <config_path> --input <transcript> --output-dir <staging_dir> --json
+```
+
+The `prepare` stage already materializes campaign/session party, players, and
+glossary files under the session `inputs/` directory, but `extract` does not
+pass them to Notarius. Narratio also has no stable spell-catalog input. As a
+result, a Notarius deployment must duplicate these paths in its own
+configuration, cannot reliably receive session overrides, and may extract
+without the same campaign context supplied to Narratio's analysis stage.
+
+Notarius v0.6.0 makes an unqualified CLI selector pipeline-scoped. For example,
+`--reference party=/absolute/path/party.yml` supplies the file to every
+selected target that declares `party`. Scoped selectors remain available for
+exceptional overrides. CLI paths are resolved from the Notarius process working
+directory, so subprocess callers are expected to provide absolute paths.
+
+The v0.6.0 receipt, index, warning, diagnostic, and ten-lane D&D artifact
+contracts remain compatible with Narratio's current v0.5 integration. This
+feature changes the invocation and input-provenance contract rather than the
+accepted output inventory.
+
+## User Outcome
+
+With the maintained complete D&D configuration, an operator can declare the
+campaign reference sources once in Narratio. For each extraction Narratio will:
+
+1. materialize the effective campaign/session files during `prepare`;
+2. resolve those prepared files by stable Narratio source ID;
+3. pass absolute paths for `party`, `players`, `glossary`, and, when configured,
+   `spell_catalog` to Notarius through repeatable CLI arguments;
+4. fail before launching Notarius when a configured reference is unavailable;
+5. rerun extraction when a selector, source binding, or reference file changes;
+   and
+6. retain bounded reference identities and checksums for diagnosis and
+   provenance without copying reference contents into manifest metadata.
+
+Session-level stable-input overrides must flow through the same mechanism. A
+custom Notarius pipeline may bind different external slots without requiring a
+Narratio code change.
+
+## Chosen Architecture
+
+### Explicit Reference Bindings
+
+Extend `pipeline.notarius` with an explicit map from a Notarius CLI selector to
+a prepared Narratio input source:
+
+```yaml
+notarius:
+  enabled: true
+  binary: notarius
+  config_path: /usr/local/etc/notarius/config.yml
+  pipeline_id: dnd-session
+  working_directory: /usr/local/etc/notarius
+  references:
+    party: narratio.input.party
+    players: narratio.input.players
+    glossary: narratio.input.glossary
+    spell_catalog: narratio.input.spell_catalog
+  outputs:
+    # Existing required lane contracts remain unchanged.
+```
+
+Each configured binding is required. An operator who does not maintain an
+optional Notarius reference, such as a spell catalog, omits that binding. This
+keeps missing-input behavior explicit and avoids a second required/optional
+policy inside each entry.
+
+The maintained complete D&D example will show all four external reference
+slots. The three existing campaign context bindings use the canonical `party`,
+`players`, and `glossary` spellings. Narratio will not emit the deprecated
+`roster` alias.
+
+The binding is deliberately source-based rather than path-based. Pipeline
+configuration should not reconstruct session workspace paths or bypass
+`prepare`; it names the stable input whose effective campaign/session value is
+already owned by Narratio. The map also avoids hard-coded behavior keyed to the
+literal `dnd-session` pipeline ID, preserving custom-pipeline support.
+
+Narratio accepts the selector forms published by Notarius v0.6.0:
+
+- `slot`;
+- `chunk.slot`;
+- `lane.slot`; and
+- `lane.extract.slot`, `lane.merge.slot`, or `lane.normalize.slot`.
+
+Configuration validation will reject empty or structurally invalid selectors,
+selectors containing `=`, unsupported source IDs, and duplicate YAML keys.
+Notarius remains authoritative for whether a selected target actually declares
+the slot and whether a file satisfies that slot's media type and size contract.
+Narratio will not duplicate the Notarius module registry.
+
+### Stable Reference Inputs
+
+Continue to use the existing prepared sources and canonical files:
+
+| Narratio source | Prepared file | Notarius slot |
+| --- | --- | --- |
+| `narratio.input.party` | `inputs/party.yml` | `party` |
+| `narratio.input.players` | `inputs/players.yml` | `players` |
+| `narratio.input.glossary` | `inputs/glossary.yml` | `glossary` |
+| `narratio.input.spell_catalog` | `inputs/spell_catalog.json` | `spell_catalog` |
+
+Add optional `spell_catalog_file` fields to campaign and session inputs, with
+the existing campaign-default/session-override resolution behavior. When
+provided, `prepare` copies it into the session input area and records its
+origin and checksum consistently with the other stable inputs. The prepared
+filename remains JSON so Notarius can apply its published spell-catalog media
+contract.
+
+The new source must be added everywhere stable inputs are enumerated: strict
+configuration decoding and merging, validation, prepare materialization,
+artifact policy/source descriptions, operator inspection, manifest input
+records, examples, and canonical documentation. It remains optional at the
+campaign level; a configured Notarius binding makes it mandatory for that
+extraction.
+
+Extract and analyze should use one shared prepared-input source resolver rather
+than maintain separate source-to-filename tables. The resolver must return an
+absolute, regular, non-empty file beneath the current session workspace and
+produce actionable `prepare --force` guidance when a configured source is
+missing. It must not fall back to the original campaign path after preparation.
+
+### Adapter Request And CLI Construction
+
+Extend the transport-neutral Notarius run request with an ordered collection of
+resolved reference bindings. Each binding contains only its selector and
+absolute prepared-file path. The extraction stage resolves source IDs and file
+identity; the subprocess adapter validates and serializes the request.
+
+The production command becomes:
+
+```text
+notarius run <pipeline_id>
+  --config <config_path>
+  --input <trimmed_json>
+  --output-dir <staging_dir>
+  --reference party=<absolute_prepared_party_path>
+  --reference players=<absolute_prepared_players_path>
+  --reference glossary=<absolute_prepared_glossary_path>
+  --reference spell_catalog=<absolute_prepared_spell_catalog_path>
+  --json
+```
+
+Only configured bindings are emitted. Selectors are sorted before request
+construction so argument order, tests, logs, and fingerprints are deterministic.
+Arguments are passed directly to the subprocess without shell interpretation;
+paths containing spaces or platform-specific separators remain one argument.
+
+CLI bindings intentionally override matching external paths in the deployed
+Notarius configuration. Narratio must not pass `--without-reference` and must
+not synthesize CLI bindings for `location_registry`, `item_registry`,
+`npc_registry`, `scene_descriptions`, `combat_turns`, or `npc_occurrences`.
+Those are generated same-run artifact handoffs in the complete D&D pipeline and
+remain entirely under Notarius configuration and execution control. A custom
+configuration that collides an external CLI binding with a generated handoff is
+expected to fail with Notarius's normal resolution error.
+
+### Fingerprints, Resume, And Provenance
+
+Reference identity is part of the extraction input contract. The extraction
+fingerprint and resume validator must include, in deterministic selector order:
+
+- the selector;
+- the configured Narratio source ID;
+- the resolved prepared path identity; and
+- the prepared file's content checksum and size.
+
+This is required even though Notarius generates a prompt session ID from the
+input module and transcript bytes: Notarius intentionally does not include
+references in that identifier. Narratio must therefore prevent an old
+extraction from being reused after a roster, player list, glossary, spell
+catalog, selector, or source mapping changes.
+
+A changed reference makes the prior `extract` result non-reusable and follows
+Narratio's normal downstream invalidation rules. A failed reference-resolution
+or checksum check also prevents reuse; it must not silently accept the prior
+bundle.
+
+Successful extract metadata should record a bounded, deterministic list of
+selector, source ID, workspace-relative path, checksum, and size. It must not
+record reference contents, original absolute operator paths, or values from the
+files. Existing receipt and bundle provenance behavior remains unchanged.
+
+### Error And Compatibility Behavior
+
+Narratio's documented minimum supported Notarius version becomes v0.6.0 for an
+enabled reference binding. Compatibility remains contract-based rather than
+dependent on parsing `notarius --version`: an older or incompatible executable
+will fail at the CLI boundary with captured diagnostics.
+
+Errors must identify the responsible selector and Narratio source without
+including file contents. Configuration errors are reported before pipeline
+execution. Missing, empty, non-regular, unsafe, or unreadable prepared files
+fail extraction before the Notarius subprocess starts. Notarius continues to
+report undeclared slots, media incompatibility, size limits, required-slot
+failures, and generated-handoff collisions.
+
+When Notarius is disabled, extraction retains its current explicit skip
+behavior and does not resolve reference inputs. Receipt v2 ingestion, bundle
+confinement, ten-lane selection, and downstream artifact source IDs are not
+otherwise changed by this feature.
+
+## Target End State
+
+Narratio and Notarius have a clear orchestration boundary:
+
+- `prepare` owns the effective, immutable session copies of external campaign
+  context;
+- `extract` maps configured stable source IDs to Notarius v0.6 CLI selectors,
+  supplies absolute file paths, and owns reuse/provenance policy;
+- the Notarius adapter owns exact subprocess serialization and supported result
+  decoding;
+- Notarius owns slot compatibility, reference precedence within its pipeline,
+  generated artifact handoffs, and output schemas; and
+- `analyze` consumes the resulting ten structured lane artifacts exactly as it
+  does today.
+
+The maintained complete D&D workflow passes party, players, glossary, and spell
+catalog context from the same prepared session inputs used elsewhere in
+Narratio. Updating any of those documents deterministically causes fresh
+extraction, and operators can diagnose the effective bindings without exposing
+file contents.
+
+## Out Of Scope
+
+- Reproducing Notarius pipeline, lane, binding, or media-type validation in
+  Narratio.
+- Passing or overriding Notarius generated artifact handoffs.
+- Adding `--without-reference`, Notarius resume/recompute controls, lane
+  selection, model selection, profile selection, or session-ID overrides.
+- Changing the ten accepted D&D lane contracts or the Scriptorium analysis
+  design.
+- Reading reference payloads into Narratio manifests or logs.
+- Automatically running `notarius config validate` for every session.
+
+## Settled Policy Choices
+
+The implementation must preserve these choices unless implementation evidence
+shows a contract conflict:
+
+- explicit selector-to-source mappings are preferred over pipeline-ID-specific
+  defaults;
+- every configured mapping is required;
+- `spell_catalog_file` is optional until a mapping requests its prepared
+  source;
+- the complete D&D example demonstrates all four external references; and
+- Notarius v0.6.0 is the minimum supported CLI contract for reference-enabled
+  extraction.

docs/troubleshooting.md

@@ -158,6 +158,66 @@ is expected audit state, not a signal to relink the old bundle manually.
 
 Relevant reference: [Operations: Extraction Workflow](./operations.md#extraction-workflow).
 
+## Prepared Notarius reference missing or inconsistent
+
+Symptom:
+
+- extraction or resume validation reports that a configured reference source is
+  unavailable, unsafe, empty, or checksum-inconsistent and recommends
+  `prepare --force`.
+
+Likely causes:
+
+- `prepare` has not run since the campaign/session stable input changed;
+- the configured source file is missing;
+- a prepared `inputs/` file or its manifest record was modified independently;
+- a spell-catalog binding exists without an effective `spell_catalog_file`.
+
+Diagnostics:
+
+```bash
+narratio session status 2026-04-04
+narratio session validate 2026-04-04
+```
+
+Safe fix:
+
+- correct the campaign/session input path, then refresh canonical prepared
+  evidence before extraction:
+
+```bash
+narratio run-stage prepare 2026-04-04 --force
+```
+
+Do not point Notarius directly at the original source path or edit the manifest
+checksum. Relevant references: [Notarius reference configuration](./config.md#notarius-reference-bindings)
+and [Operations: Extraction Workflow](./operations.md#extraction-workflow).
+
+## Notarius reference selector or generated-handoff collision
+
+Symptom:
+
+- Notarius exits nonzero with an undeclared reference-slot, incompatible media,
+  or external/generated reference collision error.
+
+Likely causes:
+
+- a selector does not identify a slot declared by the selected Notarius target;
+- a prepared file does not satisfy that slot's Notarius media contract; or
+- a CLI binding attempts to replace a same-run generated D&D handoff.
+
+Safe fix:
+
+- compare external bindings with the selected Notarius pipeline's canonical
+  consumer documentation;
+- keep only campaign-owned external slots on the CLI; and
+- leave registry, scene, combat, and occurrence handoffs to Notarius pipeline
+  composition.
+
+Narratio validates selector structure and prepared evidence, while Notarius
+owns slot declarations, media compatibility, and generated-handoff conflicts.
+Relevant reference: [Notarius integration](./integrations/notarius.md).
+
 ## Atomic Notarius promotion unsupported
 
 Symptom:
@@ -198,7 +258,7 @@ Safe fix:
 
 - compare installed Notarius output with the canonical Notarius contracts,
   including receipt `index_file: index.json` and index management names
-  `manifest.json`, `rejected.json`, and `warnings.json`; align
+  `manifest.json`, `rejected.json`, `warnings.json`, and `diagnostics.json`; align
   `pipeline.notarius` constraints and rerun. Do not bypass confinement or schema
   checks.
 
@@ -230,6 +290,8 @@ Likely causes:
 
 - the executable/config path, pipeline ID, timeout, working directory, or
   configured output contracts changed;
+- a configured prepared reference selector, source, path, checksum, or byte
+  size changed;
 - the durable bundle, index, lane set, provenance, regular-file status, or
   checksum no longer validates.
 
@@ -252,8 +314,9 @@ Safe fix:
 narratio run-stage extract 2026-04-04 --force
 ```
 
-Narratio fingerprints its invocation contract, not the contents of transitive
+Narratio fingerprints its invocation contract and prepared Narratio reference
-Notarius inputs. Always force extraction after changing them; downstream
+identities, not the contents of other transitive Notarius inputs. Always force
+extraction after changing those external inputs; downstream
 successful stages are then marked stale normally.
 
 Relevant reference: [Operations: Extraction Workflow](./operations.md#extraction-workflow).
@@ -299,7 +362,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 +374,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 +499,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/README.md

@@ -39,7 +39,9 @@ with the sample campaign and a compatible local- or S3-audio session.
   [autocorrect](campaigns/sample-campaign/autocorrect.yml),
   [glossary](campaigns/sample-campaign/glossary.yml),
   [players](campaigns/sample-campaign/players.yml), and
-  [party](campaigns/sample-campaign/party.yml) fixtures.
+  [party](campaigns/sample-campaign/party.yml) fixtures, plus an optional
+  [spell-catalog overlay](campaigns/sample-campaign/spell_catalog.json) that
+  follows the Notarius v0.6 contract.
 - [Sample speaker audio](audio/sample-speaker.flac) is a text placeholder that
   reserves the expected filename and directory shape. Replace it with a real
   FLAC file before running transcription.

examples/campaigns/sample-campaign/campaign.yml

@@ -6,3 +6,4 @@ inputs:
   glossary_file: ./glossary.yml
   players_file: ./players.yml
   party_file: ./party.yml
+  spell_catalog_file: ./spell_catalog.json

examples/campaigns/sample-campaign/spell_catalog.json

@@ -0,0 +1,18 @@
+{
+  "schema_version": "notarius.dnd.spell-catalog-overlay.v1",
+  "catalogs": [
+    {
+      "id": "narratio.sample-campaign",
+      "ruleset": "dnd-5e-2014",
+      "source": {
+        "title": "Narratio sample campaign spell names"
+      },
+      "spells": [
+        {
+          "name": "Aegis of Emberfall",
+          "aliases": ["Emberfall Aegis"]
+        }
+      ]
+    }
+  ]
+}

examples/pipeline.extraction-subset.yml

@@ -14,6 +14,11 @@ notarius:
   config_path: /usr/local/etc/notarius/config.yml
   pipeline_id: dnd-session
   timeout: 3h
+  references:
+    glossary: narratio.input.glossary
+    party: narratio.input.party
+    players: narratio.input.players
+    spell_catalog: narratio.input.spell_catalog
   outputs:
     npc_registry:
       lane_id: npc-registry
@@ -52,4 +57,3 @@ scriptorium:
         scenes:
           source: narratio.extraction.scene_descriptions
           required: true
-

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.
@@ -136,6 +136,13 @@ notarius:
   pipeline_id: dnd-session
   timeout: 3h
   working_directory: /usr/local/etc/notarius
+  # External campaign references use prepared Narratio source IDs. Omit an
+  # optional binding when the selected Notarius pipeline does not need it.
+  references:
+    glossary: narratio.input.glossary
+    party: narratio.input.party
+    players: narratio.input.players
+    spell_catalog: narratio.input.spell_catalog
   # Each key creates source narratio.extraction.<key>. These constraints match
   # the current Notarius D&D lane contracts; update them with Notarius.
   outputs:
@@ -260,7 +267,5 @@ scriptorium:
         output_kind: player_handout
 
 notification:
-  # Optional notification settings.
+  # No delivery provider is currently implemented.
-  backend: ""
+  mode: noop
-  recipient: ""
-  timeout: 30s

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
+	GeneratedConfigPath  string
-	MergedTranscriptPath     string
+	MergedTranscriptPath string
-	OutputProcessedPath      string
+	OutputProcessedPath  string
-	GlossaryPath             string
+	GlossaryPath         string
-	ReportPath               string
+	ReportPath           string
-	WorkDir                  string
+	WorkDir              string
-	Modules                  []string
+	Modules              []string
-	BaseURL                  string
+	StdoutLogPath        string
-	Model                    string
+	StderrLogPath        string
-	TranscriptDescription    string
-	ConfigPath               string
-	OutputSchema             string
-	WorkDirRetention         string
-	TotalLLMConcurrency      *int
-	ProposalLLMConcurrency   *int
-	ValidationModel          string
-	ValidationLLMConcurrency *int
-	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,
+		Executable:      r.binary,
-		Args:          args,
+		Args:            args,
-		Timeout:       r.timeout,
+		Timeout:         r.timeout,
-		EnvOverrides:  env,
+		EnvOverrides:    env,
-		StdoutLogPath: req.StdoutLogPath,
+		DiagnosticOwner: "audita",
-		StderrLogPath: req.StderrLogPath,
+		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" {
+	if rec.Env["AUDITA_INHERITED_MARKER"] != "" {
-		t.Fatalf("AUDITA_INHERITED_MARKER = %q, want inherited-from-parent", 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/fake.go

@@ -14,7 +14,9 @@ func (f *FakeRunner) Run(ctx context.Context, req RunRequest) (RunResult, error)
 	if err := ctx.Err(); err != nil {
 		return RunResult{}, err
 	}
-	f.Requests = append(f.Requests, req)
+	copyRequest := req
+	copyRequest.References = append([]ReferenceBinding(nil), req.References...)
+	f.Requests = append(f.Requests, copyRequest)
 	if f.Err != nil {
 		return RunResult{}, f.Err
 	}

internal/adapters/notarius/runner.go

@@ -6,13 +6,20 @@ import (
 	"time"
 )
 
-const ReceiptSchemaVersion = "notarius.run-result.v1"
+const ReceiptSchemaVersion = "notarius.run-result.v2"
 
 // Runner is the adapter boundary for a complete Notarius pipeline invocation.
 type Runner interface {
 	Run(ctx context.Context, req RunRequest) (RunResult, error)
 }
 
+// ReferenceBinding maps one normalized Notarius selector to an absolute
+// external reference path.
+type ReferenceBinding struct {
+	Selector string
+	Path     string
+}
+
 // RunRequest contains the resolved inputs and diagnostic destinations for one invocation.
 type RunRequest struct {
 	Binary           string
@@ -24,20 +31,41 @@ type RunRequest struct {
 	ReceiptPath      string
 	LogPath          string
 	Timeout          time.Duration
+	References       []ReferenceBinding
 }
 
 // Receipt is the transport-neutral successful run receipt.
 type Receipt struct {
-	SchemaVersion         string
+	SchemaVersion             string
-	RunID                 string
+	RunID                     string
-	PipelineID            string
+	PipelineID                string
-	OutputDirectory       string
+	OutputDirectory           string
-	IndexFile             string
+	IndexFile                 string
-	NormalizedOutputCount int
+	NormalizedOutputCount     int
-	RejectedOutputCount   int
+	RejectedOutputCount       int
-	WarningCount          int
+	WarningGroupCount         int
-	ValidationStatus      string
+	WarningOccurrenceCount    int
-	DebugDirectory        string
+	DiagnosticGroupCount      int
+	DiagnosticOccurrenceCount int
+	DiagnosticsTruncated      bool
+	ValidationStatus          string
+	ValidationSummaries       []ValidationSummary
+	DebugDirectory            string
+}
+
+// ValidationSummary retains the bounded outcome of one Notarius producer result.
+type ValidationSummary struct {
+	Stage                string
+	StepID               string
+	LaneID               string
+	ModuleKey            string
+	ChunkID              string
+	Status               string
+	RejectingValidators  []string
+	ReasonCodes          []string
+	IncompleteValidators []string
+	ProducerAttemptCount int
+	TerminalAction       string
 }
 
 // LaneDescriptor identifies one normalized lane payload discovered through the index.
@@ -72,6 +100,8 @@ type Index struct {
 	RejectedPath    string
 	WarningsFile    string
 	WarningsPath    string
+	DiagnosticsFile string
+	DiagnosticsPath string
 	Lanes           []LaneDescriptor
 	ChunkMap        *PipelineDescriptor
 	EvidenceContext *PipelineDescriptor
@@ -90,8 +120,29 @@ type RejectionSummary struct {
 
 // WarningSummary retains structured warning identity without free-form messages.
 type WarningSummary struct {
-	Scope      string
+	Disposition     string
-	ReasonCode string
+	Category        string
+	ReasonCode      string
+	Origin          DiagnosticOrigin
+	OccurrenceCount int
+}
+
+// DiagnosticOrigin identifies the framework-owned pipeline location of a finding.
+type DiagnosticOrigin struct {
+	Stage        string
+	StepID       string
+	LaneID       string
+	ModuleKey    string
+	ValidatorKey string
+}
+
+// DiagnosticSummary retains bounded advisory or observation group metadata.
+type DiagnosticSummary struct {
+	Disposition     string
+	Category        string
+	ReasonCode      string
+	Origin          DiagnosticOrigin
+	OccurrenceCount int
 }
 
 // RunResult describes a successfully decoded and validated Notarius bundle.
@@ -105,4 +156,5 @@ type RunResult struct {
 	Duration    time.Duration
 	Rejections  []RejectionSummary
 	Warnings    []WarningSummary
+	Diagnostics []DiagnosticSummary
 }

internal/adapters/notarius/subprocess.go

@@ -5,23 +5,30 @@ 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/notariusref"
 	"gitea.maximumdirect.net/eric/narratio/internal/pathsafe"
 )
 
 const (
-	maxReceiptBytes       = 1 << 20
+	maxReceiptBytes          = 1 << 20
-	maxIndexBytes         = 4 << 20
+	maxIndexBytes            = 4 << 20
-	maxSummaryBytes       = 4 << 20
+	maxSummaryBytes          = 4 << 20
-	canonicalIndexFile    = "index.json"
+	canonicalIndexFile       = "index.json"
-	canonicalManifestFile = "manifest.json"
+	canonicalManifestFile    = "manifest.json"
-	canonicalRejectedFile = "rejected.json"
+	canonicalRejectedFile    = "rejected.json"
-	canonicalWarningsFile = "warnings.json"
+	canonicalWarningsFile    = "warnings.json"
+	canonicalDiagnosticsFile = "diagnostics.json"
+	warningsSchemaVersion    = "notarius.warnings.v2"
+	diagnosticsSchemaVersion = "notarius.diagnostics.v1"
+	maxWarningGroups         = 128
+	maxDiagnosticGroups      = 256
+	maxFindingSamples        = 3
 )
 
 type subprocessRun func(context.Context, subprocess.RunRequest) (subprocess.RunResult, error)
@@ -41,7 +48,8 @@ func (r *SubprocessRunner) Run(ctx context.Context, req RunRequest) (RunResult,
 	if r == nil || r.run == nil {
 		return RunResult{}, fmt.Errorf("notarius subprocess runner is nil")
 	}
-	if err := validateRunRequest(req); err != nil {
+	references, err := validateRunRequest(req)
+	if err != nil {
 		return RunResult{}, err
 	}
 
@@ -50,15 +58,19 @@ func (r *SubprocessRunner) Run(ctx context.Context, req RunRequest) (RunResult,
 		"--config", req.ConfigPath,
 		"--input", req.InputPath,
 		"--output-dir", req.OutputRoot,
-		"--json",
 	}
+	for _, reference := range references {
+		args = append(args, "--reference", reference.Selector+"="+reference.Path)
+	}
+	args = append(args, "--json")
 	processResult, err := r.run(ctx, subprocess.RunRequest{
-		Executable:    req.Binary,
+		Executable:      req.Binary,
-		Args:          args,
+		Args:            args,
-		WorkingDir:    req.WorkingDirectory,
+		WorkingDir:      req.WorkingDirectory,
-		Timeout:       req.Timeout,
+		Timeout:         req.Timeout,
-		StdoutLogPath: req.ReceiptPath,
+		DiagnosticOwner: "notarius",
-		StderrLogPath: req.LogPath,
+		StdoutLogPath:   req.ReceiptPath,
+		StderrLogPath:   req.LogPath,
 	})
 	baseResult := RunResult{
 		ReceiptPath: req.ReceiptPath,
@@ -94,24 +106,42 @@ func (r *SubprocessRunner) Run(ctx context.Context, req RunRequest) (RunResult,
 	if err != nil {
 		return baseResult, err
 	}
+	diagnostics, diagnosticOccurrences, diagnosticsTruncated, err := loadDiagnostics(index.DiagnosticsPath)
+	if err != nil {
+		return baseResult, err
+	}
+	if receipt.NormalizedOutputCount != len(index.Lanes) || receipt.RejectedOutputCount != len(rejections) ||
+		receipt.WarningGroupCount != len(warnings) || receipt.DiagnosticGroupCount != len(diagnostics) {
+		return baseResult, fmt.Errorf("notarius receipt counts do not match published bundle")
+	}
+	warningOccurrences, err := sumWarningOccurrences(warnings)
+	if err != nil {
+		return baseResult, err
+	}
+	if receipt.WarningOccurrenceCount != warningOccurrences ||
+		receipt.DiagnosticOccurrenceCount != diagnosticOccurrences ||
+		receipt.DiagnosticsTruncated != diagnosticsTruncated {
+		return baseResult, fmt.Errorf("notarius receipt occurrence counts do not match published bundle")
+	}
 
 	baseResult.Receipt = receipt
 	baseResult.Index = index
 	baseResult.BundleRoot = bundleRoot
 	baseResult.Rejections = rejections
 	baseResult.Warnings = warnings
+	baseResult.Diagnostics = diagnostics
 	return baseResult, nil
 }
 
-func validateRunRequest(req RunRequest) error {
+func validateRunRequest(req RunRequest) ([]ReferenceBinding, error) {
 	if strings.TrimSpace(req.Binary) == "" {
-		return fmt.Errorf("notarius binary is required")
+		return nil, fmt.Errorf("notarius binary is required")
 	}
 	if strings.TrimSpace(req.PipelineID) == "" {
-		return fmt.Errorf("notarius pipeline id is required")
+		return nil, fmt.Errorf("notarius pipeline id is required")
 	}
 	if req.Timeout <= 0 {
-		return fmt.Errorf("notarius timeout must be positive")
+		return nil, fmt.Errorf("notarius timeout must be positive")
 	}
 	for label, path := range map[string]string{
 		"config":            req.ConfigPath,
@@ -122,47 +152,124 @@ func validateRunRequest(req RunRequest) error {
 		"log":               req.LogPath,
 	} {
 		if strings.TrimSpace(path) == "" {
-			return fmt.Errorf("notarius %s path is required", label)
+			return nil, fmt.Errorf("notarius %s path is required", label)
 		}
 		if !filepath.IsAbs(path) {
-			return fmt.Errorf("notarius %s path must be absolute", label)
+			return nil, fmt.Errorf("notarius %s path must be absolute", label)
 		}
 	}
 	if filepath.Clean(req.ReceiptPath) == filepath.Clean(req.LogPath) {
-		return fmt.Errorf("notarius receipt and log paths must be different")
+		return nil, fmt.Errorf("notarius receipt and log paths must be different")
+	}
+	references := make([]ReferenceBinding, 0, len(req.References))
+	selectors := make(map[string]struct{}, len(req.References))
+	for index, binding := range req.References {
+		selector, err := notariusref.NormalizeSelector(binding.Selector)
+		if err != nil {
+			return nil, fmt.Errorf("notarius reference %d selector: %w", index, err)
+		}
+		if _, duplicate := selectors[selector]; duplicate {
+			return nil, fmt.Errorf("notarius reference selector %q is duplicated", selector)
+		}
+		selectors[selector] = struct{}{}
+		if strings.TrimSpace(binding.Path) == "" {
+			return nil, fmt.Errorf("notarius reference %q path is required", selector)
+		}
+		if !filepath.IsAbs(binding.Path) {
+			return nil, fmt.Errorf("notarius reference %q path must be absolute", selector)
+		}
+		references = append(references, ReferenceBinding{Selector: selector, Path: binding.Path})
 	}
 	if err := requireRegularFile(req.ConfigPath); err != nil {
-		return fmt.Errorf("validate notarius config path: %w", err)
+		return nil, fmt.Errorf("validate notarius config path: %w", err)
 	}
 	if err := requireRegularFile(req.InputPath); err != nil {
-		return fmt.Errorf("validate notarius input path: %w", err)
+		return nil, fmt.Errorf("validate notarius input path: %w", err)
 	}
 	if err := requireDirectory(req.OutputRoot); err != nil {
-		return fmt.Errorf("validate notarius output root: %w", err)
+		return nil, fmt.Errorf("validate notarius output root: %w", err)
 	}
 	if err := requireDirectory(req.WorkingDirectory); err != nil {
-		return fmt.Errorf("validate notarius working directory: %w", err)
+		return nil, fmt.Errorf("validate notarius working directory: %w", err)
 	}
 	if err := validateLogDestination(req.ReceiptPath); err != nil {
-		return fmt.Errorf("validate notarius receipt path: %w", err)
+		return nil, fmt.Errorf("validate notarius receipt path: %w", err)
 	}
 	if err := validateLogDestination(req.LogPath); err != nil {
-		return fmt.Errorf("validate notarius log path: %w", err)
+		return nil, fmt.Errorf("validate notarius log path: %w", err)
 	}
-	return nil
+	return references, nil
 }
 
 type receiptDocument struct {
-	SchemaVersion         string `json:"schema_version"`
+	SchemaVersion             string                      `json:"schema_version"`
-	RunID                 string `json:"run_id"`
+	RunID                     string                      `json:"run_id"`
-	PipelineID            string `json:"pipeline_id"`
+	PipelineID                string                      `json:"pipeline_id"`
-	OutputDirectory       string `json:"output_directory"`
+	OutputDirectory           string                      `json:"output_directory"`
-	IndexFile             string `json:"index_file"`
+	IndexFile                 string                      `json:"index_file"`
-	NormalizedOutputCount *int   `json:"normalized_output_count"`
+	NormalizedOutputCount     *int                        `json:"normalized_output_count"`
-	RejectedOutputCount   *int   `json:"rejected_output_count"`
+	RejectedOutputCount       *int                        `json:"rejected_output_count"`
-	WarningCount          *int   `json:"warning_count"`
+	WarningGroupCount         *int                        `json:"warning_group_count"`
-	ValidationStatus      string `json:"validation_status"`
+	WarningOccurrenceCount    *int                        `json:"warning_occurrence_count"`
-	DebugDirectory        string `json:"debug_directory"`
+	DiagnosticGroupCount      *int                        `json:"diagnostic_group_count"`
+	DiagnosticOccurrenceCount *int                        `json:"diagnostic_occurrence_count"`
+	DiagnosticsTruncated      *bool                       `json:"diagnostics_truncated"`
+	ValidationStatus          string                      `json:"validation_status"`
+	ValidationSummaries       []validationSummaryDocument `json:"validation_summaries"`
+	DebugDirectory            string                      `json:"debug_directory"`
+}
+
+type validationSummaryDocument struct {
+	Stage                string   `json:"stage"`
+	StepID               string   `json:"step_id"`
+	LaneID               string   `json:"lane_id"`
+	ModuleKey            string   `json:"module_key"`
+	ChunkID              string   `json:"chunk_id"`
+	Status               string   `json:"status"`
+	RejectingValidators  []string `json:"rejecting_validators"`
+	ReasonCodes          []string `json:"reason_codes"`
+	IncompleteValidators []string `json:"incomplete_validators"`
+	ProducerAttemptCount *int     `json:"producer_attempt_count"`
+	TerminalAction       string   `json:"terminal_action"`
+}
+
+func validValidationStatus(value string) bool {
+	switch value {
+	case "approved", "rejected", "incomplete":
+		return true
+	default:
+		return false
+	}
+}
+
+func validateValidationSummaries(documents []validationSummaryDocument) ([]ValidationSummary, error) {
+	summaries := make([]ValidationSummary, 0, len(documents))
+	for _, document := range documents {
+		if document.Status != "complete" && document.Status != "rejected" && document.Status != "incomplete" {
+			return nil, fmt.Errorf("notarius validation summary status %q is invalid", document.Status)
+		}
+		if document.ProducerAttemptCount == nil || *document.ProducerAttemptCount <= 0 || !validTerminalAction(document.TerminalAction) {
+			return nil, fmt.Errorf("notarius validation summary is missing required fields")
+		}
+		summaries = append(summaries, ValidationSummary{
+			Stage: document.Stage, StepID: document.StepID, LaneID: document.LaneID,
+			ModuleKey: document.ModuleKey, ChunkID: document.ChunkID, Status: document.Status,
+			RejectingValidators:  append([]string(nil), document.RejectingValidators...),
+			ReasonCodes:          append([]string(nil), document.ReasonCodes...),
+			IncompleteValidators: append([]string(nil), document.IncompleteValidators...),
+			ProducerAttemptCount: *document.ProducerAttemptCount, TerminalAction: document.TerminalAction,
+		})
+	}
+	return summaries, nil
+}
+
+func validTerminalAction(value string) bool {
+	switch value {
+	case "accepted", "reject_output", "warn_continue", "fail_run":
+		return true
+	default:
+		return false
+	}
 }
 
 func loadReceipt(path, pipelineID string) (Receipt, error) {
@@ -176,7 +283,9 @@ func loadReceipt(path, pipelineID string) (Receipt, error) {
 	if strings.TrimSpace(document.RunID) == "" || strings.TrimSpace(document.PipelineID) == "" ||
 		strings.TrimSpace(document.OutputDirectory) == "" || strings.TrimSpace(document.ValidationStatus) == "" ||
 		document.NormalizedOutputCount == nil ||
-		document.RejectedOutputCount == nil || document.WarningCount == nil {
+		document.RejectedOutputCount == nil || document.WarningGroupCount == nil ||
+		document.WarningOccurrenceCount == nil || document.DiagnosticGroupCount == nil ||
+		document.DiagnosticOccurrenceCount == nil || document.DiagnosticsTruncated == nil {
 		return Receipt{}, fmt.Errorf("notarius receipt is missing required fields")
 	}
 	if document.IndexFile != canonicalIndexFile {
@@ -185,9 +294,18 @@ func loadReceipt(path, pipelineID string) (Receipt, error) {
 	if document.PipelineID != pipelineID {
 		return Receipt{}, fmt.Errorf("notarius receipt pipeline id %q does not match requested pipeline %q", document.PipelineID, pipelineID)
 	}
-	if *document.NormalizedOutputCount < 0 || *document.RejectedOutputCount < 0 || *document.WarningCount < 0 {
+	if *document.NormalizedOutputCount < 0 || *document.RejectedOutputCount < 0 ||
+		*document.WarningGroupCount < 0 || *document.WarningOccurrenceCount < 0 ||
+		*document.DiagnosticGroupCount < 0 || *document.DiagnosticOccurrenceCount < 0 {
 		return Receipt{}, fmt.Errorf("notarius receipt counts must be non-negative")
 	}
+	if !validValidationStatus(document.ValidationStatus) {
+		return Receipt{}, fmt.Errorf("notarius receipt validation_status %q is invalid", document.ValidationStatus)
+	}
+	validationSummaries, err := validateValidationSummaries(document.ValidationSummaries)
+	if err != nil {
+		return Receipt{}, err
+	}
 	if !filepath.IsAbs(document.OutputDirectory) {
 		return Receipt{}, fmt.Errorf("notarius receipt output directory must be absolute")
 	}
@@ -195,16 +313,21 @@ func loadReceipt(path, pipelineID string) (Receipt, error) {
 		return Receipt{}, fmt.Errorf("notarius receipt debug directory must be absolute when present")
 	}
 	return Receipt{
-		SchemaVersion:         document.SchemaVersion,
+		SchemaVersion:             document.SchemaVersion,
-		RunID:                 document.RunID,
+		RunID:                     document.RunID,
-		PipelineID:            document.PipelineID,
+		PipelineID:                document.PipelineID,
-		OutputDirectory:       filepath.Clean(document.OutputDirectory),
+		OutputDirectory:           filepath.Clean(document.OutputDirectory),
-		IndexFile:             document.IndexFile,
+		IndexFile:                 document.IndexFile,
-		NormalizedOutputCount: *document.NormalizedOutputCount,
+		NormalizedOutputCount:     *document.NormalizedOutputCount,
-		RejectedOutputCount:   *document.RejectedOutputCount,
+		RejectedOutputCount:       *document.RejectedOutputCount,
-		WarningCount:          *document.WarningCount,
+		WarningGroupCount:         *document.WarningGroupCount,
-		ValidationStatus:      document.ValidationStatus,
+		WarningOccurrenceCount:    *document.WarningOccurrenceCount,
-		DebugDirectory:        document.DebugDirectory,
+		DiagnosticGroupCount:      *document.DiagnosticGroupCount,
+		DiagnosticOccurrenceCount: *document.DiagnosticOccurrenceCount,
+		DiagnosticsTruncated:      *document.DiagnosticsTruncated,
+		ValidationStatus:          document.ValidationStatus,
+		ValidationSummaries:       validationSummaries,
+		DebugDirectory:            document.DebugDirectory,
 	}, nil
 }
 
@@ -213,6 +336,7 @@ type indexDocument struct {
 	OutputFiles     *[]laneDocument   `json:"output_files"`
 	RejectedFile    string            `json:"rejected_file"`
 	WarningsFile    string            `json:"warnings_file"`
+	DiagnosticsFile string            `json:"diagnostics_file"`
 	ChunkMap        *pipelineDocument `json:"chunk_map"`
 	EvidenceContext *pipelineDocument `json:"evidence_context"`
 }
@@ -249,6 +373,7 @@ func loadIndex(bundleRoot, indexPath string) (Index, error) {
 		{name: "manifest_file", got: document.ManifestFile, want: canonicalManifestFile},
 		{name: "rejected_file", got: document.RejectedFile, want: canonicalRejectedFile},
 		{name: "warnings_file", got: document.WarningsFile, want: canonicalWarningsFile},
+		{name: "diagnostics_file", got: document.DiagnosticsFile, want: canonicalDiagnosticsFile},
 	} {
 		if field.got != field.want {
 			return Index{}, fmt.Errorf("notarius index %s %q is incompatible; want %q", field.name, field.got, field.want)
@@ -259,10 +384,11 @@ func loadIndex(bundleRoot, indexPath string) (Index, error) {
 	}
 
 	index := Index{
-		Path:         indexPath,
+		Path:            indexPath,
-		ManifestFile: document.ManifestFile,
+		ManifestFile:    document.ManifestFile,
-		RejectedFile: document.RejectedFile,
+		RejectedFile:    document.RejectedFile,
-		WarningsFile: document.WarningsFile,
+		WarningsFile:    document.WarningsFile,
+		DiagnosticsFile: document.DiagnosticsFile,
 	}
 	var err error
 	if index.ManifestPath, err = resolveRegularFile(bundleRoot, index.ManifestFile); err != nil {
@@ -274,6 +400,9 @@ func loadIndex(bundleRoot, indexPath string) (Index, error) {
 	if index.WarningsPath, err = resolveRegularFile(bundleRoot, index.WarningsFile); err != nil {
 		return Index{}, fmt.Errorf("resolve notarius warning file: %w", err)
 	}
+	if index.DiagnosticsPath, err = resolveRegularFile(bundleRoot, index.DiagnosticsFile); err != nil {
+		return Index{}, fmt.Errorf("resolve notarius diagnostics file: %w", err)
+	}
 
 	seenLanes := make(map[string]struct{}, len(*document.OutputFiles))
 	for _, lane := range *document.OutputFiles {
@@ -361,12 +490,34 @@ func loadRejections(path string) ([]RejectionSummary, error) {
 	return summaries, nil
 }
 
-type warningDocument struct {
+type findingGroupDocument struct {
-	Warnings *[]struct {
+	Disposition     string                   `json:"disposition"`
+	Category        string                   `json:"category"`
+	ReasonCode      string                   `json:"reason_code"`
+	Origin          diagnosticOriginDocument `json:"origin"`
+	OccurrenceCount *int                     `json:"occurrence_count"`
+	Samples         *[]struct {
 		Scope      string `json:"scope"`
-		ReasonCode string `json:"reason_code"`
 		Message    string `json:"message"`
-	} `json:"warnings"`
+		ChunkID    string `json:"chunk_id"`
+		ChunkIndex *int   `json:"chunk_index"`
+	} `json:"samples"`
+	OmittedSampleCount *int `json:"omitted_sample_count"`
+}
+
+type diagnosticOriginDocument struct {
+	Stage        string `json:"stage"`
+	StepID       string `json:"step_id"`
+	LaneID       string `json:"lane_id"`
+	ModuleKey    string `json:"module_key"`
+	ValidatorKey string `json:"validator_key"`
+}
+
+type warningDocument struct {
+	SchemaVersion   string                  `json:"schema_version"`
+	GroupCount      *int                    `json:"group_count"`
+	OccurrenceCount *int                    `json:"occurrence_count"`
+	Groups          *[]findingGroupDocument `json:"groups"`
 }
 
 func loadWarnings(path string) ([]WarningSummary, error) {
@@ -374,46 +525,155 @@ func loadWarnings(path string) ([]WarningSummary, error) {
 	if err := decodeBoundedJSON(path, maxSummaryBytes, &document); err != nil {
 		return nil, fmt.Errorf("decode notarius warnings: %w", err)
 	}
-	if document.Warnings == nil {
+	if document.SchemaVersion != warningsSchemaVersion || document.GroupCount == nil ||
-		return nil, fmt.Errorf("notarius warning document is missing warnings array")
+		document.OccurrenceCount == nil || document.Groups == nil {
+		return nil, fmt.Errorf("notarius warning document is missing or incompatible required fields")
 	}
-	summaries := make([]WarningSummary, 0, len(*document.Warnings))
+	if *document.GroupCount < 0 || *document.GroupCount > maxWarningGroups || *document.OccurrenceCount < 0 ||
-	for _, item := range *document.Warnings {
+		*document.GroupCount != len(*document.Groups) {
-		if strings.TrimSpace(item.ReasonCode) == "" || strings.TrimSpace(item.Message) == "" {
+		return nil, fmt.Errorf("notarius warning document counts are inconsistent")
-			return nil, fmt.Errorf("notarius warning entries require reason_code and message")
+	}
+	summaries := make([]WarningSummary, 0, len(*document.Groups))
+	occurrences := 0
+	for _, group := range *document.Groups {
+		if err := validateFindingGroup(group); err != nil {
+			return nil, fmt.Errorf("notarius warning group: %w", err)
 		}
-		summaries = append(summaries, WarningSummary{Scope: item.Scope, ReasonCode: item.ReasonCode})
+		if group.Disposition != "warning" {
+			return nil, fmt.Errorf("notarius warning group disposition %q is invalid", group.Disposition)
+		}
+		if *group.OccurrenceCount > int(^uint(0)>>1)-occurrences {
+			return nil, fmt.Errorf("notarius warning occurrence count overflows")
+		}
+		occurrences += *group.OccurrenceCount
+		summaries = append(summaries, WarningSummary{
+			Disposition: group.Disposition, Category: group.Category, ReasonCode: group.ReasonCode,
+			Origin: diagnosticOrigin(group.Origin), OccurrenceCount: *group.OccurrenceCount,
+		})
+	}
+	if occurrences != *document.OccurrenceCount {
+		return nil, fmt.Errorf("notarius warning document occurrence count is inconsistent")
 	}
 	return summaries, nil
 }
 
+type diagnosticDocument struct {
+	SchemaVersion                string                  `json:"schema_version"`
+	GroupCount                   *int                    `json:"group_count"`
+	OccurrenceCount              *int                    `json:"occurrence_count"`
+	Truncated                    *bool                   `json:"truncated"`
+	UnrepresentedOccurrenceCount *int                    `json:"unrepresented_occurrence_count"`
+	Groups                       *[]findingGroupDocument `json:"groups"`
+}
+
+func loadDiagnostics(path string) ([]DiagnosticSummary, int, bool, error) {
+	var document diagnosticDocument
+	if err := decodeBoundedJSON(path, maxSummaryBytes, &document); err != nil {
+		return nil, 0, false, fmt.Errorf("decode notarius diagnostics: %w", err)
+	}
+	if document.SchemaVersion != diagnosticsSchemaVersion || document.GroupCount == nil ||
+		document.OccurrenceCount == nil || document.Truncated == nil ||
+		document.UnrepresentedOccurrenceCount == nil || document.Groups == nil {
+		return nil, 0, false, fmt.Errorf("notarius diagnostics document is missing or incompatible required fields")
+	}
+	if *document.GroupCount < 0 || *document.GroupCount > maxDiagnosticGroups || *document.OccurrenceCount < 0 ||
+		*document.UnrepresentedOccurrenceCount < 0 || *document.GroupCount != len(*document.Groups) {
+		return nil, 0, false, fmt.Errorf("notarius diagnostics document counts are inconsistent")
+	}
+	if !*document.Truncated && *document.UnrepresentedOccurrenceCount != 0 {
+		return nil, 0, false, fmt.Errorf("notarius diagnostics document has unrepresented occurrences without truncation")
+	}
+	summaries := make([]DiagnosticSummary, 0, len(*document.Groups))
+	representedOccurrences := 0
+	for _, group := range *document.Groups {
+		if err := validateFindingGroup(group); err != nil {
+			return nil, 0, false, fmt.Errorf("notarius diagnostic group: %w", err)
+		}
+		if group.Disposition != "advisory" && group.Disposition != "observation" {
+			return nil, 0, false, fmt.Errorf("notarius diagnostic group disposition %q is invalid", group.Disposition)
+		}
+		if *group.OccurrenceCount > int(^uint(0)>>1)-representedOccurrences {
+			return nil, 0, false, fmt.Errorf("notarius diagnostic occurrence count overflows")
+		}
+		representedOccurrences += *group.OccurrenceCount
+		summaries = append(summaries, DiagnosticSummary{
+			Disposition: group.Disposition, Category: group.Category, ReasonCode: group.ReasonCode,
+			Origin: diagnosticOrigin(group.Origin), OccurrenceCount: *group.OccurrenceCount,
+		})
+	}
+	if *document.UnrepresentedOccurrenceCount > int(^uint(0)>>1)-representedOccurrences ||
+		representedOccurrences+*document.UnrepresentedOccurrenceCount != *document.OccurrenceCount {
+		return nil, 0, false, fmt.Errorf("notarius diagnostics document occurrence count is inconsistent")
+	}
+	return summaries, *document.OccurrenceCount, *document.Truncated, nil
+}
+
+func validateFindingGroup(group findingGroupDocument) error {
+	if strings.TrimSpace(group.Disposition) == "" || strings.TrimSpace(group.Category) == "" ||
+		strings.TrimSpace(group.ReasonCode) == "" || !validDiagnosticOriginStage(group.Origin.Stage) ||
+		!validDiagnosticCategory(group.Disposition, group.Category) ||
+		group.OccurrenceCount == nil || *group.OccurrenceCount <= 0 || group.Samples == nil ||
+		group.OmittedSampleCount == nil || *group.OmittedSampleCount < 0 {
+		return fmt.Errorf("missing required fields")
+	}
+	if len(*group.Samples) == 0 || len(*group.Samples) > maxFindingSamples ||
+		*group.OmittedSampleCount != *group.OccurrenceCount-len(*group.Samples) {
+		return fmt.Errorf("sample counts are inconsistent")
+	}
+	for _, sample := range *group.Samples {
+		if strings.TrimSpace(sample.Scope) == "" || strings.TrimSpace(sample.Message) == "" ||
+			(sample.ChunkIndex != nil && *sample.ChunkIndex < 0) {
+			return fmt.Errorf("samples require scope and message")
+		}
+	}
+	return nil
+}
+
+func validDiagnosticCategory(disposition, category string) bool {
+	switch disposition {
+	case "warning":
+		return category == "configuration" || category == "degradation" ||
+			category == "validation_incomplete" || category == "fallback"
+	case "advisory":
+		return category == "data_quality"
+	case "observation":
+		return category == "normalization"
+	default:
+		return false
+	}
+}
+
+func validDiagnosticOriginStage(stage string) bool {
+	switch stage {
+	case "references", "chunk", "extract", "merge", "normalize":
+		return true
+	default:
+		return false
+	}
+}
+
+func diagnosticOrigin(document diagnosticOriginDocument) DiagnosticOrigin {
+	return DiagnosticOrigin{
+		Stage: document.Stage, StepID: document.StepID, LaneID: document.LaneID,
+		ModuleKey: document.ModuleKey, ValidatorKey: document.ValidatorKey,
+	}
+}
+
+func sumWarningOccurrences(values []WarningSummary) (int, error) {
+	total := 0
+	for _, value := range values {
+		if value.OccurrenceCount > int(^uint(0)>>1)-total {
+			return 0, fmt.Errorf("notarius warning occurrence count overflows")
+		}
+		total += value.OccurrenceCount
+	}
+	return total, nil
+}
+
 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
+		return fmt.Errorf("notarius JSON result exceeds or cannot be read within %d-byte limit: %w", limit, 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)
 	}
 	if err := json.Unmarshal(data, destination); err != nil {
 		return err

internal/adapters/notarius/subprocess_test.go

@@ -52,6 +52,10 @@ func TestSubprocessRunnerBuildsExactInvocationAndDiscoversBundle(t *testing.T) {
 	if result.Receipt.SchemaVersion != ReceiptSchemaVersion || result.Receipt.RunID != "notarius-run-1" {
 		t.Fatalf("receipt = %#v", result.Receipt)
 	}
+	if len(result.Receipt.ValidationSummaries) != 1 || result.Receipt.ValidationSummaries[0].LaneID != "npc-registry" ||
+		result.Receipt.ValidationSummaries[0].Status != "complete" {
+		t.Fatalf("validation summaries = %#v", result.Receipt.ValidationSummaries)
+	}
 	if len(result.Index.Lanes) != 1 || result.Index.Lanes[0].LaneID != "npc-registry" {
 		t.Fatalf("lanes = %#v", result.Index.Lanes)
 	}
@@ -64,12 +68,110 @@ func TestSubprocessRunnerBuildsExactInvocationAndDiscoversBundle(t *testing.T) {
 	if len(result.Rejections) != 1 || result.Rejections[0].LaneID != "spells" || result.Rejections[0].ReasonCode != "invalid_spell" {
 		t.Fatalf("rejections = %#v", result.Rejections)
 	}
-	if len(result.Warnings) != 1 || result.Warnings[0].Scope != "lane:npc-registry" || result.Warnings[0].ReasonCode != "normalized_name" {
+	if len(result.Warnings) != 1 || result.Warnings[0].Category != "degradation" || result.Warnings[0].ReasonCode != "normalized_name" {
 		t.Fatalf("warnings = %#v", result.Warnings)
 	}
+	if len(result.Diagnostics) != 1 || result.Diagnostics[0].Category != "data_quality" || result.Diagnostics[0].ReasonCode != "low_confidence" {
+		t.Fatalf("diagnostics = %#v", result.Diagnostics)
+	}
 }
 
-func TestSubprocessRunnerInheritsEnvironmentAndSeparatesStreams(t *testing.T) {
+func TestSubprocessRunnerBuildsOrderedReferenceArguments(t *testing.T) {
+	req := validRunRequest(t)
+	referenceRoot := t.TempDir()
+	req.References = []ReferenceBinding{
+		{Selector: " party ", Path: filepath.Join(referenceRoot, "party context=primary.json")},
+		{Selector: " npc-registry . extract . glossary ", Path: filepath.Join(referenceRoot, "glossary.json")},
+	}
+	originalReferences := append([]ReferenceBinding(nil), req.References...)
+	var captured sharedsubprocess.RunRequest
+	runner := &SubprocessRunner{run: func(_ context.Context, processReq sharedsubprocess.RunRequest) (sharedsubprocess.RunResult, error) {
+		captured = processReq
+		writeValidBundleAndReceipt(t, req, false)
+		return sharedsubprocess.RunResult{ExitCode: 0}, nil
+	}}
+
+	if _, err := runner.Run(context.Background(), req); err != nil {
+		t.Fatalf("Run() error = %v", err)
+	}
+	wantArgs := []string{
+		"run", req.PipelineID,
+		"--config", req.ConfigPath,
+		"--input", req.InputPath,
+		"--output-dir", req.OutputRoot,
+		"--reference", "party=" + req.References[0].Path,
+		"--reference", "npc-registry.extract.glossary=" + req.References[1].Path,
+		"--json",
+	}
+	if !reflect.DeepEqual(captured.Args, wantArgs) {
+		t.Fatalf("subprocess args = %#v, want %#v", captured.Args, wantArgs)
+	}
+	if !reflect.DeepEqual(req.References, originalReferences) {
+		t.Fatalf("Run() mutated caller references = %#v, want %#v", req.References, originalReferences)
+	}
+}
+
+func TestSubprocessRunnerRejectsInvalidReferencesBeforeLaunch(t *testing.T) {
+	tests := []struct {
+		name       string
+		references func(string) []ReferenceBinding
+		wantErr    string
+	}{
+		{
+			name: "invalid selector",
+			references: func(root string) []ReferenceBinding {
+				return []ReferenceBinding{{Selector: "lane.prepare.party", Path: filepath.Join(root, "party.json")}}
+			},
+			wantErr: "selector",
+		},
+		{
+			name: "duplicate normalized selector",
+			references: func(root string) []ReferenceBinding {
+				return []ReferenceBinding{
+					{Selector: "lane.party", Path: filepath.Join(root, "party.json")},
+					{Selector: " lane . party ", Path: filepath.Join(root, "party-2.json")},
+				}
+			},
+			wantErr: "duplicated",
+		},
+		{
+			name: "empty path",
+			references: func(string) []ReferenceBinding {
+				return []ReferenceBinding{{Selector: "party", Path: "  "}}
+			},
+			wantErr: "path is required",
+		},
+		{
+			name: "relative path",
+			references: func(string) []ReferenceBinding {
+				return []ReferenceBinding{{Selector: "party", Path: "references/party.json"}}
+			},
+			wantErr: "path must be absolute",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			req := validRunRequest(t)
+			req.References = tt.references(t.TempDir())
+			started := false
+			runner := &SubprocessRunner{run: func(context.Context, sharedsubprocess.RunRequest) (sharedsubprocess.RunResult, error) {
+				started = true
+				return sharedsubprocess.RunResult{}, nil
+			}}
+
+			_, err := runner.Run(context.Background(), req)
+			if err == nil || !strings.Contains(err.Error(), tt.wantErr) {
+				t.Fatalf("Run() error = %v, want containing %q", err, tt.wantErr)
+			}
+			if started {
+				t.Fatal("subprocess started after request validation failure")
+			}
+		})
+	}
+}
+
+func TestSubprocessRunnerUsesMinimalEnvironmentAndSeparatesStreams(t *testing.T) {
 	req := validRunRequest(t)
 	writeValidBundleAndReceipt(t, req, false)
 	receiptFixture := req.ReceiptPath + ".fixture"
@@ -103,7 +205,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 {
@@ -171,8 +273,10 @@ func TestLoadReceiptValidation(t *testing.T) {
 	valid := map[string]any{
 		"schema_version": ReceiptSchemaVersion, "run_id": "run-1", "pipeline_id": "pipeline-1",
 		"output_directory": filepath.Join(root, "outputs", "run-1"), "index_file": "index.json",
-		"normalized_output_count": 1, "rejected_output_count": 0, "warning_count": 0,
+		"normalized_output_count": 1, "rejected_output_count": 0,
-		"validation_status": "approved", "future_field": true,
+		"warning_group_count": 0, "warning_occurrence_count": 0,
+		"diagnostic_group_count": 0, "diagnostic_occurrence_count": 0,
+		"diagnostics_truncated": false, "validation_status": "approved", "future_field": true,
 	}
 	tests := []struct {
 		name      string
@@ -183,11 +287,12 @@ func TestLoadReceiptValidation(t *testing.T) {
 	}{
 		{name: "unknown fields tolerated", wantOK: true},
 		{name: "malformed", raw: []byte("{")},
-		{name: "unsupported version", mutate: func(v map[string]any) { v["schema_version"] = "notarius.run-result.v2" }},
+		{name: "unsupported version", mutate: func(v map[string]any) { v["schema_version"] = "notarius.run-result.v1" }},
 		{name: "missing field", mutate: func(v map[string]any) { delete(v, "run_id") }},
 		{name: "pipeline mismatch", mutate: func(v map[string]any) { v["pipeline_id"] = "other" }},
 		{name: "relative output", mutate: func(v map[string]any) { v["output_directory"] = "run-1" }},
-		{name: "negative count", mutate: func(v map[string]any) { v["warning_count"] = -1 }},
+		{name: "negative count", mutate: func(v map[string]any) { v["warning_group_count"] = -1 }},
+		{name: "invalid validation status", mutate: func(v map[string]any) { v["validation_status"] = "valid" }},
 		{
 			name: "nested index", mutate: func(v map[string]any) { v["index_file"] = "nested/index.json" },
 			wantError: `index_file "nested/index.json"`,
@@ -369,22 +474,26 @@ func TestLoadDiagnosticSummariesValidateBoundsAndTolerateUnknownFields(t *testin
 	root := t.TempDir()
 	rejectedPath := filepath.Join(root, "rejected.json")
 	warningsPath := filepath.Join(root, "warnings.json")
+	diagnosticsPath := filepath.Join(root, "diagnostics.json")
 	writeJSONFile(t, rejectedPath, map[string]any{"rejected": []any{map[string]any{
 		"stage": "validate", "lane_id": "spells", "reason_code": "invalid", "message": "do not retain this", "future": true,
 	}}, "future": true})
-	writeJSONFile(t, warningsPath, map[string]any{"warnings": []any{map[string]any{
+	writeJSONFile(t, warningsPath, findingEnvelope(warningsSchemaVersion, []any{findingGroup("warning", "degradation", "bounded", "normalize", 2)}, 2, false, 0))
-		"scope": "lane:spells", "reason_code": "bounded", "message": "do not retain this", "future": true,
+	writeJSONFile(t, diagnosticsPath, findingEnvelope(diagnosticsSchemaVersion, []any{findingGroup("advisory", "data_quality", "low_confidence", "normalize", 3)}, 4, true, 1))
-	}}, "future": true})
 	rejections, err := loadRejections(rejectedPath)
 	if err != nil || len(rejections) != 1 || rejections[0].ReasonCode != "invalid" {
 		t.Fatalf("loadRejections() = %#v, %v", rejections, err)
 	}
 	warnings, err := loadWarnings(warningsPath)
-	if err != nil || len(warnings) != 1 || warnings[0].Scope != "lane:spells" {
+	if err != nil || len(warnings) != 1 || warnings[0].Category != "degradation" || warnings[0].OccurrenceCount != 2 {
 		t.Fatalf("loadWarnings() = %#v, %v", warnings, err)
 	}
+	diagnostics, occurrences, truncated, err := loadDiagnostics(diagnosticsPath)
+	if err != nil || len(diagnostics) != 1 || occurrences != 4 || !truncated || diagnostics[0].Category != "data_quality" {
+		t.Fatalf("loadDiagnostics() = %#v, %d, %t, %v", diagnostics, occurrences, truncated, err)
+	}
 
-	for name, path := range map[string]string{"rejections": rejectedPath, "warnings": warningsPath} {
+	for name, path := range map[string]string{"rejections": rejectedPath, "warnings": warningsPath, "diagnostics": diagnosticsPath} {
 		t.Run("malformed "+name, func(t *testing.T) {
 			if err := os.WriteFile(path, []byte("{"), 0o644); err != nil {
 				t.Fatalf("WriteFile() error = %v", err)
@@ -392,8 +501,10 @@ func TestLoadDiagnosticSummariesValidateBoundsAndTolerateUnknownFields(t *testin
 			var err error
 			if name == "rejections" {
 				_, err = loadRejections(path)
-			} else {
+			} else if name == "warnings" {
 				_, err = loadWarnings(path)
+			} else {
+				_, _, _, err = loadDiagnostics(path)
 			}
 			if err == nil {
 				t.Fatal("summary decoder error = nil")
@@ -410,16 +521,23 @@ func TestLoadDiagnosticSummariesValidateBoundsAndTolerateUnknownFields(t *testin
 	if _, err := loadRejections(oversized); err == nil || !strings.Contains(err.Error(), "exceeds") {
 		t.Fatalf("loadRejections(oversized) error = %v", err)
 	}
+	if _, _, _, err := loadDiagnostics(oversized); err == nil || !strings.Contains(err.Error(), "exceeds") {
+		t.Fatalf("loadDiagnostics(oversized) error = %v", err)
+	}
 }
 
 func TestFakeRunnerCapturesRequestsAndHonorsContextAndError(t *testing.T) {
-	req := RunRequest{PipelineID: "pipeline"}
+	req := RunRequest{PipelineID: "pipeline", References: []ReferenceBinding{{Selector: "party", Path: "/references/party.json"}}}
 	want := RunResult{BundleRoot: "/bundle"}
 	fake := &FakeRunner{Result: want}
 	got, err := fake.Run(context.Background(), req)
 	if err != nil || !reflect.DeepEqual(got, want) || !reflect.DeepEqual(fake.Requests, []RunRequest{req}) {
 		t.Fatalf("Run() = %#v, %v; requests = %#v", got, err, fake.Requests)
 	}
+	req.References[0].Path = "/references/changed.json"
+	if fake.Requests[0].References[0].Path != "/references/party.json" {
+		t.Fatalf("fake retained aliased request references: %#v", fake.Requests[0].References)
+	}
 
 	wantErr := errors.New("configured failure")
 	fake.Err = wantErr
@@ -478,13 +596,12 @@ func writeValidBundleAndReceipt(t *testing.T, req RunRequest, includeUnknown boo
 		}
 	}
 	rejection := map[string]any{"stage": "validate", "lane_id": "spells", "reason_code": "invalid_spell", "message": strings.Repeat("external detail", 20)}
-	warning := map[string]any{"scope": "lane:npc-registry", "reason_code": "normalized_name", "message": strings.Repeat("external warning", 20)}
 	if includeUnknown {
 		rejection["future"] = true
-		warning["future"] = true
 	}
 	writeJSONFile(t, filepath.Join(bundle, "rejected.json"), map[string]any{"rejected": []any{rejection}, "future": true})
-	writeJSONFile(t, filepath.Join(bundle, "warnings.json"), map[string]any{"warnings": []any{warning}, "future": true})
+	writeJSONFile(t, filepath.Join(bundle, "warnings.json"), findingEnvelope(warningsSchemaVersion, []any{findingGroup("warning", "degradation", "normalized_name", "normalize", 2)}, 2, false, 0))
+	writeJSONFile(t, filepath.Join(bundle, "diagnostics.json"), findingEnvelope(diagnosticsSchemaVersion, []any{findingGroup("advisory", "data_quality", "low_confidence", "normalize", 3)}, 4, true, 1))
 	index := validIndexValue([]any{map[string]any{
 		"lane_id": "npc-registry", "file": "lanes/npc.json", "media_type": "application/json",
 		"module_key": "dnd/npc-registry", "schema_id": "notarius.dnd.npc_registry",
@@ -503,7 +620,13 @@ func writeValidBundleAndReceipt(t *testing.T, req RunRequest, includeUnknown boo
 	receipt := map[string]any{
 		"schema_version": ReceiptSchemaVersion, "run_id": "notarius-run-1", "pipeline_id": req.PipelineID,
 		"output_directory": bundle, "index_file": "index.json", "normalized_output_count": 1,
-		"rejected_output_count": 1, "warning_count": 1, "validation_status": "rejected",
+		"rejected_output_count": 1, "warning_group_count": 1, "warning_occurrence_count": 2,
+		"diagnostic_group_count": 1, "diagnostic_occurrence_count": 4,
+		"diagnostics_truncated": true, "validation_status": "rejected",
+		"validation_summaries": []any{map[string]any{
+			"stage": "normalize", "lane_id": "npc-registry", "status": "complete",
+			"producer_attempt_count": 1, "terminal_action": "accepted",
+		}},
 	}
 	if includeUnknown {
 		receipt["future"] = true
@@ -517,7 +640,7 @@ func createBundleSkeleton(t *testing.T) string {
 	if err := os.MkdirAll(filepath.Join(bundle, "lanes"), 0o755); err != nil {
 		t.Fatalf("MkdirAll(bundle) error = %v", err)
 	}
-	for _, name := range []string{"manifest.json", "rejected.json", "warnings.json", "lanes/npc.json", "chunk-map.json"} {
+	for _, name := range []string{"manifest.json", "rejected.json", "warnings.json", "diagnostics.json", "lanes/npc.json", "chunk-map.json"} {
 		if err := os.WriteFile(filepath.Join(bundle, filepath.FromSlash(name)), []byte("{}"), 0o644); err != nil {
 			t.Fatalf("WriteFile(%q) error = %v", name, err)
 		}
@@ -528,10 +651,31 @@ func createBundleSkeleton(t *testing.T) string {
 func validIndexValue(lanes []any) map[string]any {
 	return map[string]any{
 		"manifest_file": "manifest.json", "output_files": lanes,
-		"rejected_file": "rejected.json", "warnings_file": "warnings.json",
+		"rejected_file": "rejected.json", "warnings_file": "warnings.json", "diagnostics_file": "diagnostics.json",
 	}
 }
 
+func findingGroup(disposition, category, reasonCode, origin string, occurrences int) map[string]any {
+	return map[string]any{
+		"disposition": disposition, "category": category, "reason_code": reasonCode,
+		"origin": map[string]any{"stage": origin, "lane_id": "npc-registry"}, "occurrence_count": occurrences,
+		"samples":              []any{map[string]any{"scope": "lane:npc-registry", "message": "external detail"}},
+		"omitted_sample_count": occurrences - 1,
+	}
+}
+
+func findingEnvelope(schema string, groups []any, occurrences int, truncated bool, unrepresented int) map[string]any {
+	value := map[string]any{
+		"schema_version": schema, "group_count": len(groups), "occurrence_count": occurrences,
+		"groups": groups,
+	}
+	if schema == diagnosticsSchemaVersion {
+		value["truncated"] = truncated
+		value["unrepresented_occurrence_count"] = unrepresented
+	}
+	return value
+}
+
 func writeJSONFile(t *testing.T, path string, value any) {
 	t.Helper()
 	data, err := json.Marshal(value)

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,
+		Executable:        req.Binary,
-		Args:          args,
+		Args:              args,
-		WorkingDir:    req.WorkingDir,
+		WorkingDir:        req.WorkingDir,
-		Timeout:       req.Timeout,
+		Timeout:           req.Timeout,
-		StdoutLogPath: req.StdoutLogPath,
+		EnvOverrides:      envOverrides,
-		StderrLogPath: req.StderrLogPath,
+		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,
+		Executable:        req.Binary,
-		Args:          args,
+		Args:              args,
-		WorkingDir:    req.WorkingDir,
+		WorkingDir:        req.WorkingDir,
-		Timeout:       req.Timeout,
+		Timeout:           req.Timeout,
-		StdoutLogPath: req.StdoutLogPath,
+		EnvOverrides:      envOverrides,
-		StderrLogPath: req.StderrLogPath,
+		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() {
+	if len(data) == 0 {
-		return fmt.Errorf("path is a directory")
-	}
-	if info.Size() <= 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,
+		Executable:      r.binary,
-		Args:          args,
+		Args:            args,
-		Timeout:       r.timeout,
+		Timeout:         r.timeout,
-		EnvOverrides:  env,
+		EnvOverrides:    env,
-		StdoutLogPath: req.StdoutLogPath,
+		DiagnosticOwner: "seriatim",
-		StderrLogPath: req.StderrLogPath,
+		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,
+		Executable:      binary,
-		Args:          args,
+		Args:            args,
-		Timeout:       timeout,
+		Timeout:         timeout,
-		StdoutLogPath: req.StdoutLogPath,
+		DiagnosticOwner: "seriatim",
-		StderrLogPath: req.StderrLogPath,
+		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,
+		Executable:      binary,
-		Args:          args,
+		Args:            args,
-		Timeout:       timeout,
+		Timeout:         timeout,
-		StdoutLogPath: req.StdoutLogPath,
+		DiagnosticOwner: "seriatim",
-		StderrLogPath: req.StderrLogPath,
+		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,
+		Executable:      binary,
-		Args:          args,
+		Args:            args,
-		Timeout:       timeout,
+		Timeout:         timeout,
-		StdoutLogPath: req.StdoutLogPath,
+		DiagnosticOwner: "seriatim",
-		StderrLogPath: req.StderrLogPath,
+		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
+	ListErr      error
-	DownloadErr error
+	DownloadErr  error
-	UploadErr   error
+	UploadErr    error
-	ExistsErr   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.
+// Read returns a stable object body and the generation observed with it.
-func (f *FakeBackend) Download(ctx context.Context, key, localPath string) error {
+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 {
+	destination, err := os.Create(localPath)
-		return fmt.Errorf("download object %q: write local file: %w", key, err)
+	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)
+	f.mu.Lock()
-	return ObjectInfo{
+	f.Uploads = append(f.Uploads, call)
-		Key:          normalizedKey,
+	f.mu.Unlock()
-		Size:         int64(len(data)),
+	if f.UploadHook != nil {
-		LastModified: &now,
+		if err := f.UploadHook(call); err != nil {
-	}, 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 := b.DownloadTo(ctx, key, dst); err != nil {
-	if _, err := io.Copy(dst, resp.Body); err != nil {
+		return err
-		return fmt.Errorf("download object %q: copy body: %w", normalizedKey, 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
+	listOut     *s3.ListObjectsV2Output
-	listErr error
+	listOutputs []*s3.ListObjectsV2Output
+	listErr     error
+	listCalls   int
 
-	getBody io.ReadCloser
+	getBody         io.ReadCloser
-	getErr  error
+	getErr          error
+	getSize         *int64
+	getETag         *string
+	getLastModified *time.Time
 
 	putOut *s3.PutObjectOutput
 	putErr error
 
 	headErr error
 
-	lastList *s3.ListObjectsV2Input
+	lastList  *s3.ListObjectsV2Input
-	lastGet  *s3.GetObjectInput
+	lastLists []*s3.ListObjectsV2Input
-	lastPut  *s3.PutObjectInput
+	lastGet   *s3.GetObjectInput
-	lastHead *s3.HeadObjectInput
+	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
+	Executable        string
-	Args          []string
+	Args              []string
-	WorkingDir    string
+	WorkingDir        string
-	EnvOverrides  map[string]string
+	EnvOverrides      map[string]string
-	Timeout       time.Duration
+	SensitiveEnvNames []string
-	StdoutLogPath string
+	DiagnosticOwner   string
-	StderrLogPath 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 ctxErr == context.DeadlineExceeded {
-	if errors.Is(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")
 	}
-
+	if err := fileops.WriteFileAtomic(path, data, perm); err != nil {
-	dir := filepath.Dir(path)
+		return fmt.Errorf("write file %q: %w", path, err)
-	if err := os.MkdirAll(dir, 0o755); err != nil {
-		return fmt.Errorf("create parent directory %q: %w", dir, 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("PATH", "inherited-value")
-	t.Setenv("SUBPROCESS_HELPER_ENV_KEY", "SUBPROCESS_PARENT_VALUE")
-	t.Setenv("SUBPROCESS_PARENT_VALUE", "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,
+		Executable: exe,
-		Args:          []string{"-test.run=TestSubprocessHelper", "--", "printenv"},
+		Args:       []string{"-test.run=TestSubprocessHelper", "--", "printenv"},
-		EnvOverrides:  map[string]string{"SUBPROCESS_PARENT_VALUE": "override-value"},
+		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" {
+	requests := fake.RequestsSnapshot()
-		t.Fatalf("requests = %#v, want one alice request", fake.Requests)
+	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{}
+	upload := newMultipartUpload(ctx, audioPath, c.language, c.openAudio)
-	writer := multipart.NewWriter(bodyBuf)
+	defer upload.Close()
 
-	fileWriter, err := writer.CreateFormFile("file", filepath.Base(audioPath))
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.url.String(), upload)
-	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)
 	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 resp.StatusCode < 200 || resp.StatusCode >= 300 {
-	if err != nil {
+		_ = upload.Close()
-		return resp.StatusCode, nil, fmt.Errorf("read whisperx response body: %w", err)
+		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 {
+	if err := upload.Wait(); err != nil {
-		return resp.StatusCode, nil, fmt.Errorf("whisperx returned status %d", resp.StatusCode)
+		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 := fileops.WriteFileAtomic(path, data, perm); err != nil {
-	if err := os.MkdirAll(dir, 0o755); err != nil {
+		return fmt.Errorf("write file %q: %w", path, err)
-		return fmt.Errorf("create parent dir %q: %w", dir, 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 {
+	_, err := resolveEffectiveArtifacts(cfg, selected)
-		return nil
+	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
+	configured := artifacts.ConfiguredArtifactDefinitions(cfg.Pipeline.Scriptorium.Artifacts)
-	if len(configured) == 0 {
+	if len(selected) > 0 && len(configured) == 0 {
-		return fmt.Errorf("--artifacts requires at least one configured artifact in pipeline.scriptorium.artifacts")
+		return artifacts.EffectiveArtifactSet{}, fmt.Errorf("--artifacts requires at least one configured artifact in pipeline.scriptorium.artifacts")
 	}
-	for _, name := range selected {
+	effective, err := artifacts.ResolveEffectiveArtifactSet(configured, selected)
-		if _, ok := configured[name]; !ok {
+	if err != nil {
-			return fmt.Errorf("--artifacts includes unknown artifact %q", name)
+		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) ||
+	if err := pathsafe.ValidateOpaqueSegment(campaignID); err != nil {
-		strings.Contains(campaignID, "/") ||
+		return fmt.Errorf("campaign id %q must be a single path segment and opaque identifier: %w", campaignID, err)
-		strings.Contains(campaignID, `\`) ||
-		campaignID == "." ||
-		campaignID == ".." {
-		return fmt.Errorf("campaign id %q must be a single path segment", campaignID)
 	}
 	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") {
+	if !strings.Contains(stderr.String(), "validate secrets env_dir") {
-		t.Fatalf("stderr = %q, want secrets read-dir error context", stderr.String())
+		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

@@ -7,12 +7,14 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"sort"
 	"strings"
 	"testing"
 	"time"
 
 	"gitea.maximumdirect.net/eric/narratio/internal/adapters/notarius"
 	"gitea.maximumdirect.net/eric/narratio/internal/artifactmodel"
+	"gitea.maximumdirect.net/eric/narratio/internal/artifactpolicy"
 	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
 	"gitea.maximumdirect.net/eric/narratio/internal/config"
 	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
@@ -25,6 +27,37 @@ type materializingNotariusRunner struct {
 	failuresRemaining int
 }
 
+type assertExtractionSourcesStage struct {
+	keys []string
+	runs *int
+}
+
+func (s assertExtractionSourcesStage) Name() string { return "analyze" }
+
+func (s assertExtractionSourcesStage) Run(_ context.Context, env *stage.Env, m *manifest.Manifest) (*stage.StageResult, error) {
+	definitions := artifacts.ExtractionDefinitionsFromConfig(env.Config.Pipeline.Notarius)
+	catalog, err := artifacts.BootstrapRuntimeCatalog(nil, env.EffectiveArtifacts, definitions)
+	if err != nil {
+		return nil, err
+	}
+	paths, err := env.ArtifactStore.EnsureLayoutFor(env.Config.Session.Campaign, env.Config.Session.SessionID)
+	if err != nil {
+		return nil, err
+	}
+	catalog.HydrateExtractionArtifacts(paths, m, definitions)
+	for _, key := range s.keys {
+		sourceID := artifacts.ExtractionArtifactSourceID(key)
+		entry, ok := catalog.Lookup(sourceID)
+		if !ok || !entry.Available || entry.SourceID != sourceID || entry.Path == "" {
+			return nil, fmt.Errorf("extraction source %q unavailable: %#v, present=%v", sourceID, entry, ok)
+		}
+	}
+	if s.runs != nil {
+		*s.runs = *s.runs + 1
+	}
+	return &stage.StageResult{}, nil
+}
+
 func (r *materializingNotariusRunner) Run(_ context.Context, req notarius.RunRequest) (notarius.RunResult, error) {
 	r.requests = append(r.requests, req)
 	if r.failuresRemaining > 0 {
@@ -38,32 +71,47 @@ func (r *materializingNotariusRunner) Run(_ context.Context, req notarius.RunReq
 		return notarius.RunResult{}, err
 	}
 	for path, content := range map[string]string{
-		filepath.Join(bundle, "index.json"):    `{"manifest_file":"manifest.json"}`,
+		filepath.Join(bundle, "index.json"):       `{"manifest_file":"manifest.json"}`,
-		filepath.Join(bundle, "manifest.json"): `{}`,
+		filepath.Join(bundle, "manifest.json"):    `{}`,
-		filepath.Join(bundle, "rejected.json"): `{"rejected":[]}`,
+		filepath.Join(bundle, "rejected.json"):    `{"rejected":[]}`,
-		filepath.Join(bundle, "warnings.json"): `{"warnings":[]}`,
+		filepath.Join(bundle, "warnings.json"):    `{"schema_version":"notarius.warnings.v2","group_count":0,"occurrence_count":0,"groups":[]}`,
-		filepath.Join(lanesDir, "npcs.json"):   `{"npcs":[]}`,
+		filepath.Join(bundle, "diagnostics.json"): `{"schema_version":"notarius.diagnostics.v1","group_count":0,"occurrence_count":0,"truncated":false,"unrepresented_occurrence_count":0,"groups":[]}`,
 	} {
 		if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
 			return notarius.RunResult{}, err
 		}
 	}
-	output := r.cfg.Outputs["npc_registry"]
+	keys := make([]string, 0, len(r.cfg.Outputs))
+	for key := range r.cfg.Outputs {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+	lanes := make([]notarius.LaneDescriptor, 0, len(keys))
+	for _, key := range keys {
+		output := r.cfg.Outputs[key]
+		filename := key + ".json"
+		path := filepath.Join(lanesDir, filename)
+		if err := os.WriteFile(path, []byte(`{"records":[]}`), 0o644); err != nil {
+			return notarius.RunResult{}, err
+		}
+		lanes = append(lanes, notarius.LaneDescriptor{
+			LaneID: output.LaneID, File: filepath.ToSlash(filepath.Join("lanes", filename)), Path: path,
+			MediaType: output.MediaType, SchemaID: output.SchemaID,
+			SchemaVersion: output.SchemaVersion, ModuleKey: output.ModuleKey,
+		})
+	}
 	return notarius.RunResult{
 		Receipt: notarius.Receipt{
 			SchemaVersion: notarius.ReceiptSchemaVersion, RunID: externalRunID,
 			PipelineID: req.PipelineID, OutputDirectory: bundle, IndexFile: "index.json",
-			NormalizedOutputCount: 1, ValidationStatus: "valid",
+			NormalizedOutputCount: len(lanes), ValidationStatus: "approved",
 		},
 		BundleRoot: bundle,
 		Index: notarius.Index{
 			Path: filepath.Join(bundle, "index.json"), RejectedPath: filepath.Join(bundle, "rejected.json"),
-			WarningsPath: filepath.Join(bundle, "warnings.json"),
+			WarningsPath:    filepath.Join(bundle, "warnings.json"),
-			Lanes: []notarius.LaneDescriptor{{
+			DiagnosticsPath: filepath.Join(bundle, "diagnostics.json"),
-				LaneID: output.LaneID, File: "lanes/npcs.json", Path: filepath.Join(lanesDir, "npcs.json"),
+			Lanes:           lanes,
-				MediaType: output.MediaType, SchemaID: output.SchemaID,
-				SchemaVersion: output.SchemaVersion, ModuleKey: output.ModuleKey,
-			}},
 		},
 	}, nil
 }
@@ -100,6 +148,182 @@ func TestExtractLifecycleDisabledThenEnabled(t *testing.T) {
 	}
 }
 
+func TestExtractLifecyclePrepareBindsVerifiedReferenceSnapshots(t *testing.T) {
+	cfg, env, runner := extractionLifecycleFixture(t, true)
+	originalPaths := configureLifecycleReferences(t, cfg)
+
+	summary, err := executeStages(context.Background(), cfg, prepareExtractLifecyclePlan(t), RunOptions{Env: env})
+	if err != nil {
+		t.Fatalf("executeStages() error = %v", err)
+	}
+	if len(summary.Executed) != 2 || len(runner.requests) != 1 {
+		t.Fatalf("summary = %#v requests=%d", summary, len(runner.requests))
+	}
+	paths, err := artifacts.NewLocalStore(cfg.Pipeline.Workspace.Root).EnsureLayoutFor(cfg.Session.Campaign, cfg.Session.SessionID)
+	if err != nil {
+		t.Fatalf("EnsureLayoutFor() error = %v", err)
+	}
+	want := []struct {
+		selector string
+		sourceID string
+		filename string
+	}{
+		{selector: "glossary", sourceID: artifactpolicy.SourceInputGlossary, filename: "glossary.yml"},
+		{selector: "party", sourceID: artifactpolicy.SourceInputParty, filename: "party.yml"},
+		{selector: "players", sourceID: artifactpolicy.SourceInputPlayers, filename: "players.yml"},
+		{selector: "spells", sourceID: artifactpolicy.SourceInputSpellCatalog, filename: "spell_catalog.json"},
+	}
+	request := runner.requests[0]
+	if len(request.References) != len(want) {
+		t.Fatalf("references = %#v", request.References)
+	}
+	loaded := loadLifecycleManifest(t, cfg)
+	for index, expected := range want {
+		binding := request.References[index]
+		canonical := filepath.Join(paths.InputsDir, expected.filename)
+		snapshot := filepath.Join(
+			artifacts.SessionRunNotariusReferencesDirForCampaign(
+				cfg.Pipeline.Workspace.Root, cfg.Session.Campaign, cfg.Session.SessionID, loaded.RunID,
+			),
+			expected.filename,
+		)
+		if binding.Selector != expected.selector || binding.Path != snapshot || binding.Path == canonical || binding.Path == originalPaths[expected.sourceID] {
+			t.Fatalf("reference[%d] = %#v, want selector %q snapshot %q and not prepared/source paths", index, binding, expected.selector, snapshot)
+		}
+	}
+
+	extract := loaded.Stages["extract"]
+	if extract == nil || extract.Status != manifest.StatusSucceeded || extract.Metadata["reference_count"] != float64(len(want)) {
+		t.Fatalf("extract record = %#v", extract)
+	}
+	references, ok := extract.Metadata["references"].([]any)
+	if !ok || len(references) != len(want) || len(references) > config.MaxNotariusReferenceBindings {
+		t.Fatalf("reference metadata = %#v", extract.Metadata["references"])
+	}
+	for index, raw := range references {
+		entry, ok := raw.(map[string]any)
+		if !ok || len(entry) != 5 || entry["selector"] != want[index].selector || entry["source_id"] != want[index].sourceID {
+			t.Fatalf("reference metadata[%d] = %#v", index, raw)
+		}
+	}
+}
+
+func TestExtractLifecyclePreparedReferenceChangeRerunsExtractionAndInvalidatesDownstream(t *testing.T) {
+	cfg, env, runner := extractionLifecycleFixture(t, true)
+	originalPaths := configureLifecycleReferences(t, cfg)
+	if _, err := executeStages(context.Background(), cfg, prepareExtractLifecyclePlan(t), RunOptions{Env: env}); err != nil {
+		t.Fatalf("initial executeStages() error = %v", err)
+	}
+	before := loadLifecycleManifest(t, cfg)
+	beforeChecksum := lifecycleInputChecksum(t, before, "party")
+	for _, name := range []string{"render", "analyze", "publish"} {
+		before.MarkStageSucceeded(name, time.Now().UTC(), nil)
+	}
+	if err := (&manifest.LocalStore{}).Save(context.Background(), manifestPathFor(cfg), before); err != nil {
+		t.Fatalf("Save(downstream success) error = %v", err)
+	}
+	if err := os.WriteFile(originalPaths[artifactpolicy.SourceInputParty], []byte("changed party bytes\n"), 0o644); err != nil {
+		t.Fatalf("WriteFile(party source) error = %v", err)
+	}
+
+	prepared := loadLifecycleManifest(t, cfg)
+	prepare, err := stage.Select("prepare")
+	if err != nil {
+		t.Fatalf("stage.Select(prepare) error = %v", err)
+	}
+	if _, err := prepare.Run(context.Background(), env, prepared); err != nil {
+		t.Fatalf("prepare.Run() error = %v", err)
+	}
+	if lifecycleInputChecksum(t, prepared, "party") == beforeChecksum {
+		t.Fatal("prepared party checksum did not change")
+	}
+	if err := (&manifest.LocalStore{}).Save(context.Background(), manifestPathFor(cfg), prepared); err != nil {
+		t.Fatalf("Save(reprepared manifest) error = %v", err)
+	}
+
+	plan, err := BuildSingleStagePlan("extract")
+	if err != nil {
+		t.Fatalf("BuildSingleStagePlan(extract) error = %v", err)
+	}
+	run, err := executeStages(context.Background(), cfg, plan, RunOptions{Env: env})
+	if err != nil {
+		t.Fatalf("rerun executeStages() error = %v", err)
+	}
+	if len(run.Executed) != 1 || len(run.Skipped) != 0 || len(runner.requests) != 2 {
+		t.Fatalf("rerun summary = %#v requests=%d", run, len(runner.requests))
+	}
+	after := loadLifecycleManifest(t, cfg)
+	if after.Stages["extract"].Status != manifest.StatusSucceeded {
+		t.Fatalf("extract status = %#v", after.Stages["extract"])
+	}
+	for _, name := range []string{"render", "analyze", "publish"} {
+		if after.Stages[name] == nil || after.Stages[name].Status != manifest.StatusStale {
+			t.Fatalf("%s status = %#v, want stale", name, after.Stages[name])
+		}
+	}
+}
+
+func TestExtractLifecycleSessionOverrideBytesReachCanonicalReference(t *testing.T) {
+	cfg, env, runner := extractionLifecycleFixture(t, true)
+	configureLifecycleReferences(t, cfg)
+	overridePath := filepath.Join(filepath.Dir(cfg.SessionPath), "session-party.yml")
+	if err := os.WriteFile(overridePath, []byte("session override party\n"), 0o644); err != nil {
+		t.Fatalf("WriteFile(session override) error = %v", err)
+	}
+	cfg.StableInputs.PartyFile = config.ResolvedInputFile{
+		Path: "./session-party.yml", ConfigPath: cfg.SessionPath, Source: "session_config",
+	}
+	cfg.Session.Inputs.PartyFile = "./session-party.yml"
+
+	if _, err := executeStages(context.Background(), cfg, prepareExtractLifecyclePlan(t), RunOptions{Env: env}); err != nil {
+		t.Fatalf("executeStages() error = %v", err)
+	}
+	if len(runner.requests) != 1 {
+		t.Fatalf("requests = %d", len(runner.requests))
+	}
+	var partyPath string
+	for _, binding := range runner.requests[0].References {
+		if binding.Selector == "party" {
+			partyPath = binding.Path
+		}
+	}
+	contents, err := os.ReadFile(partyPath)
+	if err != nil {
+		t.Fatalf("ReadFile(prepared party) error = %v", err)
+	}
+	if string(contents) != "session override party\n" || partyPath == overridePath {
+		t.Fatalf("prepared party path=%q contents=%q override=%q", partyPath, contents, overridePath)
+	}
+}
+
+func TestExtractLifecycleEmptyReferencesPreserveAllDndExtractionSources(t *testing.T) {
+	cfg, env, runner := extractionLifecycleFixture(t, true)
+	cfg.Pipeline.Notarius.Outputs = lifecycleDndOutputs()
+	keys := make([]string, 0, len(cfg.Pipeline.Notarius.Outputs))
+	for key := range cfg.Pipeline.Notarius.Outputs {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+	analyzeRuns := 0
+	extractPlan, err := BuildSingleStagePlan("extract")
+	if err != nil {
+		t.Fatalf("BuildSingleStagePlan(extract) error = %v", err)
+	}
+	plan := append(extractPlan, assertExtractionSourcesStage{keys: keys, runs: &analyzeRuns})
+
+	summary, err := executeStages(context.Background(), cfg, plan, RunOptions{Env: env})
+	if err != nil {
+		t.Fatalf("executeStages() error = %v", err)
+	}
+	if len(summary.Executed) != 2 || len(runner.requests) != 1 || len(runner.requests[0].References) != 0 || analyzeRuns != 1 {
+		t.Fatalf("summary=%#v requests=%#v analyze=%d", summary, runner.requests, analyzeRuns)
+	}
+	loaded := loadLifecycleManifest(t, cfg)
+	if got := len(loaded.Stages["extract"].Outputs); got != len(keys)+1 {
+		t.Fatalf("extract outputs = %d, want %d lanes plus index", got, len(keys))
+	}
+}
+
 func TestExtractLifecycleChangedOutcomeRerunsSucceededDownstream(t *testing.T) {
 	cfg, env, runner := extractionLifecycleFixture(t, false)
 	analyzeRuns := 0
@@ -252,6 +476,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
@@ -368,6 +618,73 @@ func markLifecycleStageSucceeded(t *testing.T, cfg *config.Config, name string)
 	}
 }
 
+func prepareExtractLifecyclePlan(t *testing.T) []stage.Stage {
+	t.Helper()
+	prepare, err := BuildSingleStagePlan("prepare")
+	if err != nil {
+		t.Fatalf("BuildSingleStagePlan(prepare) error = %v", err)
+	}
+	extract, err := BuildSingleStagePlan("extract")
+	if err != nil {
+		t.Fatalf("BuildSingleStagePlan(extract) error = %v", err)
+	}
+	return append(prepare, extract...)
+}
+
+func configureLifecycleReferences(t *testing.T, cfg *config.Config) map[string]string {
+	t.Helper()
+	cfg.Pipeline.Notarius.References = map[string]string{
+		"party":    artifactpolicy.SourceInputParty,
+		"players":  artifactpolicy.SourceInputPlayers,
+		"glossary": artifactpolicy.SourceInputGlossary,
+		"spells":   artifactpolicy.SourceInputSpellCatalog,
+	}
+	spellPath := filepath.Join(filepath.Dir(cfg.CampaignPath), "spells.json")
+	if err := os.WriteFile(spellPath, []byte(`{"spells":[]}`+"\n"), 0o644); err != nil {
+		t.Fatalf("WriteFile(spell catalog) error = %v", err)
+	}
+	cfg.StableInputs.SpellCatalogFile = config.ResolvedInputFile{
+		Path: "./spells.json", ConfigPath: cfg.CampaignPath, Source: "campaign_config",
+	}
+	cfg.Session.Inputs.SpellCatalogFile = "./spells.json"
+
+	return map[string]string{
+		artifactpolicy.SourceInputParty:        filepath.Join(filepath.Dir(cfg.CampaignPath), "party.yml"),
+		artifactpolicy.SourceInputPlayers:      filepath.Join(filepath.Dir(cfg.CampaignPath), "players.yml"),
+		artifactpolicy.SourceInputGlossary:     filepath.Join(filepath.Dir(cfg.CampaignPath), "glossary.yml"),
+		artifactpolicy.SourceInputSpellCatalog: spellPath,
+	}
+}
+
+func lifecycleInputChecksum(t *testing.T, m *manifest.Manifest, kind string) string {
+	t.Helper()
+	for _, input := range m.Inputs {
+		if input.Kind == kind {
+			if strings.TrimSpace(input.Checksum) == "" {
+				t.Fatalf("input %q has no checksum: %#v", kind, input)
+			}
+			return input.Checksum
+		}
+	}
+	t.Fatalf("manifest input %q not found: %#v", kind, m.Inputs)
+	return ""
+}
+
+func lifecycleDndOutputs() map[string]config.NotariusOutputConfig {
+	return map[string]config.NotariusOutputConfig{
+		"item_registry":        {LaneID: "item-registry", MediaType: "application/json", SchemaID: "notarius.dnd.item_registry", SchemaVersion: "v1", ModuleKey: "dnd/item-registry"},
+		"npc_registry":         {LaneID: "npc-registry", MediaType: "application/json", SchemaID: "notarius.dnd.npc_registry", SchemaVersion: "v1", ModuleKey: "dnd/npc-registry"},
+		"location_registry":    {LaneID: "location-registry", MediaType: "application/json", SchemaID: "notarius.dnd.location_registry", SchemaVersion: "v1", ModuleKey: "dnd/location-registry"},
+		"scene_descriptions":   {LaneID: "scene-descriptions", MediaType: "application/json", SchemaID: "notarius.dnd.scene_descriptions", SchemaVersion: "v1", ModuleKey: "dnd/scene-descriptions"},
+		"item_occurrences":     {LaneID: "item-occurrences", MediaType: "application/json", SchemaID: "notarius.dnd.item_occurrences", SchemaVersion: "v1", ModuleKey: "dnd/item-occurrences"},
+		"spells":               {LaneID: "spells", MediaType: "application/json", SchemaID: "notarius.dnd.spells", SchemaVersion: "v1", ModuleKey: "dnd/spells"},
+		"combat_turns":         {LaneID: "combat-turns", MediaType: "application/json", SchemaID: "notarius.dnd.combat_turns", SchemaVersion: "v1", ModuleKey: "dnd/combat-turns"},
+		"npc_occurrences":      {LaneID: "npc-occurrences", MediaType: "application/json", SchemaID: "notarius.dnd.npc_occurrences", SchemaVersion: "v1", ModuleKey: "dnd/npc-occurrences"},
+		"location_occurrences": {LaneID: "location-occurrences", MediaType: "application/json", SchemaID: "notarius.dnd.location_occurrences", SchemaVersion: "v1", ModuleKey: "dnd/location-occurrences"},
+		"enemy_events":         {LaneID: "enemy-events", MediaType: "application/json", SchemaID: "notarius.dnd.enemy_events", SchemaVersion: "v1", ModuleKey: "dnd/enemy-events"},
+	}
+}
+
 func extractionLifecycleFixture(t *testing.T, enabled bool) (*config.Config, *stage.Env, *materializingNotariusRunner) {
 	t.Helper()
 	cfg := testConfig(t)

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()
+	configured := artifacts.ConfiguredArtifactDefinitions(nil)
-	if err := catalog.RegisterBuiltIns(); err != nil {
-		return nil, err
-	}
-	configured := map[string]artifacts.ConfiguredArtifactDefinition{}
 	if cfg.Pipeline.Scriptorium != nil {
-		for key, item := range cfg.Pipeline.Scriptorium.Artifacts {
+		configured = artifacts.ConfiguredArtifactDefinitions(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
 	}
 	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)) {
+	if effective, err := resolveEffectiveArtifacts(cfg, nil); err == nil {
-		fmt.Fprintf(out, "- %s required=%t\n", artifactpolicy.PreviousSessionSourceID(req.Name), req.Required)
+		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) {
+func loadHelperContext(ctx context.Context, flags commonConfigFlags, needStore bool) (*config.Config, storage.ObjectStore, *effectiveLocks, *manifest.Manifest, func(), error) {
-	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 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")
+	mustWriteSecretFile(t, filepath.Join(secretsDir, accessKeyEnv), "test-key-id\n")
-	mustWriteTestFile(t, filepath.Join(secretsDir, secretKeyEnv), "test-secret\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")
+	mustWriteSecretFile(t, filepath.Join(secretsDir, accessKeyEnv), "test-key-id\n")
-	mustWriteTestFile(t, filepath.Join(secretsDir, secretKeyEnv), "test-secret\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:
@@ -456,6 +458,63 @@ inputs:
 	}
 }
 
+func TestOperatorCommandsReportConfiguredSpellCatalog(t *testing.T) {
+	workspaceRoot := t.TempDir()
+	pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot)
+	campaignBytes, err := os.ReadFile(campaignPath)
+	if err != nil {
+		t.Fatalf("read campaign: %v", err)
+	}
+	campaignYAML := strings.Replace(string(campaignBytes), "  party_file: ./party.yml\n", "  party_file: ./party.yml\n  spell_catalog_file: ./spells.json\n", 1)
+	if err := os.WriteFile(campaignPath, []byte(campaignYAML), 0o644); err != nil {
+		t.Fatalf("write campaign: %v", err)
+	}
+	spellPath := filepath.Join(filepath.Dir(campaignPath), "spells.json")
+	mustWriteTestFile(t, spellPath, "{\"spells\":[]}\n")
+
+	fake := &storage.FakeBackend{}
+	var storeInitCalls int
+	restoreAppConfigTestGlobals(t, fake, &storeInitCalls, []string{sessionPath})
+	commonArgs := []string{
+		"2026-05-03",
+		"--config", pipelinePath,
+		"--campaign-file", campaignPath,
+		"--session", sessionPath,
+	}
+
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	validateArgs := append([]string{"session", "validate"}, commonArgs...)
+	if code := Execute(validateArgs, &stdout, &stderr); code != 0 {
+		t.Fatalf("validate exit code = %d, want 0; stdout=%q stderr=%q", code, stdout.String(), stderr.String())
+	}
+	if !strings.Contains(stdout.String(), "OK    inputs     spell_catalog: "+spellPath) {
+		t.Fatalf("validate stdout = %q, want spell catalog finding", stdout.String())
+	}
+
+	stdout.Reset()
+	stderr.Reset()
+	statusArgs := append([]string{"session", "status"}, commonArgs...)
+	if code := Execute(statusArgs, &stdout, &stderr); code != 0 {
+		t.Fatalf("status exit code = %d, want 0; stdout=%q stderr=%q", code, stdout.String(), stderr.String())
+	}
+	if !strings.Contains(stdout.String(), "Stable input spell_catalog: "+spellPath) {
+		t.Fatalf("status stdout = %q, want spell catalog inventory", stdout.String())
+	}
+
+	if err := os.Remove(spellPath); err != nil {
+		t.Fatalf("remove spell catalog: %v", err)
+	}
+	stdout.Reset()
+	stderr.Reset()
+	if code := Execute(validateArgs, &stdout, &stderr); code == 0 {
+		t.Fatalf("validate missing spell catalog exit code = 0; stdout=%q", stdout.String())
+	}
+	if !strings.Contains(stdout.String(), "ERROR inputs     spell_catalog missing:") {
+		t.Fatalf("validate stdout = %q, want missing spell catalog finding", stdout.String())
+	}
+}
+
 func TestExecuteLocksAddListAndRemoveUseRemoteLockStore(t *testing.T) {
 	workspaceRoot := t.TempDir()
 	pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot)
@@ -522,6 +581,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 +1155,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 +1205,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 +1343,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 +1357,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
+	Requirements   []artifacts.PreviousArtifactRequirement
-	MissingID    bool
+	SkippedMissing []string
-	Err          error
+	Err            error
 }
 
 type remoteCurrentStateCheck struct {
@@ -51,23 +53,28 @@ type effectiveLocksCheck struct {
 
 func inspectStableInputs(cfg *config.Config) []stableInputCheck {
 	items := []struct {
-		name string
+		name     string
-		in   config.ResolvedInputFile
+		in       config.ResolvedInputFile
+		optional bool
 	}{
 		{name: "speakers", in: cfg.StableInputs.SpeakersFile},
 		{name: "autocorrect", in: cfg.StableInputs.AutocorrectFile},
 		{name: "glossary", in: cfg.StableInputs.GlossaryFile},
 		{name: "players", in: cfg.StableInputs.PlayersFile},
 		{name: "party", in: cfg.StableInputs.PartyFile},
+		{name: "spell_catalog", in: cfg.StableInputs.SpellCatalogFile, optional: true},
 	}
 	out := make([]stableInputCheck, 0, len(items))
 	for _, item := range items {
+		if item.optional && strings.TrimSpace(item.in.Path) == "" {
+			continue
+		}
 		path, err := resolveHelperConfigRelativePath(item.in)
 		if err != nil {
 			out = append(out, stableInputCheck{Name: item.name, Err: err})
 			continue
 		}
-		if _, err := os.Stat(path); err != nil {
+		if err := requireInspectionFile(path, item.name); err != nil {
 			out = append(out, stableInputCheck{Name: item.name, Path: path, Err: err})
 			continue
 		}
@@ -152,23 +159,27 @@ func inspectPreviousArtifactReadiness(
 	if len(requirements) == 0 {
 		return out
 	}
-	if strings.TrimSpace(cfg.Session.PreviousSessionID) == "" {
+	if cfg == nil || cfg.Pipeline == nil || cfg.Session == nil {
-		out.MissingID = true
+		out.Err = fmt.Errorf("resolved config with pipeline/session is required")
 		return out
 	}
-	if store == nil {
+	paths := artifacts.NewLocalStore(cfg.Pipeline.Workspace.Root).SessionPathsFor(cfg.Session.Campaign, cfg.Session.SessionID)
-		out.Err = fmt.Errorf("previous-session artifacts cannot be checked because storage is unavailable")
+	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
 	}
-
+	out.SkippedMissing = append([]string(nil), plan.SkippedMissing...)
-	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)
-	}
 	return out
 }
 
@@ -265,8 +276,8 @@ func requireInspectionFile(path, label string) error {
 		}
 		return fmt.Errorf("stat %s %q: %w", label, path, err)
 	}
-	if info.IsDir() {
+	if !info.Mode().IsRegular() {
-		return fmt.Errorf("%s %q is a directory", label, path)
+		return fmt.Errorf("%s %q is not a regular file", label, path)
 	}
 	return nil
 }

internal/app/operator_inspection_fifo_test.go

@@ -0,0 +1,34 @@
+//go:build unix
+
+package app
+
+import (
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/config"
+	"golang.org/x/sys/unix"
+)
+
+func TestInspectStableInputsRejectsSpellCatalogFIFO(t *testing.T) {
+	root := t.TempDir()
+	sourcePath := filepath.Join(root, "spells.fifo")
+	if err := unix.Mkfifo(sourcePath, 0o644); err != nil {
+		t.Fatalf("Mkfifo() error = %v", err)
+	}
+
+	cfg := &config.Config{StableInputs: config.ResolvedStableInputs{
+		SpellCatalogFile: config.ResolvedInputFile{Path: sourcePath, ConfigPath: filepath.Join(root, "campaign.yml")},
+	}}
+	for _, check := range inspectStableInputs(cfg) {
+		if check.Name != "spell_catalog" {
+			continue
+		}
+		if check.Err == nil || !strings.Contains(check.Err.Error(), "not a regular file") {
+			t.Fatalf("spell catalog check = %#v, want regular-file rejection", check)
+		}
+		return
+	}
+	t.Fatal("spell catalog inspection result was not reported")
+}

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 err := mutateRemoteLockStore(ctx, cfg, store, func(lockStore *config.PublishLockStore) error {
-	if _, exists := remoteSet[source]; exists && !force {
+		remoteSet := lockSourceSet(lockStore.Locks)
-		return fmt.Errorf("locks add: remote lock for %q already exists; pass --force to update", source)
+		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)}
+		}
-	remoteLocks := lockMapValues(remoteSet)
+		remoteSet[source] = config.PublishLockRule{Source: source, Reason: strings.TrimSpace(reason)}
-	if _, err := config.ValidatePublishLockRules(remoteLocks, cfg.Pipeline.Scriptorium, cfg.Pipeline.Notarius, "locks"); err != nil {
+		lockStore.Locks = lockMapValues(remoteSet)
-		return fmt.Errorf("locks add: %w", err)
+		normalized, err := config.ValidatePublishLockRules(lockStore.Locks, cfg.Pipeline.Scriptorium, cfg.Pipeline.Notarius, "locks")
-	}
+		if err != nil {
-	if err := uploadRemoteLockStore(ctx, store, locks.Key, &config.PublishLockStore{Locks: remoteLocks}); 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 err := mutateRemoteLockStore(ctx, cfg, store, func(lockStore *config.PublishLockStore) error {
-	if _, ok := remoteSet[source]; !ok {
+		remoteSet := lockSourceSet(lockStore.Locks)
-		if _, static := lockSourceSet(locks.Static)[source]; static {
+		if _, ok := remoteSet[source]; !ok {
-			return fmt.Errorf("locks remove: source %q is locked by pipeline config and cannot be unlocked remotely", source)
+			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)
-	}
+		lockStore.Locks = lockMapValues(remoteSet)
-	delete(remoteSet, source)
+		return nil
-	remoteLocks := lockMapValues(remoteSet)
+	}); err != nil {
-	if err := uploadRemoteLockStore(ctx, store, locks.Key, &config.PublishLockStore{Locks: remoteLocks}); 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") {
+	if !strings.Contains(err.Error(), "validate secrets env_dir") {
-		t.Fatalf("error = %q, want secrets read error context", err.Error())
+		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
+	cleanup := m.PostPublishCleanup
-	workRequested := env.Config.Pipeline.Workspace.CleanupAfterPublish
+	if cleanup == nil {
-	if !spoolRequested && !workRequested {
+		var err error
-		return nil
+		cleanup, err = createPostPublishCleanup(env.Config, m, executed)
-	}
+		if err != nil {
-
+			return err
-	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)
 		}
-		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,
+			cfg.Pipeline.Spool.Root,
-			strings.TrimSpace(env.Config.Session.Campaign),
+			strings.TrimSpace(m.Campaign),
-			strings.TrimSpace(env.Config.Session.SessionID),
+			strings.TrimSpace(m.SessionID),
-			strings.TrimSpace(m.RunID),
+			publishedRunID,
 		)
 	}
 	workDir := strings.TrimSpace(m.LocalWorkDir)
 	if workDir == "" {
 		workDir = artifacts.SessionRunRootForCampaign(
-			env.Config.Pipeline.Workspace.Root,
+			cfg.Pipeline.Workspace.Root,
-			strings.TrimSpace(env.Config.Session.Campaign),
+			strings.TrimSpace(m.Campaign),
-			strings.TrimSpace(env.Config.Session.SessionID),
+			strings.TrimSpace(m.SessionID),
-			strings.TrimSpace(m.RunID),
+			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 {
+		cleanup.Targets = append(cleanup.Targets, manifest.CleanupTarget{
-			sr.Metadata["cleanup_failed"] = true
+			Policy: "pipeline.spool.delete_audio_after_publish",
-			sr.Metadata["cleanup_failed_policy"] = "pipeline.spool.delete_audio_after_publish"
+			Root:   strings.TrimSpace(cfg.Pipeline.Spool.Root),
-			sr.Metadata["cleanup_failed_path"] = spoolDir
+			Path:   filepath.Clean(spoolDir),
-			_ = env.ManifestStore.Save(ctx, manifestPath, m)
+		})
-			return err
-		}
-		sr.Metadata["spool_cleanup_deleted"] = filepath.Clean(spoolDir)
 	}
-
+	if workRequested {
-	if !workRequested {
+		cleanup.Targets = append(cleanup.Targets, manifest.CleanupTarget{
-		sr.Metadata["cleanup_completed"] = true
+			Policy: "pipeline.workspace.cleanup_after_publish",
-		sr.Metadata["cleanup_skipped"] = false
+			Root:   strings.TrimSpace(cfg.Pipeline.Workspace.Root),
-		if err := env.ManifestStore.Save(ctx, manifestPath, m); err != nil {
+			Path:   filepath.Clean(workDir),
-			return fmt.Errorf("save manifest cleanup metadata %q: %w", manifestPath, err)
+		})
-		}
-		return nil
 	}
-
+	return cleanup, nil
-	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
 }
 
-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 {
+	if strings.TrimSpace(asString(sr.Metadata["remote_commit_key"])) == "" {
-		return false, "publish did not write current pointer"
+		return "", false, "publish remote commit key is missing"
 	}
-	if strings.TrimSpace(asString(sr.Metadata["current_run_id_key"])) == "" {
+	if strings.TrimSpace(asString(sr.Metadata["current_commit_pointer_key"])) == "" {
-		return false, "publish current run pointer key is missing"
+		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) Name() string { return "publish" }
-func (publishSuccessStage) Declares() stage.IODecl { return stage.IODecl{} }
+func (s publishSuccessStage) Run(_ context.Context, _ *stage.Env, m *manifest.Manifest) (*stage.StageResult, error) {
-func (s publishSuccessStage) Run(_ context.Context, _ *stage.Env, _ *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",
+		"stage":                      "publish",
-		"uploaded":                true,
+		"uploaded":                   true,
-		"current_pointer_written": true,
+		"published_run_id":           m.RunID,
-		"current_run_id_key":      "dnd/campaigns/sample-campaign/sessions/2026-05-03/current/run_id.txt",
+		"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) Name() string { return "notify" }
-func (notifyFailStage) Declares() stage.IODecl { return stage.IODecl{} }
 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") {
+	if err == nil || !strings.Contains(err.Error(), "immutable object") {
-		t.Fatalf("executeStages() error = %v, want current-manifest failure", err)
+		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") {
+	if err == nil || !strings.Contains(err.Error(), "current commit pointer") {
-		t.Fatalf("executeStages() error = %v, want current-run-pointer failure", err)
+		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 {
+	if strings.TrimSpace(info.ETag) == "" {
-		return &config.PublishLockStore{}, key, nil
+		return nil, key, "", fmt.Errorf("read remote locks %q: object has no generation", key)
-	}
-	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)
 	}
 	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 {
+func mutateRemoteLockStore(ctx context.Context, cfg *config.Config, store storage.ObjectStore, mutate func(*config.PublishLockStore) error) error {
-	data, err := config.MarshalPublishLockStore(lockStore)
+	for attempt := 0; attempt < remoteLockMutationAttempts; attempt++ {
-	if err != nil {
+		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")
+	return fmt.Errorf("update remote locks: concurrent updates prevented a conditional write after %d attempts", remoteLockMutationAttempts)
-	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
 }
 
 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")
+	mustWriteSecretFile(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, secretKeyEnv), "remote-session-secret\n")
 	addSecretsToPipelineConfig(t, pipelinePath, secretsDir, accessKeyEnv, secretKeyEnv)
 
 	fake := &storage.FakeBackend{}