@kontourai/flow-agents 3.12.1 → 4.1.0

package/dist/opencode/build/src/tools/generate-capability-matrix.js

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+/**
+ * generate-capability-matrix.ts (#620) — the single-source generator (D2).
+ *
+ * ONE render() pass over RUNTIME_CAPABILITY_DECLARATIONS produces BOTH:
+ *   (a) the committed markdown matrix (docs/specs/harness-capability-matrix.md),
+ *       regenerated from the declarations with 7 adapter columns and the ✓/
+ *       partial/✗ vocabulary derived from each capability's union status; and
+ *   (b) a build-only JSON projection (build/generated/capability-declarations.json,
+ *       NEVER committed — build/ is gitignored) that the economics-record emitter
+ *       and hooks read, keyed on canonical runtime id.
+ *
+ * Because both artifacts come from the same object in one pass, markdown/JSON
+ * divergence is impossible by construction. `main(--check)` regenerates the
+ * markdown in-memory and diffs the committed file, exiting nonzero on drift —
+ * mirroring src/tools/generate-context-map.ts's render()/main(--check) precedent.
+ *
+ * Modes:
+ *   (default)     write BOTH the markdown doc and the build-only JSON.
+ *   --check       diff the committed markdown vs a fresh render; nonzero on drift.
+ *   --json-only   write ONLY the build-only JSON (used by the build pipeline so
+ *                 the JSON always exists post-build without mutating the doc).
+ */
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { exists, markdownTable, readText, rel, root, writeText } from "./common.js";
+import { CAPABILITIES, RUNTIME_ADAPTER_IDS, RUNTIME_CAPABILITY_DECLARATIONS, } from "../lib/capability-declarations.js";
+const matrixDocPath = path.join(root, "docs/specs/harness-capability-matrix.md");
+const generatedJsonPath = path.join(root, "build/generated/capability-declarations.json");
+/** ✓ / partial / ✗ glyph for a status (matches the doc's existing 3-state vocabulary). */
+function glyph(status) {
+    switch (status.status) {
+        case "supported":
+            return "✓";
+        case "partial":
+            return "partial";
+        case "unsupported":
+            return "✗";
+    }
+}
+/** The per-cell note/reason for a non-supported status, else "". */
+function detail(status) {
+    if (status.status === "partial")
+        return status.note;
+    if (status.status === "unsupported")
+        return status.reason;
+    return "";
+}
+/** The build-only JSON object: canonical-runtime-id → capability → status. */
+export function buildDeclarationJson() {
+    const out = {};
+    for (const runtime of RUNTIME_ADAPTER_IDS) {
+        const caps = {};
+        for (const capability of CAPABILITIES) {
+            caps[capability] = RUNTIME_CAPABILITY_DECLARATIONS[runtime].capabilities[capability];
+        }
+        out[runtime] = caps;
+    }
+    return out;
+}
+/** Render the full committed matrix markdown from the declarations (deterministic). */
+export function renderMatrixMarkdown() {
+    const headers = ["Capability", ...RUNTIME_ADAPTER_IDS.map((id) => `\`${id}\``)];
+    const rows = CAPABILITIES.map((capability) => [
+        `\`${capability}\``,
+        ...RUNTIME_ADAPTER_IDS.map((runtime) => glyph(RUNTIME_CAPABILITY_DECLARATIONS[runtime].capabilities[capability])),
+    ]);
+    // Per-cell notes/reasons for every non-supported cell, in stable order
+    // (capability outer, adapter inner) so partial/unsupported justifications are
+    // preserved in the generated doc rather than collapsed to a bare glyph.
+    const noteLines = [];
+    for (const capability of CAPABILITIES) {
+        for (const runtime of RUNTIME_ADAPTER_IDS) {
+            const status = RUNTIME_CAPABILITY_DECLARATIONS[runtime].capabilities[capability];
+            const text = detail(status);
+            if (text)
+                noteLines.push(`- \`${capability}\` · \`${runtime}\` (${status.status}): ${text}`);
+        }
+    }
+    return [
+        "# Harness-capability matrix",
+        "",
+        "**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",
+        "**unavailable**, distinct from a real zero — so a consumer never reads \"harness-blind\" as \"measured 0.\"",
+        "",
+        "## The load-bearing distinction: orchestrator-observable vs sub-agent-internal",
+        "",
+        "Not all \"we can't see inside the sub-agent\" gaps are equal. Two classes:",
+        "",
+        "- **Orchestrator-observable** — what our hooks see the *main agent* (the orchestrator) do. The",
+        "  orchestrator knows the prompt it dispatched, how many times it re-dispatched/re-prompted the same",
+        "  sub-agent, its own iteration/route-back count, and when it superseded or corrected a result. Our",
+        "  telemetry observes the orchestrator directly, so **these hold on any runtime that runs our hooks —",
+        "  no sub-agent introspection required.** This is where per-delegation *outcome* comes from.",
+        "- **Sub-agent-internal** — signals that live inside the sub-agent's own turn: its token usage, its",
+        "  internal reasoning, a verdict it computed but never surfaced to the orchestrator. Capturing these",
+        "  requires the harness to expose per-sub-agent instrumentation. **Most harnesses do not today**, so",
+        "  features that need them (e.g. per-delegation *cost*) must declare the signal unavailable and fall",
+        "  back to a coarser, honest proxy.",
+        "",
+        "The practical upshot for #415: we can attribute **outcome** (accepted / rework / diverged / failed) from",
+        "orchestrator-observable behavior even though we cannot attribute **cost** per delegation — because",
+        "tokens are sub-agent-internal and outcome is not.",
+        "",
+        "## The `signals` block",
+        "",
+        "Every `kontour.console.economics` record carries a `signals` object declaring what the emitting runtime",
+        "exposed:",
+        "",
+        ...markdownTable(["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. 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 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.",
+        "",
+        ...markdownTable(headers, rows),
+        "",
+        "### Declared notes and reasons",
+        "",
+        "Every `partial` / `✗` cell above, with its declared justification:",
+        "",
+        ...noteLines,
+        "",
+        "## The doctrine (applies to any telemetry-dependent feature)",
+        "",
+        "1. **Classify each signal** as run-level, orchestrator-observable, or sub-agent-internal. Prefer",
+        "   orchestrator-observable derivations — they are the most portable across harnesses.",
+        "2. **Declare coverage in-band** (a `signals`-style block) so a consumer can distinguish real-zero from",
+        "   harness-blind at read time.",
+        "3. **Degrade to an explicit `unavailable`**, never to a fabricated value. A cost you cannot attribute",
+        "   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 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.",
+        "",
+    ].join("\n");
+}
+/** Write the build-only JSON projection (build/ is gitignored — never committed). */
+function writeGeneratedJson() {
+    writeText(generatedJsonPath, `${JSON.stringify(buildDeclarationJson(), null, 2)}\n`);
+}
+export function main(argv = process.argv.slice(2)) {
+    const check = argv.includes("--check");
+    const jsonOnly = argv.includes("--json-only");
+    const markdown = renderMatrixMarkdown();
+    if (check) {
+        const current = exists(matrixDocPath) ? readText(matrixDocPath) : "";
+        if (current !== markdown) {
+            console.error(`${rel(matrixDocPath)} is stale; run npm run capability-matrix`);
+            return 1;
+        }
+        console.error(`${rel(matrixDocPath)} is current.`);
+        return 0;
+    }
+    writeGeneratedJson();
+    if (jsonOnly) {
+        // Progress/diagnostics go to stderr so stdout stays data-only: this runs inside `npm run build`,
+        // and any downstream `npm run build --silent && node … --json` command would otherwise inherit
+        // this line on stdout and corrupt the JSON its consumer parses.
+        console.error(`Wrote ${rel(generatedJsonPath)}`);
+        return 0;
+    }
+    writeText(matrixDocPath, markdown);
+    console.error(`Wrote ${rel(matrixDocPath)}`);
+    console.error(`Wrote ${rel(generatedJsonPath)}`);
+    return 0;
+}
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try {
+    return fs.realpathSync(fileURLToPath(import.meta.url));
+}
+catch {
+    return fileURLToPath(import.meta.url);
+} })();
+const _argv1RealPath = (() => { try {
+    return fs.realpathSync(process.argv[1]);
+}
+catch {
+    return process.argv[1];
+} })();
+if (_selfRealPath === _argv1RealPath) {
+    process.exitCode = main();
+}

