@kontourai/flow-agents 3.12.0 → 4.0.0

package/dist/codex/docs/decisions/writer-observed-execution.md

@@ -0,0 +1,51 @@
+---
+status: current
+subject: Writer-observed execution
+decided: 2026-07-14
+evidence:
+  - kind: issue
+    ref: "634"
+  - kind: adr
+    ref: docs/adr/0017-anti-gaming-trust-security-model.md
+  - kind: adr
+    ref: docs/adr/0020-trust-reconcile-manifest-and-claim-classification.md
+---
+# Writer-observed execution
+
+**Decision.** When `record-gate-claim` executes a declared evidence command itself
+(`runObservedCommand` — a real process it spawned, with a real exit code, output hash, and,
+for tests, a `local-process-exit` execution proof), it appends that observation to the same
+hash-chained `command-log.jsonl` the PostToolUse capture hook writes, under the same
+lockfile protocol, visibly attributed via `source: "canonical-writer-execution"`. The
+capture fold's precedence is **outcome-ranked, source-blind**: observed fail > observed
+pass > ambiguous, with the exit code always traveling with the winning status. The
+properties that matter follow: a writer pass can lift ambiguity but can never bury an
+independently captured failure (fail is sticky from either source), and a writer-observed
+failure likewise defeats any pass. Passes from the two sources rank equally — the
+distinction between them lives in the permanent `source` attribution, not in the fold. The chain
+fork classifier tolerates shared-parent siblings only when every sibling's source is
+`postToolUse-capture` or `canonical-writer-execution`; any other source on a shared parent
+remains tamper.
+
+**Context.** ADR 0017/0020 make the independent capture log the truth source for command
+outcomes, and #470 hardened capture to never record `pass` without positive evidence. On
+hosts whose runtime hook payloads carry no exit code (Codex's PostToolUse
+`tool_response` today), every captured entry is honestly `ambiguous` — and #634 showed the
+consequence: `builder.verify.*` claims can never derive `verified`, while the sanctioned
+accepted-gap waiver produces `assumed`, which no gate's `accepted_statuses` admits. The
+verify gate was structurally unclosable on such hosts regardless of evidence quality.
+
+**Why this preserves the anti-gaming posture.** A writer observation is not an inference or
+a self-report of intent — it is the exit code of a process the canonical writer itself
+spawned and waited on. It enters the record distinguishable forever (the `source` field),
+tamper-evident (chain-hashed), serialized against the hook (shared lock), and subordinate
+on conflict (an observed fail from either source wins). The waiver path is untouched:
+accepted gaps remain disclosure that derives `assumed`, never gate satisfaction.
+
+**Residual risk, accepted.** A compromised writer process could self-attest a pass the hook
+never saw. Mitigations: the attribution is permanent and auditable; the chain makes
+retroactive editing detectable; a hook-observed failure always prevails; and PR CI Trust
+Reconcile re-executes manifest commands independently of any local observation. Follow-up
+(#634 option c): when runtime harnesses surface exit codes in hook payloads, hook capture
+naturally resumes confirming passes first-hand; writer observations then serve as
+corroboration rather than the sole deterministic signal.

package/dist/codex/docs/fixture-ownership.md

@@ -23,11 +23,15 @@ run `npm run validate:source --` and `npm run fixture:retirement-audit --`.
 | `evals/fixtures/kit-conformance-levels` | K-level conformance and consumer-target derivation fixtures | `evals/integration/test_kit_conformance_levels.sh` | Keep while K-level derivation, degradation invariant, and consumer-target badge rules are tested. |
 | `evals/fixtures/hook-influence` | hook influence behavioral cases | `evals/integration/test_hook_influence_cases.sh`, `evals/static/test_workflow_skills.sh`, `scripts/validate-hook-influence-cases.js` | Keep while hook influence cases define agent guidance behavior. |
 | `evals/fixtures/learning-review-proposals` | learning-review kit/gate tuning proposal fixtures (#352): pattern-present (engineered cost-inflation + gate false-block-rate pattern, with sessions/ trust.bundle + gate-review.inquiries.json joins and a hand-computed expected-aggregates.json), balanced (proportional cost/findings movement -> zero proposals), under-threshold (below LR_MIN_WINDOW_SAMPLE), repeat-window (idempotency), and effect-follow-up (later-window effect-fill pass for a ratified proposal) | `evals/integration/test_learning_review_proposals.sh` | Keep while `scripts/telemetry/learning-review-proposals.sh`/`learning-review-decide.sh` (docs/specs/learning-review-proposals-contract.md) are enforced: hand-computed aggregates, evidence-cited proposals, zero-mutation, idempotency, and the ratify -> effect-fill trail. |
+| `evals/fixtures/narrative-sources` | narrative source snapshot, offline resolution, integrity, completeness, fail-closed redaction, grounded runtime projection, grounded execution narrative, and trust-isolation fixtures (#613, #617, #618, #619) | `evals/integration/test_narrative_source_contract.sh`, `evals/integration/test_narrative_runtime_projection.sh`, `evals/integration/test_narrative_grounded_envelope.sh`, `evals/integration/test_narrative_redaction_failclosed.sh`, `evals/integration/test_narrative_trust_isolation.sh` | Keep while the narrative source manifest, content-addressed offline resolver, integrity verification, grounded runtime projection, grounded execution narrative composition, capture-completeness disclosure, lifecycle locality, fail-closed redaction, and narrative trust-isolation contracts are supported. |
+| `evals/fixtures/narrative-grounding-validator` | narrative grounding validator adversarial fixtures (#623) | `evals/integration/test_narrative_grounding_validator.sh` | Keep while deterministic citation integrity, material-event coverage, epistemic-label integrity, and fail-closed narrative publication are enforced. |
+| `evals/fixtures/narrative-prose-renderer` | model-assisted prose renderer adversarial fixtures (#614): provenance-subset (unsupported-summary), no-op-loop lack-of-progress wording, and prompt-injection fixtures reused from evals/fixtures/narrative-grounding-validator | `evals/integration/test_narrative_prose_renderer.sh` | Keep while the fail-closed prose renderer (D3 provenance-subset citation check, provider gating, economics-always, zero-prose-artifact-on-failure) is enforced. |
+| `evals/fixtures/narrative-evals` | grounded narrative faithfulness eval corpus + result-schema package (#612): ten R1 case-class fixtures with frozen-manifest answer keys plus five R3 corruption fixtures whose named eval-check anchors are the scorer-teeth mutation targets | `evals/integration/test_narrative_evals.sh` | Keep while the versioned adversarial corpus, its frozen-manifest answer keys, the schema-valid narrative-eval-result output, the declared cross-runtime capability parity, and the R3 scorer-teeth mutation battery are enforced. |
 | `evals/fixtures/pull-work-provider` | work item provider normalization fixtures | `evals/integration/test_pull_work_provider.sh` | Keep while provider normalization preserves blockers, artifact refs, board membership, and freshness metadata. |
 | `evals/fixtures/pull-work-wip-shepherding` | WIP shepherding state fixtures | `evals/static/test_workflow_skills.sh` | Keep while pull-work documents personal versus global WIP behavior. |
 | `evals/fixtures/reconcile-preflight` | #356 reconcile-preflight shape fixtures not already covered by trust-reconcile-exploits (un-superseded disputed critique, standalone disputed session-local claim) | `evals/integration/test_reconcile_preflight.sh` | Keep while the local `reconcile-preflight` subcommand (#356) is proven against the two shapes trust-reconcile-exploits does not already fixture (un-superseded disputed critique, standalone disputed session-local claim); the other four shapes reuse trust-reconcile-exploits/trust-reconcile-mixed-bundle directly rather than forking near-duplicates. |
 | `evals/fixtures/surface-trust` | Surface trust evidence fixtures | `evals/integration/test_workflow_sidecar_writer.sh` | Keep while sidecar writer maps Surface trust evidence into workflow records. |
-| `evals/fixtures/telemetry` | hermetic Stop-hook usage transcript fixture (#defect-2026-07 telemetry-usage-cost-extraction): a multi-model JSONL transcript with .message.model + .message.usage token blocks proving real token/cost/model extraction end-to-end; also reused by the #568 slice 1 per-tool-call usage-enrichment eval (test_telemetry_tool_usage.sh), which adds usage-transcript-oversized-prefix.jsonl to prove the bounded tail-read | `evals/integration/test_usage_cost.sh`, `evals/integration/test_telemetry_usage_pipeline.sh`, `evals/integration/test_telemetry_tool_usage.sh` | Keep while telemetry.sh's Stop-hook usage pipeline (usage_parse_transcript / usage_model_from_transcript_usage / usage_last_turn_usage) is proven against hermetic multi-model and oversized-prefix transcripts rather than relying on live runtime data. |
+| `evals/fixtures/telemetry` | hermetic Stop-hook usage transcript fixture (#defect-2026-07 telemetry-usage-cost-extraction): a multi-model JSONL transcript with .message.model + .message.usage token blocks proving real token/cost/model extraction end-to-end; also reused by the #568 slice 1 per-tool-call usage-enrichment eval (test_telemetry_tool_usage.sh), which adds usage-transcript-oversized-prefix.jsonl to prove the bounded tail-read | `evals/integration/test_usage_cost.sh`, `evals/integration/test_telemetry_usage_pipeline.sh`, `evals/integration/test_telemetry_tool_usage.sh`, `evals/integration/test_telemetry_tool_outcome.sh` | Keep while telemetry.sh's Stop-hook usage pipeline (usage_parse_transcript / usage_model_from_transcript_usage / usage_last_turn_usage) is proven against hermetic multi-model and oversized-prefix transcripts rather than relying on live runtime data. |
 | `evals/fixtures/trust-reconcile-exploits` | WS8 trust-reconcile anti-gaming exploit fixtures (frozen negative regressions); also reused by the #356 local reconcile-preflight eval (same shapes, no forked copies) | `evals/integration/test_trust_reconcile_negatives.sh`, `evals/integration/test_reconcile_preflight.sh` | Keep while trust-reconcile.js enforces the WS8 iteration-2 soundness properties (no-label test_output, unwaived-assumed, status-misassertion, waiver-on-command); each fixture is a permanent negative regression. |
 | `evals/fixtures/trust-reconcile-mixed-bundle` | WS8 trust-reconcile mixed-evidence end-to-end proof fixture; also reused by the #356 reconcile-preflight eval as its CLEAN-BUNDLE (AC4) case | `evals/integration/test_trust_reconcile_mixed_bundle.sh`, `evals/integration/test_reconcile_preflight.sh` | Keep while the trust-reconcile manifest/classification/waiver contract (ADR 0020) is enforced; proves a mixed test_output + session-local + waived bundle passes the CI anchor. |
 | `evals/fixtures/trust-reconcile-ws3` | WS8 AC6 backward-compat fixture: real ws3-kit-dependencies-namespacing old-style bundle | `evals/integration/test_trust_reconcile_negatives.sh` | Keep while backward compatibility with pre-classification (all-test_output) bundles is asserted; proves an old-style bundle still FAILS the same way (no silent pass). |

package/dist/codex/docs/migrations.md

@@ -6,6 +6,26 @@ title: Migrations
 
 ## Unreleased
 
+- Gate-action envelopes now use `schema_version: "3.0"`. `action.declared_artifacts`
+  and `stop_condition.required.artifact_refs` contain typed targets instead of
+  strings. A `file` target names its project-relative `path` and whether it is
+  directly writable or must be produced through a declared operation; a
+  `trust_slice` target is explicitly non-writable and names the public interface
+  that records it. `action.artifact_bindings` maps each typed target to the
+  gate expectation ids it satisfies, so consumers can derive the exact required
+  target set from unresolved required expectations without private kit metadata.
+  The bindings are product-owned gate semantics, not grader hints or
+  consumer-authored guidance. Empty expectation ownership on a file represents
+  a declared optional artifact that is never gate-required; trust slices must
+  own an expectation so their recording interface can be derived.
+  Structured evidence parameters reference the canonical
+  `public_interfaces.schemas.evidence_ref_json` JSON Schema. There is no legacy
+  envelope fallback; adapters must require version 3.0 and stop treating
+  `trust.bundle#<slice>` as a filesystem path.
+- Gate-action envelope version 2.0 added the originating `gate_id` to each
+  `gate.requirements` entry, allowing consumers to
+  verify accepted exceptions without private Flow-definition knowledge. There
+  was no legacy version 1.0 fallback.
 - Workflow runtime artifacts now live under `.kontourai/flow-agents/` instead
   of earlier runtime roots such as `.flow-agents/` or `.agents/flow-agents/`.
   Move any local session directories, sidecars, or `current.json` pointers you

package/dist/codex/docs/public-workflow-cli.md

@@ -165,12 +165,21 @@ consume another turn when `workflow drive` is invoked again:
 flow_agents workflow drive \
   --session-dir .kontourai/flow-agents/example \
   --adapter-command-file .kontourai/flow-agents/runtime-adapter.json \
+  --context-policy fresh \
   --max-turns 6 \
   --turn-timeout-ms 900000 \
   --barrier-wait-ms 300000 \
   --json
 ```
 
+`--context-policy warm` remains the default and requests one new adapter context for the mission,
+then resumes it. `--context-policy fresh` requests a new context for every bounded Flow action. Both
+policies pass the same canonical gate-action handoff and preserve the same Flow gates, evidence rules,
+mission budget, and adapter authority. The selected policy is persisted with the mission and cannot be
+changed on resume. Adapters must honor the request's `context_strategy.thread` value and must not infer
+context routing from model names. This is a context-management capability, not permission to drop gates,
+invent evidence, or replay a prior transcript into a nominally fresh context.
+
 Driver state and its append-only event stream live under
 `.kontourai/flow-agents/<slug>/continuation-driver/`. The mission turn count survives reinvocation;
 subsequent invocations must use the same `--max-turns` value. The request contains the

package/dist/codex/docs/spec/builder-flow-runtime.md

@@ -157,7 +157,7 @@ authority for pointer navigation.
 ### Gate-Action Envelope
 
 Every active Builder continuation request includes a bounded
-`gate_action_envelope` with schema version `1.0`. Flow Agents derives it from
+`gate_action_envelope` with schema version `3.0`. Flow Agents derives it from
 the persisted canonical Flow run and effective Flow Definition, then joins it
 to the installed Builder Kit's validated `flow_step_actions` record. It is an
 execution context, not a second gate evaluator: Flow remains the only authority
@@ -179,12 +179,30 @@ Declared operations, artifacts, and evidence expectation ids come from product
 metadata. `implementation_allowed` is also product metadata; the shipped Builder
 Kit declares it true only for `builder.build/execute`.
 
-The read-only status interface is an exact version-pinned command. Mutation
+Declared artifact targets are typed. A `file` target includes its resolved
+project-relative path under the active session, its direct-write policy, and
+the skill or external operation that produces it. Operation result files are
+not model-writable. A `trust_slice` target names a
+logical `trust.bundle#<slice>` projection, sets `direct_write_allowed` to false,
+and identifies the public evidence or critique interface that records it. A
+trust slice is never a filename and adapters must not edit `trust.bundle`
+directly.
+
+The read-only status interface identifies the exact package version, binary,
+and argv without requiring an adapter to parse a shell command. Mutation
 interfaces are typed per expectation: `workflow.evidence`, `workflow.critique`,
 or a named product operation such as `publish-change`. Evidence and critique
 interfaces expose fixed argv plus typed required parameters and allowed values;
-they do not publish shell strings with substitution placeholders. Consumers add
-parameter values as distinct argv entries.
+they do not publish shell strings with substitution placeholders. Structured
+evidence parameters reference `public_interfaces.schemas.evidence_ref_json`, a
+bounded JSON Schema with required fields for source, command, artifact,
+provider, and external evidence. Consumers add parameter values as distinct
+argv entries.
+
+Adapters that perform an allowed direct file write remain responsible for
+opening the target without following symlinks and for confirming that the final
+path remains inside the active session. The envelope declares authority and
+identity; it does not make an arbitrary adapter filesystem write atomic.
 
 `publish-change` is a provider-capability protocol, not a claim that the local
 `flow-agents publish-change` helper opens a pull request. Its envelope binds the
@@ -204,7 +222,14 @@ checks; it is not the provider action executor.
 empty lists for terminal actions. Expectation ids must exactly equal the resolved
 Flow expectation set. Artifact bindings map each artifact to its owning
 expectations, allowing optional artifacts to remain declared without appearing
-under `stop_condition.required`. Operation bindings must resolve through the
+under `stop_condition.required`. The same ownership is projected publicly as
+typed `action.artifact_bindings`; consumers derive required targets by selecting
+bindings that own an unresolved required expectation. These bindings are
+product-owned gate semantics, not grader hints or consumer-authored guidance.
+For file artifacts, an empty `expectation_ids` list keeps the artifact declared
+and observable but never gate-required. Trust slices must own at least one
+expectation because ownership determines their recording interface.
+Operation bindings must resolve through the
 canonical public operation catalog, not merely a self-declared string. Artifact
 refs are either lexically safe session-relative paths or validated
 `trust.bundle#<safe-id>` virtual refs; absolute paths, traversal, and arbitrary
@@ -265,11 +290,16 @@ exception applies, or every effective expectation is optional. This advances
 those gates without prematurely evaluating ordinary missing-required gates, and
 once the run advances no obsolete action skill remains required.
 
-The envelope and its prior-turn delta are additive fields of
+The envelope, its prior-turn delta, and `context_strategy` are additive fields of
 `ContinuationTurnRequest` schema `1.0`; adapters that only consume the existing
-request fields remain compatible. When `workflow drive` produces its optional
+request fields remain compatible. `context_strategy` tells a capable adapter to
+start a `new` context or `resume` the mission context and identifies the handoff
+as canonical. The mission-bound policy defaults to warm continuation; selecting
+fresh context changes only transcript routing, never the Flow contract, gate
+requirements, or evidence authority. When `workflow drive` produces its optional
 signed request/result attestation, the exact request object (including the
-envelope) is included in the signed payload without transformation.
+envelope and context strategy) is included in the signed payload without
+transformation.
 # Builder Lifecycle Authority
 
 The canonical Flow run owns pause, resume, and cancellation. The current assignment actor may
@@ -295,6 +325,7 @@ Flow issue #118.
 ```text
 flow-agents builder-run pause --session-dir <dir> --reason <text>
 flow-agents builder-run resume --session-dir <dir> --reason <text>
+flow-agents builder-run cancel-request --session-dir <dir> [--out <file>] [--reason <text>] [--actor <name>] [--expires-in-hours <n>]
 flow-agents builder-run cancel --session-dir <dir> --authorization-file <record.json>
 flow-agents builder-run release-assignment --session-dir <dir> --reason <text>
 flow-agents builder-run archive --session-dir <dir> --authorization-file <record.json>
@@ -307,3 +338,13 @@ assignment while holding the same lock; a successfully consumed cancellation non
 replayed. Archive accepts only completed or canceled runs, moves the session under
 `.kontourai/flow-agents/archive/<slug>/`, and retains the canonical Flow run. None of these
 operations deletes a branch or worktree; cleanup requires a separate provider-aware action.
+
+`cancel-request` is a **read-only convenience** that removes the friction of hand-assembling a
+cancellation record: it mints the *unsigned* authorization for the run (correct `run_id`,
+`subject`, active `assignment_actor`, a fresh `nonce` and expiry) and prints the exact
+`signing_payload` bytes to sign. It does not sign, cancel, or mutate anything — the operator signs
+the payload with their Ed25519 lifecycle-authority key, adds the `signature` block to the emitted
+file, and runs `cancel --authorization-file` as above. The signing payload is produced through the
+same actor/request normalization the verifier applies, so a signature over it verifies by
+construction. Like `cancel`, it requires an active assignment holder; an active run whose
+assignment has already been released cannot be authorized this way without re-claiming it first.

package/dist/codex/docs/spec/runtime-hook-surface.md

@@ -29,13 +29,20 @@ Every Flow Agents event has a canonical name that is runtime-neutral. Adapters m
 | `userPromptSubmit` | The user submits a new turn or message. Maps from `UserPromptSubmit`. | `hook_event_name` | `turn.prompt_text` (redacted by default), `cwd` |
 | `preToolUse` | Immediately before a tool call is executed. Maps from `PreToolUse`. | `hook_event_name`, `tool_name`, `tool_input` | `tool_id`, `cwd`, `usage.model`, `usage.input_tokens`, `usage.output_tokens`, `usage.cache_creation_input_tokens`, `usage.cache_read_input_tokens`, `usage.estimated_cost_usd`, `usage.pricing_version` |
 | `permissionRequest` | The runtime is asking for permission to run a tool or action. Maps from `PermissionRequest`. | `hook_event_name`, `tool_name` | `tool_input`, `cwd` |
-| `postToolUse` | After a tool call completes (success or failure). Maps from `PostToolUse` and `PostToolUseFailure`. | `hook_event_name`, `tool_name`, `tool_response` | `tool_input`, `tool_output`, `error`, `cwd`, `usage.model`, `usage.input_tokens`, `usage.output_tokens`, `usage.cache_creation_input_tokens`, `usage.cache_read_input_tokens`, `usage.estimated_cost_usd`, `usage.pricing_version` |
+| `postToolUse` | After a tool call completes (success or failure). Maps from `PostToolUse` and `PostToolUseFailure`. | `hook_event_name`, `tool_name`, `tool_response` | `tool_input`, `tool_output`, `error`, `cwd`, `tool.duration_ms`, `tool.outcome`, `tool.status`, `usage.model`, `usage.input_tokens`, `usage.output_tokens`, `usage.cache_creation_input_tokens`, `usage.cache_read_input_tokens`, `usage.estimated_cost_usd`, `usage.pricing_version` |
 | `stop` | The agent is about to stop and return control to the user. Maps from `Stop` and `SessionEnd`. | `hook_event_name` | `stop_reason`, `cwd` |
 | `subagentStart` | A subagent or specialist delegate is spawning. Maps from `SubagentStart` (Codex). | `hook_event_name` | `agent_name`, `agent_type` |
 | `subagentStop` | A subagent or specialist delegate has stopped. Maps from `SubagentStop` (Codex). | `hook_event_name` | `agent_name`, `outcome` |
 
 **`usage.*` on `preToolUse`/`postToolUse` (#568 slice 1).** These two events carry an optional `.usage` object — `model`, `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens`, `estimated_cost_usd`, `pricing_version` — sourced from the runtime transcript's LAST assistant turn (the turn that produced this specific tool call), joined via a bounded tail-read of `hook.transcript_path`. This is **per-turn, not a per-tool-call cost fraction**: multiple tool calls inside the same assistant turn (parallel tool_use blocks) report the *same* whole-turn usage figures — do not sum `estimated_cost_usd` across `tool.invoke`/`tool.result` rows within one turn, or cost will be double-counted; `session.usage`'s cumulative totals remain the authoritative aggregate. When the transcript join is unavailable but the runtime's `.model` hook field is present, only `usage.model` is populated and every token/cost field is explicitly `null` (never a guessed number); `.model` itself is best-effort on these two events (see §8.2), not a contractually guaranteed field. `tool.permission_request` (`permissionRequest`) is explicitly excluded from this enrichment.
 
+**`tool.duration_ms` / `tool.outcome` / `tool.status` on `tool.result` (#580).** Every `tool.result` record (from `postToolUse`/`PostToolUse`/`PostToolUseFailure`) carries three intrinsic tool-result fields on its `.tool` object (co-located with `.tool.name`/`.tool.output`):
+- **`duration_ms`** — non-negative wall-clock milliseconds between this tool's invoke and its result, correlated per tool call (host call id when present, else a content hash of `tool_name` + compact `tool_input`). The invoke's start time is recorded on `preToolUse` and read+unlinked on the matching result. It is **`null`** — never a fabricated `0` or a stale value — when the matching start record is absent (a result with no prior recorded invoke). Best-effort and non-blocking; a missing/corrupt start record degrades to `null`. Resolution is millisecond on hosts with a sub-second clock (`$EPOCHREALTIME`/GNU `date +%s%3N`) and second-granular on the portable fallback.
+- **`outcome`** — the deterministic tri-state `pass` | `fail` | `ambiguous` from the canonical observation contract (§2.5), computed in-process by a jq port of `scripts/hooks/evidence-capture.js observeResult` so the Claude hot path stays hermetic (no node subprocess). A `PostToolUseFailure` event folds to `fail`. Never derived from stdout text or model narration. On the Codex runtime only — where the exit code lives in the rollout banner rather than the payload — the code is resolved via `scripts/hooks/lib/codex-exit-code.js` and fed through the same tri-state; an unreadable rollout degrades to `ambiguous`.
+- **`status`** — the host-surfaced integer exit code when one is cleanly present (the same fields §2.5 scans), else **`null`**.
+
+`tool.invoke` and `tool.permission_request` records carry none of these three fields (an invoke has no result yet; a permission request is not a tool result). The three fields are derived scalars only (a timestamp delta, a verdict, an integer) — no args/output/secret material — and the start record stores a bare timestamp, so the console-relay sanitize backstop is unaffected.
+
 ### Redaction Defaults
 
 Telemetry channels redact sensitive payload fields before emission. Adapters must honor these defaults and must not log raw hook payloads without applying channel redaction.
@@ -87,6 +94,27 @@ way.
   supported, it resolves from step 3 onward. Adapters MUST document which manifests they honor so the
   attribution granularity difference is explicit, not surprising.
 
+#### Work-item attribution (`task_slug`)
+
+Where `context.project` groups events by *codebase*, `task_slug` groups them by the *active Builder
+work item* — so the console can report cost and activity per unit of work (the "Cost by work-item"
+breakdown), not just per project.
+
+| Field | Semantics | Redacted? | Producer requirement |
+| --- | --- | --- | --- |
+| `task_slug` | Top-level slug of the Builder run active in `context.cwd` at emission time. | **No** (an opaque work-item slug; carries no path or content) | Adapters SHOULD stamp `task_slug` when a Builder run is active in the working dir. **Omit the field entirely when no run is active — never emit an empty string and never fabricate a slug.** |
+
+Canonical resolution (harness adapter), first match wins, read from the *same* `current.json` the
+economics relay reads so both surfaces attribute to one identifier:
+
+1. `<cwd>/.kontourai/flow-agents/current.json` → `.active_slug`, else `.artifact_dir`.
+2. `<cwd>/.flow-agents/current.json` (legacy location) → `.active_slug`, else `.artifact_dir`.
+3. No file, or both fields empty → **no `task_slug` key on the record.**
+
+Only the slug string is stored; no prompt, args, or file content is ever read into it. A non-Builder
+session (no `current.json`) therefore emits records with no `task_slug`, and the console buckets
+those under "unknown" rather than inventing an attribution.
+
 ### Exit Code Protocol (Canonical Hook Scripts)
 
 Canonical hook scripts in `scripts/hooks/` use the following exit code contract — originally derived from Kiro conventions and shared across all harness adapters via the adapter translation layer:

package/dist/codex/docs/specs/economics-record-contract.md

@@ -156,7 +156,7 @@ from a harness-blind gap (full doctrine + per-runtime matrix in `harness-capabil
 | Field | Meaning |
 | --- | --- |
 | `runtime` | the runtime that produced the record (`claude-code`, `kiro-cli`, …), from `session.usage .agent.runtime` |
-| `per_delegation_tokens` | `true` iff the runtime isolates per-sub-agent tokens. `false` everywhere today → per-delegation cost unavailable |
+| `per_delegation_tokens` | `true` iff the runtime isolates per-sub-agent tokens. **Derived (not a hardcoded literal, #620)** from the runtime's capability declaration — the emitter reads the build-only `build/generated/capability-declarations.json` (generated from `src/lib/capability-declarations.ts`), keys it on the normalized `.agent.runtime` (`kiro-cli`→`kiro`), and emits `true` iff the declared `per_delegation_tokens` status is `supported`. An unresolved runtime or a missing declaration JSON yields the explicit sentinel `false` — never a fabricated `true`. `false` everywhere today → per-delegation cost unavailable |
 | `per_delegation_outcome` | outcome-signal coverage this run: `full`\|`partial`\|`none`\|`n/a` |
 
 Consumers MUST read `signals` before rendering a delegation metric: if the needed signal is unavailable,

package/dist/codex/docs/specs/harness-capability-matrix.md

@@ -3,6 +3,10 @@
 **The signals a feature can rely on depend on which runtime/harness the kit is hooked into. State the
 coverage; never assume it, never fabricate the gap.**
 
+> Generated by `npm run capability-matrix` from `src/lib/capability-declarations.ts` — the single
+> source of truth. Do NOT edit this file by hand; change the declarations and regenerate. CI fails on
+> drift (`npm run capability-matrix -- --check`).
+
 This is a cross-cutting contract: any feature whose data comes from telemetry (economics, delegation
 efficiency, liveness, learning) must declare which signals it needs, which *class* each falls in, and
 how it degrades when the current runtime does not expose one. A missing signal is rendered as
@@ -35,30 +39,67 @@ exposed:
 | Field | Class | Meaning |
 | --- | --- | --- |
 | `runtime` | — | the runtime that produced the record (`claude-code`, `kiro-cli`, `codex`, …) |
-| `per_delegation_tokens` | sub-agent-internal | `true` iff the runtime isolates per-sub-agent token usage. **`false` on every runtime today** → per-delegation cost is unavailable; the console attributes cost at `(role, model)` granularity via `cost.by_model` instead. |
+| `per_delegation_tokens` | sub-agent-internal | `true` iff the runtime isolates per-sub-agent token usage. **`false` on every runtime today** → per-delegation cost is unavailable; the console attributes cost at `(role, model)` granularity via `cost.by_model` instead. Derived from this matrix's `per_delegation_tokens` capability declaration, not a hardcoded literal. |
 | `per_delegation_outcome` | orchestrator-observable | coverage of the outcome signal on this run: `full` (every delegation resolved to a real outcome), `partial` (some), `none` (delegations exist but none had a verdict/escalation/re-dispatch), `n/a` (no delegations observed). |
 
 Consumers (console panels, `learning-review`) MUST read `signals` before rendering a metric: if the
 signal a metric needs is unavailable, show "not measurable on this harness," not a misleading number.
 
-## Per-runtime coverage (current, honest snapshot)
-
-`✓` exposed · `partial` best-effort/orchestrator-derived · `✗` not exposed. Update this table as
-runtimes add instrumentation — it is the single source of truth the `signals` values are stamped from.
-
-| Signal | Class | claude-code | kiro-cli | codex | raw-model runner |
-| --- | --- | --- | --- | --- | --- |
-| whole-run tokens/cost (`by_model`) | run-level | ✓ | ✓ | ✓ | partial |
-| delegation dispatch (role/model) | orchestrator-observable | ✓ | ✓ | partial | ✗ |
-| re-dispatch / re-prompt count | orchestrator-observable | ✓ | ✓ | partial | ✗ |
-| escalation (tier bump) | orchestrator-observable | ✓ | ✓ | partial | ✗ |
-| supersession / correction | orchestrator-observable | partial | partial | ✗ | ✗ |
-| per-sub-agent terminal verdict | mixed | partial | partial | ✗ | ✗ |
-| per-sub-agent tokens/cost | sub-agent-internal | ✗ | ✗ | ✗ | ✗ |
-
-"partial" for verdicts/supersession reflects that these depend on the workflow actually recording an
-`evidence`/`verdict`/`supersession` event for the agent — capturable, but not guaranteed every run.
-That is exactly why `outcome` degrades to `unavailable` rather than `accepted` when the event is absent.
+## Per-runtime capability coverage (generated, honest snapshot)
+
+`✓` exposed · `partial` best-effort/orchestrator-derived · `✗` not exposed. This table is generated
+from `src/lib/capability-declarations.ts`; update the declarations there as runtimes add
+instrumentation — it is the single source of truth the `signals` values are stamped from. The
+`kiro-cli` runtime value normalizes to the canonical `kiro` column before lookup.
+
+| Capability | `claude-code` | `codex` | `kiro` | `opencode` | `pi` | `codex-local` | `strands-local` |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `turn_id` | ✓ | ✓ | ✓ | partial | ✓ | ✗ | ✗ |
+| `transcript_path` | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ |
+| `intent_annotation` | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
+| `per_delegation_trace_context` | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
+| `per_delegation_tokens` | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
+| `terminal_verdict` | partial | ✗ | partial | ✗ | ✗ | ✗ | ✗ |
+
+### Declared notes and reasons
+
+Every `partial` / `✗` cell above, with its declared justification:
+
+- `turn_id` · `opencode` (partial): session.start telemetry is unavailable in opencode run (non-interactive) mode; tool events still carry a turn context.
+- `turn_id` · `codex-local` (unsupported): codex-local is a kit-activation adapter, not an agent-runtime telemetry source; it emits no per-turn agent-runtime telemetry.
+- `turn_id` · `strands-local` (unsupported): strands-local is a kit-activation adapter, not an agent-runtime telemetry source; it emits no per-turn agent-runtime telemetry.
+- `transcript_path` · `opencode` (unsupported): opencode does not expose a per-session transcript path to hooks.
+- `transcript_path` · `pi` (unsupported): pi does not expose a per-session transcript path to hooks.
+- `transcript_path` · `codex-local` (unsupported): codex-local is a kit-activation adapter and does not expose a per-session transcript path.
+- `transcript_path` · `strands-local` (unsupported): strands-local is a kit-activation adapter and does not expose a per-session transcript path.
+- `intent_annotation` · `claude-code` (unsupported): Intent-annotation capture is not implemented on any runtime yet (#622).
+- `intent_annotation` · `codex` (unsupported): Intent-annotation capture is not implemented on any runtime yet (#622).
+- `intent_annotation` · `kiro` (unsupported): Intent-annotation capture is not implemented on any runtime yet (#622).
+- `intent_annotation` · `opencode` (unsupported): Intent-annotation capture is not implemented on any runtime yet (#622).
+- `intent_annotation` · `pi` (unsupported): Intent-annotation capture is not implemented on any runtime yet (#622).
+- `intent_annotation` · `codex-local` (unsupported): Intent-annotation capture is not implemented on any runtime yet (#622).
+- `intent_annotation` · `strands-local` (unsupported): Intent-annotation capture is not implemented on any runtime yet (#622).
+- `per_delegation_trace_context` · `claude-code` (unsupported): Per-delegation trace-context propagation is not implemented on any runtime yet (#425).
+- `per_delegation_trace_context` · `codex` (unsupported): Per-delegation trace-context propagation is not implemented on any runtime yet (#425).
+- `per_delegation_trace_context` · `kiro` (unsupported): Per-delegation trace-context propagation is not implemented on any runtime yet (#425).
+- `per_delegation_trace_context` · `opencode` (unsupported): Per-delegation trace-context propagation is not implemented on any runtime yet (#425).
+- `per_delegation_trace_context` · `pi` (unsupported): Per-delegation trace-context propagation is not implemented on any runtime yet (#425).
+- `per_delegation_trace_context` · `codex-local` (unsupported): Per-delegation trace-context propagation is not implemented on any runtime yet (#425).
+- `per_delegation_trace_context` · `strands-local` (unsupported): Per-delegation trace-context propagation is not implemented on any runtime yet (#425).
+- `per_delegation_tokens` · `claude-code` (unsupported): No runtime isolates per-sub-agent token usage; per-delegation cost is attributed at (role, model) granularity instead.
+- `per_delegation_tokens` · `codex` (unsupported): No runtime isolates per-sub-agent token usage; per-delegation cost is attributed at (role, model) granularity instead.
+- `per_delegation_tokens` · `kiro` (unsupported): No runtime isolates per-sub-agent token usage; per-delegation cost is attributed at (role, model) granularity instead.
+- `per_delegation_tokens` · `opencode` (unsupported): No runtime isolates per-sub-agent token usage; per-delegation cost is attributed at (role, model) granularity instead.
+- `per_delegation_tokens` · `pi` (unsupported): No runtime isolates per-sub-agent token usage; per-delegation cost is attributed at (role, model) granularity instead.
+- `per_delegation_tokens` · `codex-local` (unsupported): No runtime isolates per-sub-agent token usage; per-delegation cost is attributed at (role, model) granularity instead.
+- `per_delegation_tokens` · `strands-local` (unsupported): No runtime isolates per-sub-agent token usage; per-delegation cost is attributed at (role, model) granularity instead.
+- `terminal_verdict` · `claude-code` (partial): Captured only when the workflow records an evidence/verdict event for the sub-agent — not guaranteed every run.
+- `terminal_verdict` · `codex` (unsupported): Codex does not surface a per-sub-agent terminal verdict to the orchestrator.
+- `terminal_verdict` · `kiro` (partial): Captured only when the workflow records an evidence/verdict event for the sub-agent — not guaranteed every run.
+- `terminal_verdict` · `opencode` (unsupported): opencode does not surface per-sub-agent terminal verdicts.
+- `terminal_verdict` · `pi` (unsupported): pi has no named-subagent registry, so per-sub-agent verdicts are not observable.
+- `terminal_verdict` · `codex-local` (unsupported): codex-local is a kit-activation adapter and does not surface per-sub-agent terminal verdicts.
+- `terminal_verdict` · `strands-local` (unsupported): strands-local is a kit-activation adapter and does not surface per-sub-agent terminal verdicts.
 
 ## The doctrine (applies to any telemetry-dependent feature)
 
@@ -70,5 +111,6 @@ That is exactly why `outcome` degrades to `unavailable` rather than `accepted` w
    is not `$0`; an outcome you cannot observe is not `accepted`.
 4. **Fall back to the coarsest honest proxy** when the fine signal is missing (per-delegation cost →
    `(role, model)` via `by_model`), and label the proxy as such.
-5. **Keep this matrix current.** When a harness starts exposing a signal, flip the cell and the
-   `signals` stamp follows — the feature "lights up" without a schema change.
+5. **Keep these declarations current.** When a harness starts exposing a signal, flip the declaration in
+   `src/lib/capability-declarations.ts` and regenerate — the `signals` stamp follows and the feature
+   "lights up" without a schema change.

package/dist/codex/docs/workflow-usage-guide.md

@@ -667,7 +667,10 @@ For unattended runtime re-entry, the active assignment actor may use `workflow d
 explicit runtime adapter argv file. The driver repeats the same public projection/evidence cycle,
 persists its mission turn budget, and parks on adapter-declared PID or deadline barriers instead of
 spending turns while external work is incomplete. Adapter completion never advances a gate by
-self-report; only trust evidence accepted by canonical Flow can change the current step. See
+self-report; only trust evidence accepted by canonical Flow can change the current step. Use
+`--context-policy fresh` when the selected adapter supports canonical fresh-context handoffs and
+the runtime capability profile calls for bounded contexts. This preserves every gate while avoiding
+prior-transcript replay between actions; `warm` remains the default. See
 [`docs/public-workflow-cli.md`](public-workflow-cli.md#bounded-continuation-driver) for the protocol.
 
 If the same Builder slice is interrupted, inspect its canonical status. Resume

package/dist/codex/evals/ci/run-baseline.sh

@@ -11,9 +11,11 @@ mkdir -p "$LOG_DIR"
 
 CHECKS=(
   "Content boundary|npm run check:content-boundary --"
+  "Hachure boundary|npm run check:hachure-boundary --"
   "Decision registry|npm run check:decisions --"
   "Source tree validation|npm run validate:source --"
   "Context map drift|npm run context-map -- --check"
+  "Capability matrix drift|npm run capability-matrix -- --check"
   "Static eval suite|bash evals/run.sh static"
   "Workflow artifact integration|bash evals/integration/test_workflow_artifacts.sh"
   "Workflow artifact cleanup audit integration|bash evals/integration/test_workflow_artifact_cleanup_audit.sh"
@@ -22,6 +24,15 @@ CHECKS=(
   "Workflow sidecar writer integration|bash evals/integration/test_workflow_sidecar_writer.sh"
   "Sidecar field preservation integration|bash evals/integration/test_sidecar_field_preservation.sh"
   "Record-check integration|bash evals/integration/test_record_check.sh"
+  "Narrative source contract integration|bash evals/integration/test_narrative_source_contract.sh"
+  "Narrative runtime projection integration|bash evals/integration/test_narrative_runtime_projection.sh"
+  "Narrative grounded envelope integration|bash evals/integration/test_narrative_grounded_envelope.sh"
+  "Narrative redaction fail-closed integration|bash evals/integration/test_narrative_redaction_failclosed.sh"
+  "Narrative trust isolation integration|bash evals/integration/test_narrative_trust_isolation.sh"
+  "Narrative grounding validator integration|bash evals/integration/test_narrative_grounding_validator.sh"
+  "Narrative prose renderer integration|bash evals/integration/test_narrative_prose_renderer.sh"
+  "Narrative grounded evals integration|bash evals/integration/test_narrative_evals.sh"
+  "Narrative intent annotation integration|bash evals/integration/test_narrative_intent_annotation.sh"
   "Actor identity resolver integration|bash evals/integration/test_actor_identity.sh"
   "CI-runtime actor identity integration|bash evals/integration/test_ci_actor_identity.sh"
   "Assignment provider local-file integration|bash evals/integration/test_assignment_provider_local_file.sh"
@@ -35,6 +46,8 @@ CHECKS=(
   "Liveness console relay integration|bash evals/integration/test_liveness_console_relay.sh"
   "Console tenant isolation integration|bash evals/integration/test_console_tenant_isolation.sh"
   "Goal Fit hook integration|bash evals/integration/test_goal_fit_hook.sh"
+  "Plain stop messaging integration|bash evals/integration/test_plain_stop_messaging.sh"
+  "Goal Fit narrative exclusion integration|env -u FLOW_AGENTS_GOAL_FIT_MODE bash evals/integration/test_goal_fit_narrative_exclusion.sh"
   "Hook category behavior integration|bash evals/integration/test_hook_category_behaviors.sh"
   "Workflow steering hook integration|bash evals/integration/test_workflow_steering_hook.sh"
   "Hook influence contract integration|bash evals/integration/test_hook_influence_cases.sh"
@@ -61,7 +74,13 @@ CHECKS=(
   "Usage and cost integration|bash evals/integration/test_usage_cost.sh"
   "Telemetry usage pipeline integration|bash evals/integration/test_telemetry_usage_pipeline.sh"
   "Telemetry tool usage integration|bash evals/integration/test_telemetry_tool_usage.sh"
+  "Telemetry tool outcome integration|bash evals/integration/test_telemetry_tool_outcome.sh"
+  "Telemetry delegation integration|bash evals/integration/test_telemetry_delegation.sh"
+  "Telemetry action-class integration|bash evals/integration/test_telemetry_action_class.sh"
+  "Telemetry sanitize usage integration|bash evals/integration/test_telemetry_sanitize_usage.sh"
+  "Telemetry task slug integration|bash evals/integration/test_telemetry_task_slug.sh"
   "Economics record integration|bash evals/integration/test_economics_record.sh"
+  "Capability declarations integration|bash evals/integration/test_capability_declarations.sh"
   "Learning review proposals integration|bash evals/integration/test_learning_review_proposals.sh"
   "Utterance check integration|bash evals/integration/test_utterance_check.sh"
   "Pull work provider integration|bash evals/integration/test_pull_work_provider.sh"
@@ -100,9 +119,11 @@ CHECKS=(
 
 LANE_SOURCE_AND_STATIC=(
   "Content boundary"
+  "Hachure boundary"
   "Decision registry"
   "Source tree validation"
   "Context map drift"
+  "Capability matrix drift"
   "Static eval suite"
 )
 
@@ -110,6 +131,15 @@ LANE_WORKFLOW_CONTRACTS=(
   "Workflow artifact integration"
   "Workflow artifact cleanup audit integration"
   "Fixture retirement audit integration"
+  "Narrative source contract integration"
+  "Narrative runtime projection integration"
+  "Narrative grounded envelope integration"
+  "Narrative redaction fail-closed integration"
+  "Narrative trust isolation integration"
+  "Narrative grounding validator integration"
+  "Narrative prose renderer integration"
+  "Narrative grounded evals integration"
+  "Narrative intent annotation integration"
   "Publish-change helper integration"
   "Workflow sidecar writer integration"
   "Sidecar field preservation integration"
@@ -126,10 +156,15 @@ LANE_WORKFLOW_CONTRACTS=(
   "Current.json per-actor integration"
   "Liveness console relay integration"
   "Console tenant isolation integration"
+  "Telemetry tool outcome integration"
+  "Telemetry delegation integration"
+  "Telemetry action-class integration"
 )
 
 LANE_RUNTIME_AND_KIT=(
   "Goal Fit hook integration"
+  "Plain stop messaging integration"
+  "Goal Fit narrative exclusion integration"
   "Hook category behavior integration"
   "Workflow steering hook integration"
   "Hook influence contract integration"
@@ -156,7 +191,10 @@ LANE_RUNTIME_AND_KIT=(
   "Usage and cost integration"
   "Telemetry usage pipeline integration"
   "Telemetry tool usage integration"
+  "Telemetry sanitize usage integration"
+  "Telemetry task slug integration"
   "Economics record integration"
+  "Capability declarations integration"
   "Learning review proposals integration"
   "Utterance check integration"
   "Pull work provider integration"

package/dist/codex/evals/fixtures/narrative-evals/README.md

@@ -0,0 +1,62 @@
+# Grounded narrative evals corpus (#612)
+
+A versioned, frozen-manifest-grounded adversarial fixture corpus and its scorer
+for the narrative faithfulness program. This directory is the shared, externally
+consumable package for the human-study and cross-presentation work in
+kontourai/evals#95: the corpus + result schema are self-describing and can be
+ingested unmodified.
+
+## Package contract
+
+- `corpus.json` (`schema_version: "narrative-evals-corpus/v1"`) enumerates every
+  fixture: its `id`, its `case_class` (one of the ten R1 classes), a declarative
+  `build` recipe (seeded source records materialized through the public
+  `snapshotNarrative` API into a frozen manifest — never a hand-fabricated
+  manifest), and a typed `expected` answer key (`verdict` of `accept` / `reject`
+  / `known_gap`, plus `material_claims`, `epistemic_labels`, and citation
+  resolvability). Corruption fixtures additionally carry a `corruption` block and
+  the named `check` their defect must trip. The serialization references only
+  seeded records and fa1 source IDs, never internal flow-agents APIs.
+- `schemas/narrative-eval-result.schema.json` (`schema_version:
+  "narrative-eval-result/v1"`, at the repo root) is the consolidated result
+  contract: per-fixture verdicts, aggregate faithfulness metrics
+  (unsupported-claim rate, citation precision/recall/resolvability, material-claim
+  coverage, per-class omission rate, epistemic-classification accuracy), an
+  `uncertainty` block (every metric carries a sample count + range), the DECLARED
+  cross-runtime `capability_parity` block, documented `known_gaps`, and per-fixture
+  `raw_source_links` for audit. `validateNarrativeEvalResult` (exported from the
+  package root) is the ajv-free validator.
+- `scorer.mjs` is the hermetic scorer. `node scorer.mjs all` replays the whole
+  corpus and emits one schema-valid `narrative-eval-result/v1` object (write it to
+  a file with `NARRATIVE_EVAL_RESULT_OUT=<path>`); per-check modes
+  (`support` / `citation` / `coverage` / `epistemic` / `injection`) drive the
+  mutation battery. It imports only the BUILT modules under `build/`, so run
+  `npm run build` first.
+
+## Case classes and detection
+
+The ten R1 case classes (`passing`, `failing`, `ambiguous`, `contradictory`,
+`redacted`, `nested-agent`, `timeout`, `no-op`, `created-file`,
+`prompt-injection`) are honest narratives scored `accept`, except the
+`contradictory` case which is disclosed as a documented `known_gap`
+(contradiction detection is an upstream gap, sequenced #568/#425 — it is never
+faked as real detection). Five R3 corruption fixtures (hallucinated statement,
+omitted failure, dangling citation, mislabeled inference, injection-followed
+prose) each carry one deliberate defect the scorer must detect (`reject`). Every
+corruption class is the teeth-proving mutation target for its `/* eval-check:<name> */`
+anchor: `evals/integration/test_narrative_evals.sh` disables each detection in
+turn and proves the matching fixture flips `expected=reject -> actual=accept`,
+then restores the scorer byte-for-byte.
+
+Results are per-corpus MEASUREMENTS, not proofs: no metric is asserted from a
+single fixture, model, or runtime, and capability gaps are asserted from the
+#620 declarations (`queryCapability`), never probed from behavior.
+
+## Running
+
+```sh
+npm run build
+node evals/fixtures/narrative-evals/scorer.mjs all
+# or the full gate (corpus + schema validation + mutation battery):
+bash evals/integration/test_narrative_evals.sh
+```