@kontourai/flow-agents 3.3.0 → 3.4.0

package/docs/integrations/flow-agents-console.md

@@ -66,6 +66,173 @@ Phase 1 delivers the "see everyone's active sessions, and your own usage in team
 project/team insight views alongside individual ones — while coordination authority stays exactly
 where it is today (local + GitHub).
 
+#### Liveness relay — flow-agents side (shipped)
+
+The flow-agents EMIT half of the relay ships as an **optional, off-by-default** sink
+(`scripts/liveness/relay.sh`). When enabled, each liveness event (`claim`/`heartbeat`/`release`) is
+mirrored to the Console as a `kontour.console.liveness` record over the **same transport core** the
+telemetry mirror uses — `console_post_json` in `scripts/telemetry/lib/transport.sh` (endpoint-allow
+gate, `Authorization: Bearer` + `x-console-tenant-id`, timeouts, detached fire), shared not forked.
+
+It is **strictly local-first** (ADR 0012 §5): the relay fires *after* the durable local
+`liveness/events.jsonl` write, fully detached and best-effort, so it can never block, slow, or fail
+the local emit — and with the flag off or no console configured it is a true no-op. Enable it with:
+
+```
+FLOW_AGENTS_CONSOLE_LIVENESS_RELAY=1
+FLOW_AGENTS_CONSOLE_LIVENESS_ENDPOINT_URL=<console>/records   # or FLOW_AGENTS_CONSOLE_URL / CONSOLE_TELEMETRY_URL + /records
+CONSOLE_TELEMETRY_TOKEN=<bearer>   (or FLOW_AGENTS_CONSOLE_TOKEN_FILE)   ·   CONSOLE_TENANT_ID / FLOW_AGENTS_CONSOLE_TENANT
+```
+
+Untrusted fields (actor, subjectId, branch, artifact_dir) are JSON-escaped by `jq` at record
+construction, so hostile control bytes are `\u`-escaped, never emitted raw.
+
+#### Economics record — flow-agents side (shipped, #349)
+
+Every kit-driven run emits **one per-run economics record** — a `kontour.console.economics` v0.1 fact
+carrying `cost`, `time`, `iterations`, and `defects` caught — so "flow kits save money and produce
+more accurate results" becomes a **measurable, falsifiable** claim. It is the measurement substrate
+for the Kit-economics telemetry initiative and is consumed by the baseline harness (#350), the
+small-model headline (#409), and the console value view (console #117). The full field-by-field
+contract is in [`docs/specs/economics-record-contract.md`](../specs/economics-record-contract.md).
+
+The emitter (`scripts/telemetry/economics-record.sh`) is modeled byte-for-byte on the liveness relay:
+it assembles the record with a **single `jq -c` filter** (valid JSON + `\u`-escaping of every untrusted
+field — `task_slug`, model names, finding text) and hands off to the **same** `console_post_json`
+transport core (endpoint-allow gate, `Bearer` + `x-console-tenant-id`, detached fire), shared not
+forked. It is wired into the telemetry **stop path** (`add_stop_data_and_emit_usage` in
+`scripts/telemetry/telemetry.sh`): right after the `session.usage` event is emitted, the economics
+record is assembled from that event's `.usage` block (token/cost **ground truth** parsed by
+`usage_parse_transcript` from the transcript — never re-estimated) joined with the run's review
+sidecars (`critique.json` for defects, `state.json` for verdict / phase / iterations).
+
+It is **strictly local-first** (ADR 0003 call 6): the record is **always** written to the local
+economics log (`<TELEMETRY_DATA_DIR>/economics.jsonl`) *first*; only then is a **detached, opt-in,
+best-effort** POST fired — a true no-op when the relay flag is off or no console is configured, and
+`exit 0` on every failure path so it can never block, slow, or fail a run. flow-agents emits a per-run
+**fact**, never a rollup — economics aggregation and the value view are console-side **projections**
+over the immutable record stream (ADR 0003 call 3). Tenancy is stamped console-side from the verified
+principal (call 2); the record's `tenant_id` is self-description only. Structurally, `cost` and
+`defects` are **co-required** in the schema (the R7 Goodhart guard) — no consumer can render "cheaper"
+without also rendering "and here is what it caught / missed." Enable the relay with:
+
+```
+FLOW_AGENTS_CONSOLE_ECONOMICS_RELAY=1
+FLOW_AGENTS_CONSOLE_ECONOMICS_ENDPOINT_URL=<console>/records   # or FLOW_AGENTS_CONSOLE_URL / CONSOLE_TELEMETRY_URL + /records
+CONSOLE_TELEMETRY_TOKEN=<bearer>   (or FLOW_AGENTS_CONSOLE_TOKEN_FILE)   ·   CONSOLE_TENANT_ID / FLOW_AGENTS_CONSOLE_TENANT
+```
+
+#### Economics relay config (default-on, opt-out — #469)
+
+Like the telemetry mirror (see the "Owner machine mirror" section of
+[`docs/agent-usage-feedback-loop.md`](../agent-usage-feedback-loop.md)), the economics relay is
+now **config-driven** rather than requiring the env vars above to be exported by hand: once a
+Console telemetry sink is configured (`console_telemetry_url` / `console_telemetry_endpoint_url`
+in a trusted conf), the relay turns on **automatically**. It rides the exact same trusted-conf
+gate as the telemetry mirror — `.kontourai/telemetry-console.conf` or
+`~/.flow-agents/telemetry-console.conf`, mode `600` and owned by the current user — and the same
+`https://`/`localhost` transport allowlist (`console_telemetry_endpoint_allowed` in
+`scripts/telemetry/lib/transport.sh`). The derived endpoint is `<console-origin>/records` — the
+same shared kind-routed ingress the liveness relay uses, and **distinct** from the telemetry
+mirror's `/api/telemetry/records` path. An explicit `console_economics_relay=0` conf key, or
+`install-console-config.sh --no-economics-relay`, opts back out; `console_economics_endpoint_url`
+overrides the derived endpoint when needed. Full resolution order is documented in
+[`docs/specs/economics-record-contract.md`](../specs/economics-record-contract.md#enabling-the-relay-config-driven-opt-out--469).
+
+On the console side, `POST /records` already accepts the `kontour.console.economics` kind into a
+per-tenant `EconomicsStore`, read back via `GET /api/economics` (console #117) — deployed.
+
+#### Attribution & pricing correctness (#487)
+
+Two robustness fixes close the "why is my usage landing `unattributed` at `$0`?" gap that made the
+first hosted-console economics rows misleading:
+
+- **Attribution source.** The stop path stamps the record's `task_slug` and `phase` from the
+  **canonical** active-session file (`.kontourai/flow-agents/current.json`), falling back to the
+  legacy `.flow-agents/` path only when the canonical one is absent — so a run inside a live Builder
+  session lands attributed to the *real* slug/phase, not a stale placeholder. A run with **no** active
+  session is still recorded, but as `unattributed` by design: there is no session to attribute it to,
+  so that is a correct null, not a bug.
+- **Pricing floor.** Cost is resolved from the **bundled** pricing registry
+  (`scripts/telemetry/pricing.json`) as the default source. `pricing.sh` validates that any fetched or
+  cached body is JSON carrying `current_version` + `versions` before trusting it, and never caches a
+  non-JSON body — so a poisoned cache (e.g. a console gate's HTML) or a `401` from an authed pricing
+  endpoint **falls through to the bundled registry** instead of degrading cost to `$0`. `config.sh` no
+  longer silently derives an authed console pricing URL that 401s unauthenticated; the default path
+  uses the valid bundled registry. Net effect: a model the bundled registry can price is **never**
+  recorded at `$0` because of a stale/hostile cache or an unreachable remote.
+
+Both fixes are forward-looking — they correct what future runs emit. Historical `unattributed`/`$0`
+rows already ingested are not retroactively rewritten; that is a console-side data operation.
+
+The paired **console side** — ingesting `kontour.console.liveness`, the fleet OperatingState
+projection (actors + held/reclaimable subjects + last-seen + per-session cost), and the ADR 0021 §4
+janitor — is tracked in the console repo (**console #125**), and feeds the redesigned console
+**Fleet** panel (its per-actor `coordinationState` is already wired to render the pills). Two-machine
+visibility and the janitor sweep are console-side acceptance; this repo ships only the emit half.
+
+#### Multi-tenant install runbook (adding tenant #2 to an existing install)
+
+Installing a second tenant against the same Console instance is a **one-command** operation, with
+either installer entry point:
+
+```
+npx @kontourai/flow-agents init --telemetry-sink kontour-hosted-console --console-tenant <tenant-id> --console-token-file <path>
+```
+
+```
+bash install.sh <workspace> --telemetry-sink kontour-hosted-console --console-tenant <tenant-id> --console-token-file <path>
+```
+
+Both forms drive the same mechanism. `install.sh` collects the Console-related flags into
+`CONSOLE_CONFIG_ARGS` (`install.sh:21,24-27`) and passes them straight through to the installed
+`scripts/telemetry/install-console-config.sh` once the bundle is copied into place (`install.sh:54-55`).
+`flow-agents init`'s `installBundle()` shells out to that same freshly-installed `install.sh` with the
+equivalent flags (`src/cli/init.ts:385-408`); when a raw token value (rather than a file) is supplied,
+`installBundle()` first writes it to a private `mkdtemp` file with `mode: 0o600` before passing
+`--console-token-file` through (`src/cli/init.ts:390-398`), so a bearer token never sits in argv or an
+unprotected file even transiently.
+
+Interactive `flow-agents init` (run without `--yes`/`--headless`) offers a third way to reach this same
+mechanism: a guided "Connect to Kontour Console? [Hosted/Local/Self-hosted/Skip]" prompt that collects
+the token and tenant inline, then ends the install by auto-running the same reachability/token/tenant
+check `flow-agents telemetry-doctor` performs headlessly, folded into a post-install summary. Power
+users who prefer the explicit flag-driven forms above can still use them directly; scripted/CI installs
+(`--yes`/`--headless`) are unaffected by the wizard.
+
+**Token provisioning** is console-side, not flow-agents-side: see the "Ingest" bullet above — tokens
+are configured through `CONSOLE_AUTH_TOKENS_JSON`. Issuing tenant #2 a token, or rotating an existing
+one, is entirely console-repo scope; this repo only ever consumes a token file/value handed to it by
+that process, it does not mint or manage tokens itself.
+
+**Idempotency:** re-running the installer (e.g. to update a tenant's token after rotation, or to add
+`--console-tenant` to an install that didn't originally have one) is safe to repeat. `set_config_key`
+in `install-console-config.sh` (lines 88-100) rewrites `telemetry.conf` by awk-filtering out any
+existing `key=` line for that key and appending the new value, so re-running with the same or updated
+flags updates the same conf keys in place rather than duplicating or appending stale entries.
+
+**Post-install verification:** run
+
+```bash
+flow-agents telemetry-doctor --dest <workspace> --json --headless
+```
+
+and check the `console` block of the report: `tokenConfigured` and `tenantConfigured`
+(`src/cli/telemetry-doctor.ts:208-209`) should both be `true`, and `reachability`
+(`src/cli/telemetry-doctor.ts:210`) should report `ok: true` for a healthy install. A misconfigured
+tenant install typically shows `tenantConfigured: false` (no `--console-tenant` at install time) or
+`reachability.ok: false` (endpoint unreachable, or the token was rejected).
+
+**Isolation proof:** `evals/integration/test_console_tenant_isolation.sh` installs two distinct
+tenants side by side through this exact `install-console-config.sh` → `config.sh` → `transport.sh`
+path against a local HTTP stub, and asserts each tenant's outbound POST carries only its own
+`x-console-tenant-id` and bearer token, never the other's. This proves the **client-side wire
+contract** — that a correctly configured install sends the right headers for the right tenant. It
+does **not** prove server-side tenant isolation or enforcement (that a token cannot be used to read
+another tenant's data); that remains Console-repo scope (console #98–#100 tenant hardening, see
+*Phase 2* below).
+
+
 ### Phase 2 — authoritative fleet coordination
 
 Opt-in, for teams that want cross-machine assignment arbitration:

package/docs/kit-authoring-guide.md

@@ -54,7 +54,7 @@ Required fields:
 | `name` | Non-empty display name |
 | `flows` | Non-empty list; each entry must have `id` and `path` |
 
-Optional fields: `product_name`, `description`, `skills`, `docs`, `adapters`, `evals`, `assets`, `dependencies` (cross-kit dependency declarations; see [Cross-kit dependencies](#cross-kit-dependencies)). Optional fields list relative asset paths or objects with `id`, `path`, and optional `description`. `skills` and `docs` assets are activated by both adapters alongside flows. `adapters`, `evals`, and `assets` appear in diagnostics as `skipped_assets` (see the Activate section for the full per-adapter table).
+Optional fields: `product_name`, `description`, `skills`, `docs`, `adapters`, `evals`, `assets`, `dependencies` (cross-kit dependency declarations; see [Cross-kit dependencies](#cross-kit-dependencies)), `workflow_triggers` (structured workflow steering keyed by engine trigger names such as `implementation-work-detected`), `hook_influence_expectations` (kit-owned required hook-influence fixture expectations), and `first_party` (legacy catalog/marketplace metadata; no runtime privilege). Optional asset fields list relative asset paths or objects with `id`, `path`, and optional `description`. `skills` and `docs` assets are activated by both adapters alongside flows. `adapters`, `evals`, and `assets` appear in diagnostics as `skipped_assets` (see the Activate section for the full per-adapter table).
 
 ## Minimal flow file
 
@@ -181,6 +181,14 @@ When installing through `npx @kontourai/flow-agents init` with the Codex runtime
 npx @kontourai/flow-agents init --runtime codex --dest /path/to/workspace --activate-kits --yes
 ```
 
+`init` activates no kits by default. To activate one or more catalog kits explicitly, pass `--activate-kit <kit-id>` once per selected kit. Declared kit dependencies are auto-included transitively during activation; for example, activating Builder also activates its Knowledge dependency:
+
+```bash
+npx @kontourai/flow-agents init --runtime codex --dest /path/to/workspace --activate-kit builder --yes
+```
+
+`--activate-kits` remains a backwards-compatible alias for selecting every catalog kit.
+
 ## Troubleshooting
 
 Common validation errors and fixes are documented in the [Flow Kit Repository Contract](flow-kit-repository-contract.md#common-failures). The most frequent:
@@ -271,6 +279,42 @@ Where it is checked:
 
 `dependencies` is metadata, not evaluable-gate content, so it does **not** affect K0/K1/K2 conformance scoring (see the K-levels section below).
 
+### Structured workflow triggers
+
+A kit may declare `workflow_triggers` to let the engine route matching prompts into a kit workflow. Triggers do not contain freeform prose. The engine owns the rendered wording and applies the same template to every kit. Every trigger steering field is an identifier and must match `^[a-z0-9]+(?:[.-][a-z0-9]+)*$`; malformed values fail closed and the trigger is skipped.
+
+Shape:
+
+```json
+{
+  "workflow_triggers": [
+    {
+      "id": "builder-build-work",
+      "when": "implementation-work-detected",
+      "target_flow_id": "builder.build",
+      "default_skill": "deliver",
+      "conditional_skills": [
+        { "when": "user-requested-tdd", "skill": "tdd-workflow" }
+      ],
+      "required_sequence": ["plan-work", "execute-plan", "review-work", "verify-work"],
+      "post_verify_targets": ["release-readiness", "learning-review"]
+    }
+  ]
+}
+```
+
+| Field | Rule |
+|---|---|
+| `id` | Required trigger id unique within the kit. |
+| `when` | Required engine trigger category such as `implementation-work-detected` or `knowledge-capture-detected`. |
+| `target_flow_id` | Optional flow id the session should stay on. |
+| `default_skill` | Optional skill id to activate when no conditional skill applies. |
+| `conditional_skills` | Optional list of `{ "when": "...", "skill": "..." }` identifier entries. |
+| `required_sequence` | Optional ordered list of workflow skills or steps the engine should name as the required sequence. |
+| `post_verify_targets` | Optional list of post-verification targets such as release readiness or learning capture. |
+
+The retired `hint` field is invalid. `display_name` is not a workflow trigger field; keep human-readable names in catalog/listing metadata such as top-level `name` or `product_name`. Do not put natural-language steering instructions in kit metadata; express routing needs through the structured identifier fields above.
+
 ### When a kit "is" a Flow Agents Kit
 
 A kit is a **Flow Agents Kit** when it satisfies both layers:
@@ -378,36 +422,23 @@ Every kit carries two independent badges:
 | Axis | Values | Question answered |
 |---|---|---|
 | **Capability** (K-level) | K0 / K1 / K2 | What does the kit CONTAIN? (derived from assets) |
-| **Trust** | first-party / verified / unverified | WHO vouches for it? (derived from provenance) |
+| **Trust** | verified / unverified | WHO vouches for it? |
 
-A K2 kit can be `unverified`. A K0 kit can be `first-party`. The levels are independent.
+A K2 kit can be `unverified`. The levels are independent.
 
-**Marketplace listing format**: `Works with: Flow (gates-only) | K1 | ✓ First-party`
+**Marketplace listing format**: `Works with: Flow (gates-only) | K1 | Official`
+
+`official` / `first_party` is catalog and marketplace metadata only. It grants no runtime privilege: every kit uses the same structured steering mechanism, and no capability decision keys off kit id or load provenance.
 
 ### Trust levels
 
 | Level | Meaning | How it is assigned (v1) |
 |---|---|---|
-| `first-party` | Kontour authored, tested, and ships this kit in the `@kontourai/flow-agents` package. | Kit id is in the internal FIRST_PARTY_KIT_IDS allowlist in `src/flow-kit/validate.ts`. |
 | `verified` | Reserved for a future third-party verification process. | Not yet implemented; the value is reserved but not granted to any kit today. |
-| `unverified` | Default for all kits not explicitly vouched for. | All other kits, including third-party community kits. |
+| `unverified` | Default for all kits. | All current kits, including built-ins and third-party community kits. |
 
 `unverified` says nothing about the quality of a kit — it only means Kontour has not vouched for it through one of the above channels.
 
-### First-party kits (v1)
-
-The first-party allowlist in v1 contains the kits authored by Kontour and distributed with the flow-agents package:
-
-- `builder` — Builder Kit (shape, build, and deliver work)
-- `knowledge` — Knowledge Kit (durable gated knowledge store)
-
-Criteria for a kit to be first-party:
-1. Its directory lives under `kits/` in the `kontourai/flow-agents` repository.
-2. It is published as part of the `@kontourai/flow-agents` npm package.
-3. Kontour owns and maintains the kit's content and release lifecycle.
-
-Third-party forks, community kits, or kits published under a different npm package are NOT first-party even if they share a similar id. First-party is tied to provenance in this specific repository and package.
-
 ### Deferred: verified trust and cryptographic attestation (v2)
 
 The `verified` value is reserved for a future verification process. The intended v2 path:
@@ -438,7 +469,7 @@ npm run kit -- inspect kits/builder
   },
   "targets": ["flow", "flow-agents"],
   "third_party_extensions": [],
-  "trust": "first-party"
+  "trust": "unverified"
 }
 ```
 

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

@@ -0,0 +1,80 @@
+# Builder Flow Runtime
+
+Builder Kit build sessions use Flow as the authority for steps, gates, transitions,
+route-backs, and attempt limits. Flow Agents supplies the agent-facing adapter: it
+starts or loads the canonical run, attaches the session trust bundle, and projects
+Flow's current state into the existing workflow sidecars.
+
+## Ownership Boundary
+
+- Flow persists generated run state under `.kontourai/flow/runs/<run-id>/` and owns
+  Flow Definition evaluation.
+- Builder Kit declares agent actions for each Flow step in `kit.json` under
+  `flow_step_actions`. Actions name skills or product operations; they do not alter
+  Flow transitions or gate outcomes.
+- Flow Agents compiles its kit-level `uses_flow` extension and gate-less `done`
+  sentinel into one Flow-native effective definition. The generated definition is
+  content-addressed under `.kontourai/flow-agents/runtime-definitions/`; Flow then
+  owns all evaluation of that definition.
+- Flow Agents writes product session artifacts under
+  `.kontourai/flow-agents/<slug>/`, produces Hachure trust bundles through Surface,
+  and projects the canonical Flow run into `state.json` and `current.json`.
+- Durable Flow Definitions remain authored under `kits/builder/flows/`. Generated
+  state has no `.flow/runs` fallback.
+
+The adapter contains no benchmark, task, filename, or grader-specific guidance.
+It derives its next action from the persisted Flow step, the current gate's declared
+expectations, and Builder Kit's structured action map.
+
+## Entry And Synchronization
+
+A Builder session must first be created at the Flow Definition's entry step by the
+workflow sidecar. Start the canonical run with:
+
+```bash
+flow-agents builder-run start --session-dir .kontourai/flow-agents/<slug>
+```
+
+`start` requires exactly one `state.work_item_refs` entry and uses that stable Work
+Item reference as the Flow run subject. It is idempotent for an existing canonical
+run. A direct primitive session without a Builder Flow stamp remains independent and
+does not create a Flow run.
+
+After a gate producer writes `trust.bundle`, the sidecar writer synchronizes an
+existing run automatically. Interrupted clients can replay the projected command:
+
+```bash
+flow-agents builder-run sync --session-dir .kontourai/flow-agents/<slug>
+```
+
+Synchronization is digest-idempotent. The same trust bundle is not attached twice.
+Inspection loads the run without evaluating it, so invalid evidence is rejected
+before Flow mutation.
+
+## Trust Binding
+
+Claims relevant to the current gate must carry
+`metadata.workflow_subject_ref` equal to the persisted Flow run subject. Unrelated
+claims are ignored for that gate. A relevant claim with a missing or different
+subject reference is rejected; Flow is not mutated.
+
+A failed gate claim may include a Flow classifier through
+`record-gate-claim --status fail --route-reason <reason>`. Flow validates the reason
+against the gate's `on_route_back` map and owns both the destination and attempt
+budget. Flow Agents only projects the resulting attempt and maximum into `state.json`.
+
+## Agent Projection
+
+While a run is active, `state.json` contains:
+
+- `flow_run`: canonical run identity, current step, open gates, run reference, and
+  route-back attempt information when present.
+- `next_action.skills`: ordered Builder skills for the current step.
+- `next_action.operations`: ordered non-skill product operations when present.
+- `next_action.summary`: required gate claims derived from the Flow Definition.
+- `next_action.command`: the exact idempotent synchronization command.
+
+Workflow steering surfaces these fields on session start and prompt submission. The
+Stop hook treats an unfinished canonical Flow run as active even during pickup or
+planning, blocks a premature stop in block mode, and does not release its liveness
+claim. A run is complete only when Flow reaches its terminal step.

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

@@ -45,6 +45,46 @@ Telemetry channels redact sensitive payload fields before emission. Adapters mus
 
 These defaults are configurable via `TELEMETRY_CHANNEL_FULL_REDACT` and `TELEMETRY_CHANNEL_ANALYTICS_REDACT` environment variables.
 
+### Attribution Fields (canonical, all adapters)
+
+Because `context.cwd` is redacted on the analytics/console relay (the full local path must never
+leave the machine), adapters cannot rely on the consumer deriving a project name from it. So the
+attribution label is itself canonical and every adapter — harness **and** framework — must produce it:
+
+| Field | Semantics | Redacted? | Producer requirement |
+| --- | --- | --- | --- |
+| `context.project` | Coarse, path-free project label identifying the project a session is working in. | **No** (path-free by construction; safe to relay) | Adapters SHOULD populate `context.project` before emission when `context.project` is not already set, using the **canonical derivation precedence** below. Never send the full path. |
+
+**Canonical derivation precedence (all adapters MUST resolve in this order, first match wins).** A
+bare `basename(cwd)` is *not* sufficient — folder names differ between developers, clones, and
+worktrees, so the same project would report inconsistent labels. Resolve most-stable-first:
+
+1. `FLOW_AGENTS_PROJECT` — explicit operator override; always wins.
+2. **Nearest project manifest name** walking up from the working dir — `package.json` `name` today
+   (monorepo-granular *and* committed, so every developer of the same package resolves the same
+   label). Other ecosystems (`pyproject.toml`, `Cargo.toml`, `go.mod`, …) extend this step — see
+   the consistency callout.
+3. **Git remote `org/repo`** (from `remote.origin.url`, `.git` stripped, path-free) — repo-level
+   identity that is stable across clones and worktrees.
+4. **Git toplevel directory basename** — the repo dir even when invoked from a worktree or subdir.
+5. **`basename(cwd)`** — last resort.
+
+Derivation is deterministic for a given working tree, so adapters SHOULD compute it once per
+project per session and cache it rather than re-resolving per event.
+
+Consumers (the console projection) prefer `context.project` and fall back to `basename(context.cwd)`
+only when a non-redacted cwd is present. This keeps project attribution consistent across every
+runtime — a Claude Code shell hook and an in-process Strands adapter derive the same label the same
+way.
+
+**Consistency callouts (features that cannot be identical across runtimes — surface, don't hide):**
+- A runtime that exposes no working directory cannot resolve steps 2–5 and attributes to "unknown"
+  by design; that gap must be surfaced, not silently bucketed (§"Degradation when host lacks
+  trigger").
+- Step 2's manifest matrix is inherently language-specific. Until an adapter's ecosystem manifest is
+  supported, it resolves from step 3 onward. Adapters MUST document which manifests they honor so the
+  attribution granularity difference is explicit, not surprising.
+
 ### 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:
@@ -198,7 +238,11 @@ Flow Agents currently ships five canonical policy classes. Each policy class has
 { "command": "npm test", "observedResult": "pass", "exitCode": 0, "capturedAt": "2026-06-23T00:00:00Z", "source": "postToolUse-capture" }
 ```
 
-**Exit-code handling (deterministic observation only)**: a clean integer exit code is host-dependent. The policy extracts the real exit code where the host surfaces one (`tool_response`/`tool_output` `.exitCode`/`.exit_code`/`.status`/`.code`/`.returnCode`, or top-level equivalents) and sets `observedResult` to `pass` iff that code is `0`. When no clean integer exit code is present, `exitCode` is recorded as `null` and `observedResult` is inferred *only* from deterministic failure signals — a non-empty `error`, a `success:false`/`failed:true`/`is_error:true` flag, or a non-empty stderr with no stdout. Plain stdout text is never scanned for the words "error"/"fail"; the model's narration is never consulted.
+**Exit-code handling (deterministic observation only)**: a clean integer exit code is host-dependent. The policy extracts the real exit code where the host surfaces one (`tool_response`/`tool_output` `.exitCode`/`.exit_code`/`.status`/`.code`/`.returnCode`, or top-level equivalents) and sets `observedResult` to `pass` iff that code is `0`. When no clean integer exit code is present, `exitCode` is recorded as `null` and `observedResult` is inferred *only* from deterministic failure signals — a non-empty `error`, a `success:false`/`failed:true`/`is_error:true` flag, or a non-empty stderr with no stdout. When no clean integer exit code is present AND no deterministic failure signal exists, `exitCode` is recorded as `null` and `observedResult` is **`ambiguous`** — never `pass`. A `pass` always requires positive evidence (a clean integer exit code of 0; no host currently surfaces a positive success flag). Plain stdout text is never scanned for the words "error"/"fail"; the model's narration is never consulted.
+
+**Consumer semantics of `ambiguous`**: `ambiguous` is non-confirming everywhere it is consumed — it never confirms a claimed pass and never itself resolves to a `verified` event, regardless of which runtime or extraction path produced it. `workflow-sidecar`'s trust-bundle build (`reduceCaptureLogByCommand` / `captureByCommand`) maps a command-log `ambiguous` capture to the existing canonical `not_verified` status — the same status record-check already uses for an ambiguous grep/diff exit — so the evidence item is `passing:false` and no `verified` event is ever emitted for it. `stop-goal-fit` (§2.3) further distinguishes the ORIGIN of an ambiguous capture: the absence-ambiguous case (a bare `grep`/`diff` that exited exactly `1`, which re-running yields no new information for) keeps its grep/diff-flavored `NOT_VERIFIED (ambiguous)` message and HARD_BLOCKs a terminal stop; a generic no-signal-ambiguous capture — no exit code observed at all, e.g. an unreadable Codex rollout banner or a bounded read that exceeded its caps — gets a grep/diff-free `NOT_VERIFIED —` message that is warn-only at a terminal stop but still blocks a non-terminal (in-flight) stop via the same `NOT_VERIFIED —` pattern. Neither path ever demotes to a confirmed `pass`.
+
+**Codex host-banner carve-out**: On the Codex runtime, the host serializes the real exit code as host-generated prose (`Process exited with code N`) inside the tool result / session rollout rather than as a structured field (observed on codex-cli 0.142.5). The codex ADAPTER (`scripts/hooks/codex-hook-adapter.js`, scoped to the evidence-capture invocation on `postToolUse` only) extracts exactly that banner and injects it as a structured `tool_response.exitCode` BEFORE capture observes; this is a deterministic HOST signal (host-authored fixed format), not narration scanning — capture itself still never scans stdout or model narration. Extraction (`scripts/hooks/lib/codex-exit-code.js`) is **preamble-anchored**: the banner in a `function_call_output.output` string sits in the HOST-authored preamble, before the model's own stdout, which the codex CLI appends after a literal `Output:` delimiter; extraction matches the banner only in the portion BEFORE that delimiter (the FIRST match when no delimiter is present) and never scans the post-delimiter model stdout, so a command that deliberately prints a forged `Process exited with code 0` to its own stdout cannot override the real host-reported code. Reads are **head-anchored and bounded**: the target rollout line is located via a bounded backward scan (default 1MB), and only the first ~64KB of that line is read/parsed — the preamble/banner lives within the first few hundred bytes of the `output` field regardless of how much model stdout follows, so a >64KB flood of stdout after the banner can never displace it out of the read window; beyond either bound, extraction yields no signal (`null` → the `ambiguous` default above), never a guess. Extraction **correlates or declines** rather than blindly trusting the newest rollout entry: a payload-carried call_id match is authoritative when present; absent that, the newest `function_call_output` is cross-checked against its paired `function_call`'s command, and a resolvable match uses it while a resolvable **mismatch DECLINES to no signal** (never attributes another call's exit code); only when no correlation signal exists at all (the common single-call case) does it fall back to the newest banner. The `transcript_path` is resolved through `realpath` and required to be a regular file — and, when the codex sessions root itself is resolvable, contained within it — before any read. Extraction is fail-open throughout (missing/unreadable rollout, an unresolvable line, a declined correlation, or no banner → no injection → the `ambiguous` default above, subject to the consumer semantics described above).
 
 **Decision contract**: Non-blocking. Always exits 0 and echoes stdin. Idempotent/append-only. Fail-open on any error — a capture failure must never block the agent or corrupt the log. Only records when an active workflow artifact dir resolves (otherwise there is nothing to anchor the log to).