package/dist/opencode/build/src/tools/validate-source-tree.js

@@ -113,10 +113,14 @@ const fixtureOwnerPolicies = new Map([
     ["evals/fixtures/kit-conformance-levels", { owners: ["evals/integration/test_kit_conformance_levels.sh"], classification: "K-level conformance and consumer-target derivation fixtures" }],
     ["evals/fixtures/hook-influence", { owners: ["evals/integration/test_hook_influence_cases.sh", "evals/static/test_workflow_skills.sh", "scripts/validate-hook-influence-cases.js"], classification: "hook influence behavioral cases" }],
     ["evals/fixtures/learning-review-proposals", { owners: ["evals/integration/test_learning_review_proposals.sh"], classification: "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/fixtures/narrative-sources", { owners: ["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"], classification: "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/fixtures/narrative-grounding-validator", { owners: ["evals/integration/test_narrative_grounding_validator.sh"], classification: "narrative grounding validator adversarial fixtures (#623)" }],
+    ["evals/fixtures/narrative-prose-renderer", { owners: ["evals/integration/test_narrative_prose_renderer.sh"], classification: "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/fixtures/narrative-evals", { owners: ["evals/integration/test_narrative_evals.sh"], classification: "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/fixtures/pull-work-provider", { owners: ["evals/integration/test_pull_work_provider.sh"], classification: "work item provider normalization fixtures" }],
     ["evals/fixtures/pull-work-wip-shepherding", { owners: ["evals/static/test_workflow_skills.sh"], classification: "WIP shepherding state fixtures" }],
     ["evals/fixtures/surface-trust", { owners: ["evals/integration/test_workflow_sidecar_writer.sh"], classification: "Surface trust evidence fixtures" }],
-    ["evals/fixtures/telemetry", { owners: ["evals/integration/test_usage_cost.sh", "evals/integration/test_telemetry_usage_pipeline.sh", "evals/integration/test_telemetry_tool_usage.sh"], classification: "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/fixtures/telemetry", { owners: ["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"], classification: "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/fixtures/reconcile-preflight", { owners: ["evals/integration/test_reconcile_preflight.sh"], classification: "#356 reconcile-preflight shape fixtures not already covered by trust-reconcile-exploits (un-superseded disputed critique, standalone disputed session-local claim)" }],
     ["evals/fixtures/trust-reconcile-exploits", { owners: ["evals/integration/test_trust_reconcile_negatives.sh", "evals/integration/test_reconcile_preflight.sh"], classification: "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/fixtures/trust-reconcile-mixed-bundle", { owners: ["evals/integration/test_trust_reconcile_mixed_bundle.sh", "evals/integration/test_reconcile_preflight.sh"], classification: "WS8 trust-reconcile mixed-evidence end-to-end proof fixture; also reused by the #356 reconcile-preflight eval as its CLEAN-BUNDLE (AC4) case" }],

package/dist/opencode/context/contracts/execution-contract.md

@@ -42,7 +42,36 @@ Execution may upgrade to a stronger mode when risk increases. Downgrades require
 - Independent tasks with no shared files can run in the same wave.
 - Shared files, generated artifacts, migrations, and cross-cutting contracts should be serialized unless the plan gives explicit file ownership.
 - Worker delegation must name the exact worker role (`tool-worker`) rather than spawning an unnamed/default implementation agent.
-- After each wave, collect results, check conflicts, and update the session artifact before starting the next wave.
+- After each wave, reconcile results against the wave manifest (below), check conflicts, and update the session artifact before starting the next wave.
+
+## Wave Manifest And Reconciliation
+
+Fan-out collection is machine-checkable, not prose. A reduce step that silently
+drops a worker's stream is worse than one that errors.
+
+- **Declare before dispatch.** Before dispatching a wave that delegates work,
+  declare it in the session's `waves.json` sidecar (schema:
+  `schemas/workflow-waves.schema.json`): `wave_id`, owning step, and one
+  `expected_workers` entry per worker. The expected count (M) must exist before
+  any result arrives.
+- **One terminal record per worker.** Each worker lands exactly one terminal
+  status record: `completed`, `failed`, or `blocked`. Duplicate records and
+  undeclared reporters are validation errors.
+- **Reconcile at wave close.** The orchestrator's collect step is
+  reconcile-against-manifest: record every declared worker that has no terminal
+  record as `not_reported` — never silently absorb a missing worker — then
+  record the wave's `reconciliation` with `expected_count` M, `reported_count`
+  N, and an explicit "N of M reported" summary naming the `not_reported`
+  workers (for example "2 of 3 reported; worker-3 not_reported").
+- **Incomplete is visible, never silent.** A wave is `complete` only when N
+  equals M. An incomplete wave stays visible data and routes to re-dispatch, a
+  blocker report, or an explicit accepted gap; it must never be treated as
+  complete because the missing worker was forgotten.
+- **Enforcement boundary (slice 1).** `validate-workflow-artifacts` enforces
+  the shape and the cross-record arithmetic (counts, exactly-one-record,
+  undeclared reporters, impossible `complete` claims) as data-level validation.
+  Stop-hook refusal of wave completion is #663 part 3 (slice 2), deferred until
+  the hook correctness issues (#453/#450/#494) are resolved.
 
 ## Delegation: Model Routing
 

package/dist/opencode/context/contracts/review-contract.md

@@ -100,6 +100,10 @@ npm run workflow:sidecar -- import-critique .kontourai/flow-agents/<slug> \
   --reviewer tool-code-reviewer
 ```
 
+A security-review finding is recorded as a structured verdict + reference — `{severity, file_refs: ["path:line"], description: "<one-line weakness>"}` — not as reproduced exploit payloads or copied vulnerable-code blocks. A precise reference is sufficient evidence; the fuller remediation detail belongs in the fix pass, not the recorded finding. This keeps security findings recordable even when the reviewer runtime's provider content-filters exploit-shaped prose.
+
+Recording a review requires a reviewer identity distinct from the active implementation-assignment actor (anti-self-review). The identity is derived from the runtime actor, so an orchestrator that implemented cannot also review under the same actor: run the reviewer under a distinct actor — set `FLOW_AGENTS_ACTOR=<reviewer-id>` on the reviewing process, or run it in a separate runtime session.
+
 ## Gate Rules
 
 - Critical or high findings block delivery until fixed, accepted by the user, deferred with explicit rationale, or marked false positive.

package/dist/opencode/context/contracts/trigger-guards.md

@@ -0,0 +1,73 @@
+# Trigger-Spawned Agent Run Guards Contract
+
+> Read [`context/contracts/standing-directives.md`](standing-directives.md) — ratified owner directives that override default engineering conservatism.
+
+Any kit, hook, or integration that spawns an agent run from a trigger MUST declare, before it ships, how that spawn surface is guarded against runaway amplification. A trigger with no dedup, cooldown, cap, or concurrency guard converts one flapping upstream signal into an unbounded stream of agent runs — each of which may hold permissions, spend budget, and mutate state without a human turn in the loop. A 2026-07 field near-miss made this concrete: an on-failure escalation wired without these guards would have spawned a continuous stream of permission-skipping agent runs from a single flapping check. This contract makes the guard requirements standing suite policy so the next trigger-driven feature inherits them by default instead of rediscovering them in an incident.
+
+## Scope
+
+A **trigger-spawned agent run** is any agent execution started by an event rather than by a human request in an interactive session: a check or CI failure escalation, a schedule firing, a watcher or automation trigger, or any other perimeter event that launches headless agent work.
+
+Out of scope:
+
+- `workflow_triggers` in kit.json — in-session workflow steering for an already-running interactive session. Steering routes an existing session; it does not spawn a run.
+- Subagent delegation inside an active, human-initiated session — the session itself is the supervision boundary.
+
+No flow-agents hook spawns agent runs today (all four hook policy classes are advisory/steering), but the suite's perimeter already does, and in-repo consumers are planned (see "Future consumers" below). The contract applies the moment a surface CAN spawn a run, not the moment it misbehaves.
+
+## Required Guard Declarations
+
+Every trigger surface that spawns agent runs declares all four guards, with explicit values. The defaults below are the starting point when the feature has no measured reason to differ; declaring a weaker value than the default requires a recorded rationale on the owning work item.
+
+| Guard | Field | Meaning | Default |
+| --- | --- | --- | --- |
+| Dedup | `dedup_key` | The trigger-signature expression used to suppress duplicate spawns while an equivalent run is pending or was recently spawned. For failure escalations: subject plus normalized failure signature (e.g. `check-name+failure-signature`), so a repeat of the same failure does not spawn a second run. | subject + trigger signature |
+| Cooldown | `cooldown_seconds` | Minimum seconds between spawns for the same subject, regardless of signature churn. | `900` |
+| Daily cap | `daily_cap` | Maximum spawns per trigger surface per day; the surface goes quiet (with a visible, non-silent skip) once reached. | `20` |
+| Concurrency lock | `max_concurrent` | Maximum runs from this surface allowed to exist simultaneously, expressed as a limit; `1` is a mutual-exclusion lock. | `1` |
+
+A skipped spawn (dedup hit, cooldown window, cap reached, lock held) must be observable — logged or counted, never silently dropped — so a guard absorbing real signal is diagnosable.
+
+## Kit Declaration: `agent_spawn_triggers`
+
+Kits declare agent-spawning trigger surfaces in kit.json through the optional `agent_spawn_triggers` extension field (Flow Agents extension-layer metadata, like `dependencies` and `workflow_triggers`):
+
+```jsonc
+"agent_spawn_triggers": [
+  {
+    "id": "on-check-failure",
+    "description": "Escalates failing checks to a headless agent run.",
+    "spawns_agent_runs": true,
+    "guards": {
+      "dedup_key": "check-name+failure-signature",
+      "cooldown_seconds": 900,
+      "daily_cap": 20,
+      "max_concurrent": 1
+    }
+  }
+]
+```
+
+- `id`: unique identifier (`^[a-z0-9]+(?:[.-][a-z0-9]+)*$`).
+- `description`: non-empty human-readable purpose of the surface.
+- `spawns_agent_runs`: required boolean. `false` documents a trigger surface that fires without spawning agent runs (e.g. notification-only); such entries need no guards.
+- `guards`: required-complete when `spawns_agent_runs` is `true` — all four fields, `dedup_key` a non-empty string, the three numeric guards integers >= 1.
+
+Hooks and integrations that live outside a kit manifest declare the same four guards, with the same vocabulary, in their own configuration or design artifact.
+
+## Enforcement
+
+Kit repository validation emits a **WARNING** (not an error) when an `agent_spawn_triggers` entry has `spawns_agent_runs: true` and missing or incomplete `guards`. Malformed declarations (wrong types, duplicate ids, non-positive limits) are shape ERRORS like every other extension field.
+
+Warning-level enforcement is deliberate, declaration-first rollout: the declaration is new and optional, and no in-repo surface spawns runs yet. When the first in-repo trigger-spawned runner ships, its surface must declare complete guards, and enforcement for spawning surfaces hardens with it (validation error and/or runtime refusal). Runtime guard enforcement is explicitly NOT part of this contract's first iteration — no spawning or guard machinery exists in this repo yet, and per standing directive 4 (standalone-first), the enforcement runtime belongs with the first real spawner.
+
+## Conforming Examples
+
+- **kontourai/plumb#1** — check-failure escalation to a headless agent with per-subject cooldown, failure-signature dedup, and a max-concurrent cap: the direct antecedent of this contract's `cooldown_seconds`, `dedup_key`, and `max_concurrent` guards.
+- **ephemeris** — trigger firing that is coalesced per claim, idempotent, and rate-limited: dedup and cap expressed as coalescing plus rate limits, showing the guards generalize beyond failure escalation.
+
+Both are cited as reference implementations of the guard vocabulary; consult their current sources when implementing a new surface.
+
+## Future Consumers
+
+The autonomy epic's background-review fork — kontourai/flow-agents#252, under epic #250 — will spawn agent runs from a trigger. Any implementation of #252 MUST declare its guard configuration under this contract (an `agent_spawn_triggers` entry with complete `guards`, or the equivalent declaration in its owning design artifact) before it ships.

package/dist/opencode/context/scripts/hooks/stop-goal-fit.js

@@ -140,7 +140,7 @@ function walkMarkdown(dir, out = []) {
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
     const full = path.join(dir, entry.name);
     if (entry.isDirectory()) {
-      if (entry.name === 'archive') continue;
+      if (entry.name === 'archive' || entry.name === 'narrative') continue;
       walkMarkdown(full, out);
     } else if (entry.isFile() && entry.name.endsWith('.md')) {
       out.push(full);
@@ -996,7 +996,12 @@ function verifyCommandLogChain(artifactDir) {
     sources.push(entry.source);
     parentSources.set(chain.prevHash, sources);
     if (sources.length > 1) {
-      if (!sources.every(s => s === 'postToolUse-capture')) {
+      // #634: the canonical writer's own execution observations
+      // ('canonical-writer-execution', appended by record-gate-claim under the
+      // same lockfile) legitimately race the PostToolUse capture on the same
+      // tip inside the lock's fail-open window. Both sources are benign fork
+      // siblings; any OTHER source on a shared parent stays tamper.
+      if (!sources.every(s => s === 'postToolUse-capture' || s === 'canonical-writer-execution')) {
         return { status: 'broken', brokenAt: i, forkAt: null };
       }
       if (firstForkAt === null) firstForkAt = i;
@@ -1026,10 +1031,86 @@ function verifyCommandLogChain(artifactDir) {
 // WS8 (AC10b): isRunnableCommandText now lives in ./lib/runnable-command.js (single
 // source of truth shared with workflow-sidecar.ts's record-time validation, #412).
 
+function decodeNarrativeReference(value) {
+  try { return decodeURIComponent(String(value || '')); } catch { return String(value || ''); }
+}
+
+function realpathWithExistingPrefix(candidate) {
+  let cursor = path.resolve(candidate);
+  const suffix = [];
+  while (!fs.existsSync(cursor)) {
+    const parent = path.dirname(cursor);
+    if (parent === cursor) return path.resolve(candidate);
+    suffix.unshift(path.basename(cursor));
+    cursor = parent;
+  }
+  try {
+    const real = fs.realpathSync.native ? fs.realpathSync.native(cursor) : fs.realpathSync(cursor);
+    return path.resolve(real, ...suffix);
+  } catch { return path.resolve(candidate); }
+}
+
+function isNarrativeArtifactContent(bytes) {
+  const text = Buffer.isBuffer(bytes) ? bytes.toString('utf8') : String(bytes || '');
+  try {
+    const value = JSON.parse(text);
+    if (value && typeof value === 'object') {
+      if (value.schema_version === 'grounded-execution-narrative/v1' || value.schema_version === 'grounded-runtime-projection/v1') return true;
+      if (value.schema_version === '1.0' && typeof value.narrative_id === 'string' && typeof value.captured_at === 'string'
+        && value.compiler && typeof value.compiler === 'object' && value.capture_completeness && typeof value.capture_completeness === 'object'
+        && Array.isArray(value.sources)) return true;
+    }
+  } catch { /* non-JSON content may still be a rendered narrative */ }
+  return text.includes('flow-agents-narrative-composer') && text.includes('# Grounded Execution Narrative') && text.includes('## Authority provenance');
+}
+
+function referencesNarrativeNamespace(root, command) {
+  // Static scanning cannot resolve arbitrary runtime shell composition such as
+  // `base=.kontourai; test -f "$base/narrative/..."`. The compensating control
+  // is that command evidence persists only the command, exit status, and an
+  // observed-output digest; it never materializes referenced file bytes. Every
+  // channel that does materialize files is independently content-shape guarded.
+  const decoded = decodeNarrativeReference(command).replaceAll('\\', '/');
+  const foldedCommand = decoded.toLowerCase();
+  if (foldedCommand.includes('.kontourai/narrative')) return true;
+  if (/(?:^|[^A-Za-z0-9._-])\.kontourai(?:\/[^/\s"'`]+)*\/narrative(?:$|[/\s"'`])/.test(decoded.toLowerCase())) return true;
+
+  // A relative narrative path becomes namespace-bearing after a shell `cd`.
+  // Resolve the directory operand, then inspect only the subsequent command.
+  for (const match of decoded.matchAll(/(?:^|[;&|]\s*)cd\s+(?:"([^"]+)"|'([^']+)'|([^\s;&|]+))\s*&&([\s\S]*?)(?=(?:[;&|]\s*cd\s+)|$)/gi)) {
+    const cdTarget = match[1] || match[2] || match[3];
+    const canonicalTarget = realpathWithExistingPrefix(path.isAbsolute(cdTarget) ? cdTarget : path.resolve(root, cdTarget));
+    const foldedTarget = canonicalTarget.replaceAll('\\', '/').toLowerCase();
+    const inKontouraiTree = foldedTarget.endsWith('/.kontourai') || foldedTarget.includes('/.kontourai/');
+    if (!inKontouraiTree) continue;
+    const subsequentTokens = match[4].split(/[\s"'`;|&<>]+/).filter(Boolean);
+    if (subsequentTokens.some(token => /(?:^|\/)narrative\//i.test(token.replaceAll('\\', '/')))) return true;
+  }
+
+  const matches = [...decoded.matchAll(/(?:file:\/\/[^\s"'`;&|<>]+|(?:\.{0,2}\/|\/)[^\s"'`;&|<>]+|[^\s"'`;&|<>]+\/[^\s"'`;&|<>]+)/g)].map(match => match[0]);
+  const tokens = [decoded, ...matches];
+  const canonicalNamespace = realpathWithExistingPrefix(path.join(root, '.kontourai', 'narrative')).toLowerCase();
+  for (let token of tokens) {
+    token = token.replace(/^[('"`]+|[)'"`,:]+$/g, '');
+    if (!token || (token.includes('://') && !token.startsWith('file://'))) continue;
+    if (token.startsWith('file://')) {
+      try { token = new URL(token).pathname; } catch { continue; }
+    }
+    const candidate = realpathWithExistingPrefix(path.isAbsolute(token) ? token : path.resolve(root, token));
+    const folded = candidate.toLowerCase();
+    if (folded === canonicalNamespace || folded.startsWith(`${canonicalNamespace}${path.sep}`)) return true;
+    try {
+      if (fs.statSync(candidate).isFile() && isNarrativeArtifactContent(fs.readFileSync(candidate))) return true;
+    } catch { /* unresolved command tokens are handled by ordinary command validation */ }
+  }
+  return false;
+}
+
 function resolveTrustedCommand(root, artifactDir, check, acceptance) {
   // (a) acceptance criterion command for the matching criterion.
   const fromAcceptance = acceptanceCommandFor(check, acceptance);
   if (fromAcceptance) {
+    if (referencesNarrativeNamespace(root, fromAcceptance)) return { refused: fromAcceptance, refusal: 'narrative trust isolation (#619)' };
     // WS8 (AC10b): never spawn a prose "excerpt" as bash. A kind:"command" ref whose text
     // is not a runnable shell command is malformed-evidence — reported distinctly, not
     // executed, and not conflated with a caught false-completion.
@@ -1070,6 +1151,7 @@ function resolveTrustedCommand(root, artifactDir, check, acceptance) {
   // (c) free-form model command — opt-in only.
   if (String(process.env.FLOW_AGENTS_GOAL_FIT_RECHECK || '').toLowerCase() === 'true') {
     const cmd = normalizeCommand(check && check.command);
+    if (cmd && referencesNarrativeNamespace(root, cmd)) return { refused: cmd, refusal: 'narrative trust isolation (#619)' };
     if (cmd) return { argv: ['bash', '-lc', cmd], cwd: root, source: 'model-command (FLOW_AGENTS_GOAL_FIT_RECHECK)' };
   }
   return null;
@@ -1380,6 +1462,10 @@ function captureCrossReference(root, artifactDir, activeFlowStep) {
       continue;
     }
     const trusted = resolveTrustedCommand(root, artifactDir, check, acceptance);
+    if (trusted && trusted.refused) {
+      warnings.push(`${base} evidence check ${id}: ${trusted.refusal} — command "${safeOneLine(trusted.refused, 120)}" references the narrative namespace and was NOT executed.`);
+      continue;
+    }
     if (trusted && trusted.malformed) {
       // WS8 (AC10b): the matching acceptance criterion named a kind:"command" evidence ref
       // whose text is prose, not a runnable command. Do NOT execute it; classify it.
@@ -2174,7 +2260,7 @@ async function analyze(root, now = Date.now()) {
     warnings.push(`workflow state: canonical Flow run remains active at step ${activeStep}; complete or explicitly cancel the run before stopping.`);
   }
   const blockRe = ((preExecution && !activeFlowRun) || terminal) ? HARD_BLOCK : FULL_BLOCK;
-  const activeTurnAuthority = activeFlowRun && canonicalFlow.state && !unsafeActiveCanonical
+  const activeTurnAuthority = activeFlowRun && !terminal && canonicalFlow.state && !unsafeActiveCanonical
     ? validateActiveTurnAuthority({
       sessionDir: latestArtifactDir,
       runId: process.env.FLOW_AGENTS_CONTINUATION_RUN_ID,
@@ -2192,14 +2278,77 @@ async function analyze(root, now = Date.now()) {
     if (activeTurnAuthority.valid && isOrdinaryActiveGateWarning(w, relPath)) return false;
     return blockingRe.test(w);
   });
-  return { warnings, blocking, activeFlowRun, activeTurnAuthority: activeTurnAuthority.valid, preExecution, gatePrefix: gateLabel(activeFlowStep), latestArtifactDir };
+  return {
+    warnings,
+    blocking,
+    activeFlowRun,
+    activeTurnAuthority: activeTurnAuthority.valid,
+    activeTurnIssuedStep: activeTurnAuthority.valid ? activeTurnAuthority.record.issued_step : null,
+    activeFlowCurrentStep: canonicalFlow.state?.current_step || null,
+    preExecution,
+    gatePrefix: gateLabel(activeFlowStep),
+    warningRelPath: relPath,
+    latestArtifactDir,
+  };
+}
+
+// #659 Slice B: internal Flow-step / expectation vocabulary → plain-English
+// labels, so the human lead below doesn't leak implementation terms.
+const PLAIN_STEP = {
+  'pull-work': 'work selection',
+  'design-probe': 'scoping',
+  plan: 'planning',
+  execute: 'the build',
+  verify: 'final review',
+  'release-readiness': 'release readiness',
+  'learning-review': 'the wrap-up review',
+};
+// Each entry maps a token that appears in the raw warnings to a plain label for
+// "what still needs recording". Order is display order.
+const PLAIN_EXPECTATIONS = [
+  { rx: /clean-critique|critique\.review/, label: 'a reviewer sign-off' },
+  { rx: /acceptance-criteria|acceptance\.criterion/, label: 'the acceptance checks' },
+  { rx: /tests?-evidence|verify\.tests/, label: 'test results' },
+  { rx: /policy-compliance/, label: 'a policy check' },
+];
+
+// #659 Slice A: a plain-language lead for the stop-hook output. Returns a short
+// human summary (what is paused, how many sign-offs remain, the two options), or
+// null when there is no active Builder run to explain. Presentation only — it
+// reads the same `result` the technical block is built from and never mutates it.
+function plainStopLead(result, gapCount) {
+  if (!result || !result.activeFlowRun) return null;
+  const name = result.latestArtifactDir ? path.basename(result.latestArtifactDir) : 'a task';
+  const step = String(result.activeFlowCurrentStep || '').trim();
+  const stepPhrase = PLAIN_STEP[step] || (step ? `the "${step}" step` : 'a checkpoint');
+  const haystack = Array.isArray(result.warnings) ? result.warnings.join('\n') : '';
+  const needs = PLAIN_EXPECTATIONS.filter(e => e.rx.test(haystack)).map(e => e.label);
+  const needsList = needs.length ? ` Still needed: ${needs.join(', ')}.` : '';
+  const count = Number.isFinite(gapCount) && gapCount > 0
+    ? (gapCount === 1 ? '1 sign-off' : `${gapCount} sign-offs`)
+    : 'a few sign-offs';
+  return [
+    `⏸ In plain terms: the task "${name}" is paused at its ${stepPhrase}. ${count} still need recording before it can finish on its own.${needsList}`,
+    `   Two ways forward: let it finish those checks, or cancel the run to close it now. Nothing else you're doing is blocked by this.`,
+    `   (The technical detail below is for the agent/debugging.)`,
+  ].join('\n');
 }
 
 function isOrdinaryActiveGateWarning(warning, relPath) {
+  const normalizedRelPath = relPath.replaceAll('\\', '/');
+  const sessionSlug = path.posix.basename(path.posix.dirname(normalizedRelPath));
+  const canonicalActive = /^workflow state: canonical Flow run remains active at step .+; complete or explicitly cancel the run before stopping\.$/.test(warning);
+  if (HARD_BLOCK.test(warning) && !canonicalActive) return false;
+  const finalAcceptancePrefix = `${sessionSlug} Final Acceptance:`;
+  const currentFinalAcceptance = warning.startsWith(finalAcceptancePrefix)
+    && /^ \d+ acceptance criterion\/criteria still pending; complete CI\/merge\/docs before final delivery\.$/.test(warning.slice(finalAcceptancePrefix.length));
+  const surfaceUnavailable = /^surface unavailable — \d+ high\/critical-impact claim\(s\) could not be re-derived at gate; stored claim status is trusted without independent re-derivation \(fail-closed: high-assurance path\)\. Ensure @kontourai\/surface is installed and importable, or escalate for operator review\.$/.test(warning);
   return warning.startsWith(`${relPath} is still status:`)
     || /(?:^|\/)\.kontourai\/flow-agents\/[^/]+ workflow state:/.test(warning)
     || /(?:^|\/)\.kontourai\/flow-agents\/[^/]+ (?:next action|required skills|required operations|next command):/.test(warning)
-    || /canonical Flow run remains active at step .+; complete or explicitly cancel the run before stopping\.$/.test(warning);
+    || currentFinalAcceptance
+    || surfaceUnavailable
+    || canonicalActive;
 }
 
 function isHardStopWarning(warning, relPath, activeTurnAuthority) {
@@ -2582,9 +2731,33 @@ async function run(rawInput) {
   }
 
   const gatePrefix = result.gatePrefix || '[stop-gate]';
+  const relPath = result.warningRelPath || relative(root, result.latestArtifactDir || root);
+  const remediationWarnings = result.activeTurnAuthority && result.blocking
+    ? result.warnings.filter(w => isHardStopWarning(w, relPath, true))
+    : result.warnings;
+  // A signed continuation turn owns one issued gate action. When a real blocker
+  // requires another model pass, do not mix the next gate's advisory actions into
+  // that remediation prompt: smaller models reasonably treat every visible next
+  // action as authorized work and can cross the driver's fresh-context boundary.
+  const issuedStep = safeOneLine(result.activeTurnIssuedStep || 'unknown', 80);
+  const canonicalStep = safeOneLine(result.activeFlowCurrentStep || 'unknown', 80);
+  const repairBoundary = issuedStep !== canonicalStep
+    ? `Do not perform work for later canonical step "${canonicalStep}" in this turn.`
+    : `Remain within issued step "${issuedStep}" in this turn.`;
+  const repairScope = result.activeTurnAuthority && result.blocking
+    ? ` - continuation repair scope: this signed turn was issued for step "${issuedStep}"; repair only the hard blocker(s) below and return control to the driver. ${repairBoundary}`
+    : null;
+  // #659 Slice A+B: lead with a plain-language summary so a human (not just an
+  // agent) can tell what is paused and what their options are. Presentation only
+  // — derived from the same state, prepended to the output string, and NEVER
+  // folded into remediationWarnings/result.warnings (those feed reasonsHash,
+  // block-dedup, and the HARD_BLOCK detector, which must stay byte-stable).
+  const plainLead = plainStopLead(result, remediationWarnings.length);
   const message = [
+    ...(plainLead ? [plainLead, ''] : []),
     `${gatePrefix} Goal Fit warning:`,
-    ...result.warnings.flatMap(w => {
+    ...(repairScope ? [repairScope] : []),
+    ...remediationWarnings.flatMap(w => {
       const lines = [` - ${w}`];
       const guidance = remediationFor(w);
       if (guidance) lines.push(guidance);
@@ -2598,7 +2771,7 @@ async function run(rawInput) {
   }
 
   const maxBlocks = resolveMaxBlocks();
-  const count = bumpBlockStreak(root, reasonsHash(result.warnings));
+  const count = bumpBlockStreak(root, reasonsHash(remediationWarnings));
   if (count >= maxBlocks) {
     // AC2: never auto-release a HARD block (caught false-completion, capture contradiction,
     // tamper signal, gate misconfiguration, integrity failure). An agent burning through
@@ -2628,7 +2801,7 @@ async function run(rawInput) {
   }
   return {
     stdout: rawInput,
-    stderr: `${message}\n${gatePrefix} Stop blocked — ${result.warnings.length} evidence gap(s) (block ${count}; after ${maxBlocks} identical blocks I stop blocking and hand this to you)`,
+    stderr: `${message}\n${gatePrefix} Stop blocked — ${remediationWarnings.length} evidence gap(s) (block ${count}; after ${maxBlocks} identical blocks I stop blocking and hand this to you)`,
     exitCode: 2,
   };
 }
@@ -2664,4 +2837,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { analyze, run, resolveGoalFitMode, uncheckedInSection, findRepoRoot, sidecarGuidance, safeOneLine, captureCrossReference, bundleEnforcement, loadActiveFlowStep, readCommandLog, resolveTrustedCommand, declaredManifestTarget, verifyCommandLogChain, CHAIN_GENESIS_VERIFY, hasLaunderingOperator, releaseOnNonTerminalStop, isHardStopWarning, canonicalFlowState };
+module.exports = { analyze, run, resolveGoalFitMode, uncheckedInSection, findRepoRoot, sidecarGuidance, safeOneLine, captureCrossReference, bundleEnforcement, loadActiveFlowStep, readCommandLog, resolveTrustedCommand, declaredManifestTarget, verifyCommandLogChain, CHAIN_GENESIS_VERIFY, hasLaunderingOperator, releaseOnNonTerminalStop, isHardStopWarning, canonicalFlowState, plainStopLead };