@kontourai/flow-agents 3.1.0 → 3.3.0

package/docs/index.md

@@ -118,6 +118,10 @@ Use fix-bug. Reproduce the problem, diagnose root cause, implement the fix, and
     <strong>System Guidebook</strong>
     <span>The plain-language map of how Flow Agents is assembled and how it should feel to use.</span>
   </a>
+  <a class="doc-card" href="coordination-guide.html">
+    <strong>Parallel-Session Coordination</strong>
+    <span>Run many sessions against one repo without collisions: the two-stream model (liveness + assignment), the four guard points, the one hard publish fence, and how delivery defends itself.</span>
+  </a>
   <a class="doc-card" href="skills-map.html">
     <strong>Workflow Map</strong>
     <span>See the core skills, gates, artifacts, and route-back behavior.</span>

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

@@ -0,0 +1,108 @@
+---
+title: Flow Agents × Kontour Console
+---
+
+# Flow Agents × Kontour Console
+
+Flow Agents' [coordination substrate](../coordination-guide.md) is **local-first and complete on a
+single machine** — the local liveness stream plus the GitHub `AssignmentProvider` give you full
+parallel-session safety with no server. The **Kontour Console** (`console.kontourai.io`) is the
+**optional fleet tier** layered on top: it never becomes the authority for coordination; it *relays,
+projects, and eventually arbitrates* across machines and teammates.
+
+> This is the design boundary, stated plainly: **single-machine parallelism is fully unlocked
+> locally, for free.** Multi-machine fleets, cross-teammate visibility, human oversight, history, and
+> team-level insight are what the hosted tier adds — and sells. See [ADR 0021 §7](../adr/0021-assignment-leases-and-stale-claim-takeover.md)
+> for the ratifying decision.
+
+**Tracking:** flow-agents epic [#394](https://github.com/kontourai/flow-agents/issues/394) · console
+epic [#123](https://github.com/kontourai/console/issues/123). This doc is the in-repo narrative; the
+issues carry live slice status.
+
+---
+
+## What the Console already is
+
+The Console is a Node/TypeScript monorepo (`console-core` / `console-server` / `console-ui`), backed
+by Postgres (Neon), deployed on Render, running the dogfood instance at `console.kontourai.io`. It
+already ingests and projects agent telemetry:
+
+- **Ingest** — `POST /records` accepts telemetry records; auth via `Bearer` / `X-Console-API-Token`
+  plus `X-Console-Tenant-Id` (tokens configured through `CONSOLE_AUTH_TOKENS_JSON`).
+- **Projection** — `GET /state` returns an `OperatingState` projection; **SSE** streams live updates.
+- **Economics** — per-session cost/usage views (console #117) and an org-scoped registry (#118).
+
+Its multi-tenancy today is **strong at the infrastructure layer** (Postgres primary keys per tenant,
+per-tenant hubs and SSE fan-out) but **weak at the schema layer**: records don't self-identify their
+tenant — tenancy is carried by the request header, not the record body. Closing that gap is part of
+this epic (see *Tenant hardening* below).
+
+## The design invariant: relay, never authority
+
+Two rules keep the Console from compromising the local-first guarantee:
+
+1. **Heartbeats are never written to a provider.** They mirror to the Console relay (the one vantage
+   with global heartbeat visibility) but never to GitHub — rate-limit abuse for no benefit. At most a
+   claim comment refreshes on phase transitions, doubling as board-level progress.
+2. **The advisory stream stays advisory.** The Console projects the same liveness/assignment signals
+   the local substrate computes; in Phase 1 it adds *visibility*, not new authority. Only in Phase 2,
+   opt-in, does a Console-backed `AssignmentProvider` make assignment authoritative across machines —
+   and even then it implements the exact same contract the GitHub/local providers do.
+
+## The phased plan (one epic, two phases)
+
+### Phase 1 — read-only fleet insight (the relay)
+
+Turn per-repo coordination into a team-wide view, without changing where authority lives.
+
+| Slice | Repo | What it does |
+| --- | --- | --- |
+| **ApiSink** ([console #73]) | console | The ingest substrate the relay rides on — the prerequisite. |
+| **Liveness relay** (flow-agents [#295]) | flow-agents | An optional sink: sessions mirror `claim`/`heartbeat`/`release` events to the Console, reusing its idempotent ingest + tenant auth + SSE. Off by default; strictly additive. |
+| **Fleet projection** | console | Active actors, `held`/`reclaimable` subjects, and per-session cost, projected per tenant — the fleet view. |
+| **In-hub janitor** | console | The [coordination janitor](../coordination-guide.md#10-takeover-protocol-forthcoming--294) run centrally: the Console is the one vantage with global heartbeat visibility, so stale-claim reaping for a *fleet* is its natural first cross-machine duty. (Decision: the janitor lives **in the console hub**, not per-client.) |
+
+Phase 1 delivers the "see everyone's active sessions, and your own usage in team context" outcome —
+project/team insight views alongside individual ones — while coordination authority stays exactly
+where it is today (local + GitHub).
+
+### Phase 2 — authoritative fleet coordination
+
+Opt-in, for teams that want cross-machine assignment arbitration:
+
+- **Console `AssignmentProvider`** — a third implementation of the [assignment-provider contract](https://github.com/kontourai/flow-agents/blob/main/context/contracts/assignment-provider-contract.md),
+  making assignment authoritative across machines (not just within one repo's GitHub board). Same
+  `claim`/`release`/`supersede`/`status`/`list` operations; same effective-state join. This is also
+  what lets [verify-hold](../coordination-guide.md#8-guard-point-3--the-verify-hold-publish-gate-the-one-hard-fence)
+  enforce against a *fleet-wide* holder, not just a local one.
+- **Tenant hardening** (console #98–#100) — close the schema-level gap: put an **explicit `tenant_id`
+  on records** (decision) so tenancy is self-describing in the body, not only in the request header,
+  hardening the phased auth model end-to-end.
+- **Native init step** — `flow-agents init` gains a first-class, optional Console-integration step:
+  configure the relay sink, tenant, and (Phase 2) the Console provider at install time, so joining a
+  fleet is a setup choice rather than manual wiring.
+
+## How CI fits (paired with #398)
+
+The [CI-runtime actor identity tier (#398)](https://github.com/kontourai/flow-agents/issues/398) makes
+CI sessions carry a **stable identity** (e.g. `github-actions:<run-id>` plus `GITHUB_ACTOR`/repo/SHA).
+That has two payoffs here: the [verify-hold gate](../coordination-guide.md#1-the-actor-model--who-am-i)
+upgrades from *advisory* to *enforcing* in CI, and CI becomes an **attributable participant** in the
+fleet — its records land in the same Console projections, so team/project/individual insight views
+include automated work, not just interactive sessions. #398 is the keystone that makes the Console
+fleet view whole.
+
+## Dogfooding
+
+`console.kontourai.io` runs from the `console` repo; the deployment lives in `console-deploy` (the
+dogfood instance). Flow Agents development itself is intended to run against it — the fleet view of our
+own parallel Builder sessions is both the first real test and the first sales demo of the tier.
+
+---
+
+## Status
+
+Designed and ratified ([ADR 0021 §7](../adr/0021-assignment-leases-and-stale-claim-takeover.md)); the
+local substrate it builds on is complete (see the [coordination guide](../coordination-guide.md)). Phase
+1 begins with console #73 (ApiSink) → flow-agents #295 (relay). This is forward-looking: no Console
+integration ships in the coordination substrate itself — it is strictly the optional tier above it.

package/docs/integrations/index.md

@@ -49,6 +49,10 @@ The <a href="../spec/runtime-hook-surface.html">Runtime Hook Surface spec</a> de
     <strong>Knowledge Kit Live Example</strong>
     <span>End-to-end proof of the Knowledge Kit ingest + compile flows against a real Strands agent (OllamaModel / qwen3:1.7b). No API key required. Includes acceptance test with telemetry and provenance assertions.</span>
   </a>
+  <a class="doc-card" href="flow-agents-console.html">
+    <strong>Flow Agents × Console</strong>
+    <span>The optional fleet tier over the local coordination substrate: a liveness relay, team/project insight views, an in-hub janitor, and (Phase 2) a Console-backed AssignmentProvider. Local-first stands; the Console never becomes the authority.</span>
+  </a>
 </div>
 
 ---

package/docs/workflow-artifact-lifecycle.md

@@ -19,10 +19,47 @@ npm run workflow-artifact-cleanup-audit -- --artifact-root .flow-agents --json
 
 The default root for local runtime artifacts is `.kontourai/flow-agents`. `.flow-agents` may hold explicit durable Flow Agents config/install state, but it is not a runtime fallback. Move old local sessions with the migration script instead of relying on automatic fallback reads.
 
-The command scans immediate workflow directories, skips non-workflow lanes such as `archive/`, and reports active WIP separately from cleanup candidates, terminal done records, active learning follow-ups, and invalid sidecars. This first slice is dry-run classification only: it does not delete, archive, move, or rewrite runtime artifacts by default, and it has no apply mode.
+The command scans immediate workflow directories, skips non-workflow lanes such as `archive/`, and reports active WIP separately from cleanup candidates, terminal done records, active learning follow-ups, and invalid sidecars.
 
 Use the Current-State Semantics and Local Retention Policy sections below to interpret each bucket. In particular, learning records with `learning.status: followup_required` or any `routing[].status: open` remain active learning follow-ups until every route is completed, opened elsewhere, deferred with a trigger, accepted, or rejected.
 
+## Apply Mode
+
+Dry-run classification is the default and remains a zero-side-effect, read-only pass. Pass `--apply` to actually archive-move the sessions the classifier already puts in `cleanup_candidate` (and aged `terminal_done` sessions past the retention window) out of the active listing:
+
+```bash
+# Dry-run (unchanged; still the default with no flags)
+npm run workflow-artifact-cleanup-audit -- --artifact-root .kontourai/flow-agents
+
+# Archive-move cleanup_candidate / aged terminal_done sessions
+npm run workflow-artifact-cleanup-audit -- --artifact-root .kontourai/flow-agents --apply
+
+# Also archive-move lifecycle-ambiguous and genuinely-stub invalid sessions (second gate)
+npm run workflow-artifact-cleanup-audit -- --artifact-root .kontourai/flow-agents --apply --apply-ambiguous
+
+# Custom retention window and destination
+npm run workflow-artifact-cleanup-audit -- --artifact-root .kontourai/flow-agents \
+  --apply --freshness-window-hours 72 --archive-root /path/to/archive
+```
+
+**Two-gate model.** `--apply` alone only ever moves `cleanup_candidate` sessions and aged `terminal_done` sessions (the same buckets the manual Session Archival Policy procedure in `context/contracts/artifact-contract.md` already selects by hand) — it never touches anything the classifier calls `active_wip`, `active_learning_followup`, or `invalid`. A session the classifier marks `invalid` with an "unrecognized lifecycle shape" reason (a delivered/accepted session whose shape doesn't fit a known terminal pattern, but is otherwise a real, substantive record) is reported separately as **ambiguous** and is moved only when `--apply-ambiguous` is *also* passed — this is a deliberate second opt-in, not a default, because confirming that kind of straggler is genuinely done (e.g. its referenced PR actually merged) is a human/flow judgment call this tool does not make for you (see `--confirm` below).
+
+**Safety rails.** Regardless of flags, `--apply`/`--apply-ambiguous` never touch:
+
+1. **Active work** — `active_wip` and `active_learning_followup` sessions are hard-excluded; no flag combination overrides this.
+2. **A session someone else is holding** — if the local liveness stream shows a fresh claim on a session's slug (any actor, not just the current one), that session is skipped and reported as blocked by a held liveness claim, even if the classifier would otherwise archive it.
+3. **Anything too recent** — a session newer than the freshness window (`--freshness-window-hours`, default 48) is never moved, using `state.json`'s `updated_at` as the primary signal; directory modification time is used only as a fallback when `state.json` is missing or unparsable, never preferred over `updated_at` when it is present (bulk worktree operations can reset file mtimes without touching the actual session content, so mtime alone is not a trustworthy freshness signal).
+4. **Infrastructure directories** — per-agent claim/assignment tracking, the runtime adapter's generated output, the skills catalog, and similar structural directories are recognized by their own shape (they carry their own top-level pointer/lock files, i.e. they are themselves a workflow-sidecar-managed root, not a session) and are never treated as sessions to begin with, so a nested runtime tree with real sub-sessions of its own is never flattened into a single misclassified entry or partially swept.
+5. **Substantive sessions with a schema nit** — an `invalid` session that actually has real `state.json` plus `learning.json` and/or `trust.bundle` content is always report-only, even under `--apply --apply-ambiguous`; only a genuinely empty/stub `invalid` directory (no state at all, or state with no sidecar content) is ever eligible for the ambiguous-archive path.
+
+**Never delete.** Every move is an archive-move (rename, or copy-then-verify-then-remove-source when a plain rename can't cross filesystems) — the tool has no delete capability of any kind, in any mode.
+
+**Where things land.** `--apply` moves matching sessions to `<archive-root>/<date>-<runid>/<slug>/`, where `--archive-root` defaults to a sibling `.kontourai/flow-agents-archive/` next to the artifact root. This is a deliberately *different* destination from the manual, in-tree `<artifact-root>/archive/<slug>/` convention the Session Archival Policy section of `context/contracts/artifact-contract.md` documents for hand-driven moves: giving every automated `--apply` invocation its own dated, run-scoped directory means two same-day runs never collide, and it keeps the artifact root's own scan set immutable while a run is in progress. A human archiving a session by hand may still use the in-tree `archive/<slug>/` path from that section; the two destinations serve the same retirement intent through different (manual vs. automated) procedures — this mode automates the `cleanup_candidate`/aged-`terminal_done` selection that section already specifies, it does not replace the manual path for everything else.
+
+**Manifest.** Any `--apply` run that moves at least one session writes `MANIFEST.md` into that run's archive directory, listing each moved session's slug, classification, last-updated timestamp, and the classifier's own reason text. A run that moves nothing writes no manifest and creates no new archive directory. `--confirm <slug>=<evidence>` (repeatable) lets the invoking human or flow record, verbatim, evidence they already independently gathered (for example, that a straggler's referenced PR is confirmed merged) into that slug's manifest row — a slug moved without a matching `--confirm` entry shows `"none recorded"` rather than a fabricated value. This tool makes no network or `gh` calls itself; it only records evidence it is told.
+
+This is the same procedure a 2026-07-05 live triage sweep of this repo's own `.kontourai/flow-agents/` tree ran by hand before `--apply` existed (see that sweep's own `MANIFEST.md` for the real cases — stale stubs, aged cleanup candidates, confirmed-merged-PR stragglers, and the infrastructure/schema-nit exclusions above) — the sweep's findings are what shaped the safety rails above; `--apply` automates exactly that already-proven procedure.
+
 ## Artifact Lanes
 
 Use one local non-durable lane under `.kontourai/flow-agents/`:

package/evals/ci/antigaming-suite.sh

@@ -35,6 +35,7 @@ TESTS=(
   "evals/integration/test_trust_reconcile_manifest.sh"
   "evals/integration/test_trust_reconcile_mixed_bundle.sh"
   "evals/integration/test_trust_reconcile_negatives.sh"
+  "evals/integration/test_reconcile_preflight.sh"
   "evals/integration/test_goal_fit_ghost_session.sh"
 )
 

package/evals/ci/run-baseline.sh

@@ -22,10 +22,14 @@ 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"
   "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"
   "Assignment provider github integration|bash evals/integration/test_assignment_provider_github.sh"
+  "Stop hook release-with-handoff integration|bash evals/integration/test_stop_hook_release.sh"
   "Pull work assignment join integration|bash evals/integration/test_pull_work_assignment_join.sh"
   "Ensure-session ownership guard integration|bash evals/integration/test_ensure_session_ownership_guard.sh"
+  "Verify-hold gate integration|bash evals/integration/test_verify_hold.sh"
+  "Takeover protocol integration|bash evals/integration/test_takeover_protocol.sh"
   "Current.json per-actor integration|bash evals/integration/test_current_json_per_actor.sh"
   "Goal Fit hook integration|bash evals/integration/test_goal_fit_hook.sh"
   "Hook category behavior integration|bash evals/integration/test_hook_category_behaviors.sh"
@@ -77,10 +81,14 @@ LANE_WORKFLOW_CONTRACTS=(
   "Workflow sidecar writer integration"
   "Sidecar field preservation integration"
   "Actor identity resolver integration"
+  "CI-runtime actor identity integration"
   "Assignment provider local-file integration"
   "Assignment provider github integration"
+  "Stop hook release-with-handoff integration"
   "Pull work assignment join integration"
   "Ensure-session ownership guard integration"
+  "Verify-hold gate integration"
+  "Takeover protocol integration"
   "Current.json per-actor integration"
 )
 

package/evals/fixtures/reconcile-preflight/disputed-critique-unsuperseded.json

@@ -0,0 +1,48 @@
+{
+  "schemaVersion": 5,
+  "source": "reconcile-preflight-fixture:disputed-critique-unsuperseded",
+  "note": "#356 shape 3: an un-superseded workflow.critique.review claim with a 'fail' verdict derives status 'disputed' — session-local-failed divergence (a disputed critique always blocks reconcile unless a later same-reviewer pass superseded it via metadata.superseded_by).",
+  "claims": [
+    {
+      "id": "c-disputed-critique",
+      "claimType": "workflow.critique.review",
+      "value": "fail",
+      "status": "disputed",
+      "subjectId": "reconcile-preflight-fixture/review-1",
+      "facet": "flow-agents.workflow",
+      "subjectType": "workflow-critique",
+      "fieldOrBehavior": "Found a critical security issue in the auth handler.",
+      "createdAt": "2026-07-04T00:00:00Z",
+      "updatedAt": "2026-07-04T00:00:00Z",
+      "impactLevel": "medium",
+      "verificationPolicyId": "policy:workflow.critique.review",
+      "metadata": { "origin": "critique", "reviewer": "tool-code-reviewer", "reviewed_at": "2026-07-04T00:00:00Z" }
+    }
+  ],
+  "evidence": [],
+  "policies": [
+    {
+      "id": "policy:workflow.critique.review",
+      "claimType": "workflow.critique.review",
+      "requiredEvidence": [],
+      "acceptanceCriteria": ["A verified verification event must support a workflow.critique.review claim."],
+      "reviewAuthority": "system",
+      "validityRule": { "kind": "manual" },
+      "stalenessTriggers": [],
+      "conflictRules": [],
+      "impactLevel": "medium"
+    }
+  ],
+  "events": [
+    {
+      "id": "evt-disputed-critique",
+      "claimId": "c-disputed-critique",
+      "status": "disputed",
+      "actor": "flow-agents/workflow-sidecar",
+      "method": "validation",
+      "evidenceIds": [],
+      "createdAt": "2026-07-04T00:00:00Z",
+      "verifiedAt": "2026-07-04T00:00:00Z"
+    }
+  ]
+}

package/evals/fixtures/reconcile-preflight/standalone-disputed-session-local.json

@@ -0,0 +1,59 @@
+{
+  "schemaVersion": 5,
+  "source": "reconcile-preflight-fixture:standalone-disputed-session-local",
+  "note": "#356 shape 4 (the #292/#384 variant): a NON-critique session-local claim (workflow.check.external, human_attestation-backed) with a re-derived status of 'disputed' and no waiver. Distinct from shape 3 (an un-superseded disputed CRITIQUE) only in claimType/subject — both land on the same session-local-failed divergence, proving a disjoint pre-existing failure can never be smuggled in as a standalone claim; the fix hint directs the agent to document it as prose in a waived non-command summary instead.",
+  "claims": [
+    {
+      "id": "c-standalone-disputed",
+      "claimType": "workflow.check.external",
+      "value": "fail",
+      "status": "disputed",
+      "subjectId": "reconcile-preflight-fixture/pre-existing-flaky-integration",
+      "facet": "flow-agents.workflow",
+      "subjectType": "workflow-check",
+      "fieldOrBehavior": "pre-existing integration test failure unrelated to this change",
+      "createdAt": "2026-07-04T00:00:00Z",
+      "updatedAt": "2026-07-04T00:00:00Z",
+      "impactLevel": "high",
+      "verificationPolicyId": "policy:workflow.check.external:human_attestation"
+    }
+  ],
+  "evidence": [
+    {
+      "id": "ev-standalone-disputed",
+      "claimId": "c-standalone-disputed",
+      "evidenceType": "human_attestation",
+      "method": "attestation",
+      "sourceRef": "reconcile-preflight-fixture/evidence.json",
+      "excerptOrSummary": "pre-existing integration test failure, unrelated to this change, observed but not fixed",
+      "observedAt": "2026-07-04T00:00:00Z",
+      "collectedBy": "flow-agents/workflow-sidecar",
+      "passing": false
+    }
+  ],
+  "policies": [
+    {
+      "id": "policy:workflow.check.external:human_attestation",
+      "claimType": "workflow.check.external",
+      "requiredEvidence": ["human_attestation"],
+      "acceptanceCriteria": ["A verified verification event must support a workflow.check.external claim."],
+      "reviewAuthority": "system",
+      "validityRule": { "kind": "manual" },
+      "stalenessTriggers": [],
+      "conflictRules": [],
+      "impactLevel": "high"
+    }
+  ],
+  "events": [
+    {
+      "id": "evt-standalone-disputed",
+      "claimId": "c-standalone-disputed",
+      "status": "disputed",
+      "actor": "flow-agents/workflow-sidecar",
+      "method": "attestation",
+      "evidenceIds": ["ev-standalone-disputed"],
+      "createdAt": "2026-07-04T00:00:00Z",
+      "verifiedAt": "2026-07-04T00:00:00Z"
+    }
+  ]
+}

package/evals/integration/test_checkpoint_signing.sh

@@ -278,14 +278,22 @@ flow_agents_node "$WRITER" init-plan "$SESSION_DIR2/${SLUG2}--deliver.md" \
   --source-request "Test" --summary "Test" \
   --timestamp "2026-06-26T11:01:00Z" >/dev/null 2>&1
 
+# #356: the check-json below carries a real "command" so its test_output evidence
+# has a manifest-matchable execution.label (evidence.execution.label) -- otherwise the new
+# reconcile-preflight gate inside publishDelivery() (#356 Wave 3, AC6) correctly refuses to
+# publish a "kind":"build" claim with test_output evidence but no captured command (a
+# genuinely shape-invalid claim CI's own trust-reconcile.js would ALSO reject -- this is not
+# a preflight-specific false positive, see reconcile-shape.js's finding-1 hardening).
+# TRUST_RECONCILE_COMMANDS makes "node --version" resolve via resolveManifest's legacy
+# fallback tier, matching what a real repo configured with that canonical verify would do.
 flow_agents_node "$WRITER" record-evidence "$SESSION_DIR2" \
   --verdict pass \
-  --check-json '{"id":"build","kind":"build","status":"pass","summary":"build passed"}' \
+  --check-json '{"id":"build","kind":"build","status":"pass","summary":"build passed","command":"node --version"}' \
   --timestamp "2026-06-26T11:02:00Z" >/dev/null 2>&1
 
 # advance-state to delivered: this is the other code path that seals the checkpoint
 SEAL_EXIT=0
-flow_agents_node "$WRITER" advance-state "$SESSION_DIR2" \
+TRUST_RECONCILE_COMMANDS="node --version" flow_agents_node "$WRITER" advance-state "$SESSION_DIR2" \
   --status delivered \
   --phase release \
   --summary "Delivered." \
@@ -298,10 +306,11 @@ else
   _fail "advance-state --status delivered exited $SEAL_EXIT (signing must not break the seal)"
 fi
 
-if [[ -f "$REPO_ROOT2/delivery/trust.bundle" ]]; then
-  _pass "publish-delivery published into the explicit scratch --repo-root ($REPO_ROOT2/delivery/trust.bundle), not process.cwd()"
+# #379: publishDelivery writes to the per-session path delivery/<slug>/trust.bundle.
+if [[ -f "$REPO_ROOT2/delivery/$SLUG2/trust.bundle" ]]; then
+  _pass "publish-delivery published into the explicit scratch --repo-root ($REPO_ROOT2/delivery/$SLUG2/trust.bundle, #379 per-session), not process.cwd()"
 else
-  _fail "publish-delivery did not write to the explicit scratch --repo-root ($REPO_ROOT2/delivery/trust.bundle) — check the --repo-root plumbing in advanceState"
+  _fail "publish-delivery did not write to the explicit scratch --repo-root ($REPO_ROOT2/delivery/$SLUG2/trust.bundle) — check the --repo-root plumbing in advanceState"
 fi
 
 if [[ -f "$SESSION_DIR2/trust.checkpoint.json" ]]; then

package/evals/integration/test_ci_actor_identity.sh

@@ -0,0 +1,221 @@
+#!/usr/bin/env bash
+# test_ci_actor_identity.sh — CI-runtime actor identity tier (issue #398, extends #287; ADR 0021 §2).
+#
+# Proves a CI-triggered session gets a STABLE actor derived from the CI provider's published
+# run/job identifiers, sitting ABOVE process-ancestry and BELOW an explicit override / native
+# runtime session id in resolveActor()'s chain. The payoff: the #293 verify-hold gate now ENFORCES
+# for CI sessions (stable identity) instead of degrading to advisory — the root fix for the CI
+# false-block #293 had to work around.
+#
+# Part A — resolveActor() resolution (pure): stability + byte-identity, precedence (override /
+#   native runtime win), per-provider detection (GitHub, GitLab), conservative generic fallthrough,
+#   recognized-provider-missing-id fallthrough, and env-var injection sanitization.
+# Part B — verify-hold integration: a STABLE CI actor BLOCKS a differing assignment-backed holder
+#   (ENFORCE — contrast the ancestry/advisory case in test_verify_hold.sh §1d), and a CI actor's
+#   OWN claim is recognized as self and PASSES (the reconstruction-seam fix in resolveEnsureSessionActor).
+#
+# Deterministic, no model spend, self-cleaning, no network, no `gh` process anywhere.
+# Usage: bash evals/integration/test_ci_actor_identity.sh
+
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+source "$ROOT/evals/lib/node.sh"
+
+WRITER="workflow-sidecar"
+ACTOR_IDENTITY_HELPER="$ROOT/scripts/hooks/lib/actor-identity.js"
+
+TMPDIR_EVAL="$(mktemp -d)"
+trap 'rm -rf "$TMPDIR_EVAL"' EXIT
+ARTIFACT_ROOT="$TMPDIR_EVAL/artifact-root"
+
+errors=0
+pass() { echo "  [PASS] $1"; }
+fail() { echo "  [FAIL] $1"; errors=$((errors + 1)); }
+
+json_query() {
+  node -e 'const fs=require("fs"); let cur=JSON.parse(fs.readFileSync(process.argv[1],"utf8")); for (const part of process.argv[2].split(".")) cur=part==="length" ? cur.length : (Array.isArray(cur) ? cur[Number(part)] : cur[part]); console.log(cur);' "$1" "$2"
+}
+
+# resolve_field <field:actor|source> <env-assignments...> — run resolveActor under a CLEAN env
+# (only the passed assignments + HOME) so no ambient FLOW_AGENTS_ACTOR/CLAUDE_CODE_SESSION_ID from
+# the eval host leaks into the resolution. Prints the requested field.
+resolve_field() {
+  local field="$1"; shift
+  # env -i gives a CLEAN slate (no ambient FLOW_AGENTS_ACTOR / CLAUDE_CODE_SESSION_ID / real
+  # GITHUB_* from the CI host leaking in); PATH is preserved so `node` resolves.
+  env -i HOME="$HOME" PATH="$PATH" "$@" node -e '
+const { resolveActor } = require(process.argv[1]);
+const r = resolveActor(process.env);
+process.stdout.write(process.argv[2] === "source" ? r.source : r.actor);
+' "$ACTOR_IDENTITY_HELPER" "$field"
+}
+
+# verify_hold_under_ci <dir> <KEY=VAL...> — run verify-hold with a CONTROLLED CI identity.
+# flow_agents_node is a bash FUNCTION (from node.sh), so it cannot be launched via `env -i`; instead
+# run in a subshell that unsets every identity source that would out-rank the CI tier (an explicit
+# override or a native runtime session id — including the eval host's own, since this suite itself
+# runs under a coding agent) and exports the provided CI vars. When this suite runs in real GitHub
+# Actions, the exported fake ids override the ambient real ones so the assertions stay deterministic.
+verify_hold_under_ci() {
+  local dir="$1"; shift
+  (
+    unset FLOW_AGENTS_ACTOR CLAUDE_CODE_SESSION_ID CODEX_SESSION_ID OPENCODE_SESSION_ID PI_SESSION_ID CLAUDECODE
+    while [[ $# -gt 0 ]]; do export "${1?}"; shift; done
+    flow_agents_node "$WRITER" verify-hold "$dir"
+  )
+}
+
+# append_liveness_event / write_assignment_record — the proven fixture writers from
+# test_verify_hold.sh (kept byte-identical in shape so the join fixtures behave the same).
+append_liveness_event() {
+  local root="$1" subject="$2" actor="$3" at="$4" ttl="${5:-1800}"
+  mkdir -p "$root/liveness"
+  node -e '
+const fs = require("fs");
+const evt = { type: "claim", subjectId: process.argv[1], actor: process.argv[2], at: process.argv[3], ttlSeconds: Number(process.argv[4]) };
+fs.appendFileSync(process.argv[5], JSON.stringify(evt) + "\n");
+' "$subject" "$actor" "$at" "$ttl" "$root/liveness/events.jsonl"
+}
+
+write_assignment_record() {
+  local root="$1" slug="$2" sessionId="$3" actorKey="$4"
+  mkdir -p "$root/assignment"
+  node -e '
+const fs = require("fs");
+const [dest, slug, sessionId, actorKey] = process.argv.slice(1);
+const now = new Date().toISOString();
+const actor = { runtime: "github-actions", session_id: sessionId, host: "eval-host" };
+const rec = {
+  schema_version: "1.0", role: "AssignmentClaimRecord", subject_id: slug,
+  actor, actor_key: actorKey, claimed_at: now, ttl_seconds: 1800, branch: "main",
+  artifact_dir: slug, status: "claimed",
+  audit_trail: [{ at: now, transition: "claim", from_actor: null, to_actor: actor, reason: "claim" }],
+};
+fs.writeFileSync(dest, JSON.stringify(rec, null, 2));
+' "$root/assignment/$slug.json" "$slug" "$sessionId" "$actorKey"
+}
+
+# GitHub Actions env used across the file (a single job's stable identifiers).
+GHA=(GITHUB_ACTIONS=true GITHUB_RUN_ID=555 GITHUB_RUN_ATTEMPT=1 GITHUB_JOB=deliver)
+
+echo "=== CI actor identity (#398) ==="
+
+# ─── Part A: resolveActor() resolution ───────────────────────────────────────────────────────
+echo "--- A1. GitHub Actions -> stable ci-runtime actor, byte-identical across invocations ---"
+GH_SRC="$(resolve_field source "${GHA[@]}")"
+GH_ACTOR_1="$(resolve_field actor "${GHA[@]}")"
+GH_ACTOR_2="$(resolve_field actor "${GHA[@]}")"
+[[ "$GH_SRC" == "ci-runtime:github-actions" ]] && pass "source is ci-runtime:github-actions" || fail "source was not ci-runtime:github-actions: '$GH_SRC'"
+[[ "$GH_ACTOR_1" == github-actions:555-1-deliver:* ]] && pass "actor is github-actions:<run>-<attempt>-<job>:<host> ('$GH_ACTOR_1')" || fail "actor shape unexpected: '$GH_ACTOR_1'"
+[[ "$GH_ACTOR_1" == "$GH_ACTOR_2" ]] && pass "actor is byte-identical across repeated invocations (stable)" || fail "actor differed across invocations: '$GH_ACTOR_1' vs '$GH_ACTOR_2'"
+
+echo "--- A2. precedence: explicit override and native runtime session id both WIN over CI ---"
+OVR_SRC="$(resolve_field source "${GHA[@]}" FLOW_AGENTS_ACTOR=alice)"
+[[ "$OVR_SRC" == "explicit-override" ]] && pass "FLOW_AGENTS_ACTOR under CI still resolves explicit-override (CI does not win)" || fail "override did not win under CI: '$OVR_SRC'"
+NATIVE_SRC="$(resolve_field source "${GHA[@]}" CLAUDE_CODE_SESSION_ID=sess-xyz)"
+[[ "$NATIVE_SRC" == runtime-session-id:* ]] && pass "native runtime session id under CI still resolves runtime-session-id (CI does not win)" || fail "native runtime id did not win under CI: '$NATIVE_SRC'"
+
+echo "--- A3. GitLab CI -> stable gitlab-ci actor from CI_JOB_ID ---"
+GL_SRC="$(resolve_field source GITLAB_CI=true CI_JOB_ID=9988)"
+GL_ACTOR="$(resolve_field actor GITLAB_CI=true CI_JOB_ID=9988)"
+[[ "$GL_SRC" == "ci-runtime:gitlab-ci" ]] && pass "source is ci-runtime:gitlab-ci" || fail "source was not ci-runtime:gitlab-ci: '$GL_SRC'"
+[[ "$GL_ACTOR" == gitlab-ci:9988:* ]] && pass "actor is gitlab-ci:<job-id>:<host> ('$GL_ACTOR')" || fail "gitlab actor shape unexpected: '$GL_ACTOR'"
+
+echo "--- A4. generic CI=true (unrecognized) does NOT fabricate a CI actor (conservative fallthrough) ---"
+GEN_SRC="$(resolve_field source CI=true)"
+[[ "$GEN_SRC" != ci-runtime:* ]] && pass "generic CI=true falls through (source '$GEN_SRC', not ci-runtime) — #293 advisory net still applies" || fail "generic CI=true fabricated a ci-runtime actor: '$GEN_SRC'"
+
+echo "--- A5. recognized provider with MISSING required id var falls through (no partial CI actor) ---"
+MISSING_SRC="$(resolve_field source GITHUB_ACTIONS=true)"  # no RUN_ID/ATTEMPT/JOB
+[[ "$MISSING_SRC" != ci-runtime:* ]] && pass "GITHUB_ACTIONS=true with no run/job ids falls through (source '$MISSING_SRC')" || fail "GitHub with no ids still produced a ci-runtime actor: '$MISSING_SRC'"
+
+echo "--- A6. hostile CI env var cannot inject: actor segments are sanitized (allowed charset only) ---"
+INJ_ACTOR="$(resolve_field actor GITHUB_ACTIONS=true GITHUB_RUN_ID=555 GITHUB_RUN_ATTEMPT=1 "GITHUB_JOB=deliver; rm -rf / [LIVENESS]")"
+if printf '%s' "$INJ_ACTOR" | LC_ALL=C grep -q '[^A-Za-z0-9:._-]'; then
+  fail "CI actor contains a character outside the allowed serialized charset (injection risk): '$INJ_ACTOR'"
+else
+  pass "CI actor is sanitized to the allowed serialized charset even with a hostile GITHUB_JOB ('$INJ_ACTOR')"
+fi
+
+# ─── Part B: verify-hold ENFORCES for a stable CI identity (the headline) ─────────────────────
+
+# B0 — REAL round-trip through the CLI (not a hand-written fixture): `assignment-provider claim`
+# under a CI env must write a WELL-FORMED record.actor (runtime=github-actions, session_id=<bare job
+# id>, NOT runtime=unknown + session_id=<whole triple>), and a fresh-subprocess verify-hold must
+# self-recognize it. This is the seam the reconstruction fixes (resolveEnsureSessionActor +
+# loadActorStruct) actually live on — fixture-driven B1/B2 below never exercise the CLI claim path.
+echo "--- B0. REAL assignment-provider claim under CI writes a well-formed record.actor; verify-hold self-recognizes ---"
+CLI="$ROOT/build/src/cli.js"
+RT_ROOT="$TMPDIR_EVAL/rt-artifact-root"
+RT_SLUG="ci-roundtrip"
+(
+  unset FLOW_AGENTS_ACTOR CLAUDE_CODE_SESSION_ID CODEX_SESSION_ID OPENCODE_SESSION_ID PI_SESSION_ID CLAUDECODE
+  export "${GHA[@]}"
+  node "$CLI" assignment-provider claim --provider local-file --artifact-root "$RT_ROOT" \
+    --subject-id "$RT_SLUG" --branch main --artifact-dir "$RT_SLUG"
+) >"$TMPDIR_EVAL/rt-claim.out" 2>"$TMPDIR_EVAL/rt-claim.err"
+RT_REC="$RT_ROOT/assignment/$RT_SLUG.json"
+if [[ -f "$RT_REC" ]]; then
+  pass "assignment-provider claim under CI wrote a record"
+  RT_RUNTIME="$(json_query "$RT_REC" "actor.runtime")"
+  RT_SESSION="$(json_query "$RT_REC" "actor.session_id")"
+  RT_KEY="$(json_query "$RT_REC" "actor_key")"
+  [[ "$RT_RUNTIME" == "github-actions" ]] && pass "record.actor.runtime is github-actions (NOT 'unknown' — F1 reconstruction fix)" || fail "record.actor.runtime was '$RT_RUNTIME', expected github-actions (F1 regressed: loadActorStruct not CI-aware)"
+  [[ "$RT_SESSION" == "555-1-deliver" ]] && pass "record.actor.session_id is the bare CI job id 555-1-deliver (NOT the whole triple — F1 fix)" || fail "record.actor.session_id was '$RT_SESSION', expected 555-1-deliver (F1 regressed)"
+  [[ "$RT_KEY" == github-actions:555-1-deliver:* ]] && pass "record.actor_key is the canonical CI key ('$RT_KEY')" || fail "record.actor_key was '$RT_KEY', expected github-actions:555-1-deliver:<host>"
+else
+  fail "assignment-provider claim under CI wrote NO record: $(cat "$TMPDIR_EVAL/rt-claim.out" "$TMPDIR_EVAL/rt-claim.err")"
+fi
+# Fresh-subprocess verify-hold under the same CI env → the actor written by the real claim is self.
+mkdir -p "$RT_ROOT/$RT_SLUG"
+if verify_hold_under_ci "$RT_ROOT/$RT_SLUG" "${GHA[@]}" >"$TMPDIR_EVAL/rt-vh.out" 2>"$TMPDIR_EVAL/rt-vh.err"; then
+  pass "verify-hold self-recognizes the CI actor from a REAL claim across subprocesses (end-to-end seam)"
+else
+  fail "verify-hold FALSE-BLOCKED the CI actor's own real claim across subprocesses: $(cat "$TMPDIR_EVAL/rt-vh.out" "$TMPDIR_EVAL/rt-vh.err")"
+fi
+[[ "$(json_query "$TMPDIR_EVAL/rt-vh.out" "reason")" == "self_is_holder" ]] && pass "real-round-trip verify-hold reason is self_is_holder" || fail "real-round-trip verify-hold reason was not self_is_holder: $(cat "$TMPDIR_EVAL/rt-vh.out")"
+
+echo "--- B1. a stable CI actor BLOCKS a differing, assignment-backed holder (ENFORCE, not advisory) ---"
+BLOCK_SLUG="ci-verify-hold-block"
+BLOCK_DIR="$ARTIFACT_ROOT/$BLOCK_SLUG"
+mkdir -p "$BLOCK_DIR"
+# Held (fresh) by a clearly different actor -> a durable, assignment-backed conflict.
+write_assignment_record "$ARTIFACT_ROOT" "$BLOCK_SLUG" "other-session" "eval-actor-ci-other-holder"
+append_liveness_event "$ARTIFACT_ROOT" "$BLOCK_SLUG" "eval-actor-ci-other-holder" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" 1800
+# Current actor: a STABLE CI identity (GitHub env), NO FLOW_AGENTS_ACTOR — before #398 this would
+# have fallen to ancestry (unstable) and the gate would have degraded to advisory/PASS.
+if verify_hold_under_ci "$BLOCK_DIR" "${GHA[@]}" >"$TMPDIR_EVAL/ci-block.out" 2>"$TMPDIR_EVAL/ci-block.err"; then
+  fail "verify-hold under a stable CI identity should BLOCK a differing assignment-backed holder (ENFORCE) — got exit 0: $(cat "$TMPDIR_EVAL/ci-block.out" "$TMPDIR_EVAL/ci-block.err")"
+else
+  pass "verify-hold under a stable CI identity BLOCKS a differing assignment-backed holder (the #398 enforce payoff)"
+fi
+[[ "$(json_query "$TMPDIR_EVAL/ci-block.out" "ok")" == "false" ]] && pass "CI-block verify-hold JSON reports ok:false" || fail "CI-block verify-hold JSON did not report ok:false: $(cat "$TMPDIR_EVAL/ci-block.out")"
+CI_BLOCK_REASON="$(json_query "$TMPDIR_EVAL/ci-block.out" "reason")"
+[[ "$CI_BLOCK_REASON" != "actor-identity-unstable-advisory-only" ]] && pass "CI-block reason is NOT the unstable-advisory degradation ('$CI_BLOCK_REASON') — the gate genuinely enforces" || fail "CI actor still degraded to advisory (reason=$CI_BLOCK_REASON) — #398 did not make the CI identity stable"
+
+echo "--- B2. a CI actor's OWN claim is recognized as self and PASSES (the reconstruction-seam fix) ---"
+SELF_SLUG="ci-verify-hold-self"
+SELF_DIR="$ARTIFACT_ROOT/$SELF_SLUG"
+mkdir -p "$SELF_DIR"
+# The holder's actor_key IS the CI actor resolveActor() produces under the GitHub env — so the
+# claim written in one CI step is recognized as self at publish in a later step. If the
+# resolveEnsureSessionActor reconstruction diverged (rebuilt an ancestry struct), this would
+# FALSE-BLOCK — exactly the bug #398 removes.
+write_assignment_record "$ARTIFACT_ROOT" "$SELF_SLUG" "self-session" "$GH_ACTOR_1"
+if verify_hold_under_ci "$SELF_DIR" "${GHA[@]}" >"$TMPDIR_EVAL/ci-self.out" 2>"$TMPDIR_EVAL/ci-self.err"; then
+  pass "verify-hold PASSES when the CI actor is the holder (self recognized across subprocesses — seam fix)"
+else
+  fail "verify-hold FALSE-BLOCKED a CI actor on its OWN claim (the reconstruction seam regressed): $(cat "$TMPDIR_EVAL/ci-self.out" "$TMPDIR_EVAL/ci-self.err")"
+fi
+[[ "$(json_query "$TMPDIR_EVAL/ci-self.out" "ok")" == "true" ]] && pass "CI-self verify-hold JSON reports ok:true" || fail "CI-self verify-hold JSON did not report ok:true: $(cat "$TMPDIR_EVAL/ci-self.out")"
+[[ "$(json_query "$TMPDIR_EVAL/ci-self.out" "reason")" == "self_is_holder" ]] && pass "CI-self verify-hold reason is self_is_holder (the CI actor matched the stored actor_key)" || fail "CI-self verify-hold reason was not self_is_holder: $(cat "$TMPDIR_EVAL/ci-self.out")"
+
+echo ""
+if [[ "$errors" -eq 0 ]]; then
+  echo "ALL CI ACTOR IDENTITY CHECKS PASSED"
+  exit 0
+else
+  echo "$errors CHECK(S) FAILED"
+  exit 1
+fi

package/evals/integration/test_fixture_retirement_audit.sh

@@ -21,9 +21,9 @@ json_query() {
   node -e 'const fs=require("fs"); let cur=JSON.parse(fs.readFileSync(process.argv[1],"utf8")); for (const part of process.argv[2].split(".")) cur=Array.isArray(cur) ? cur[Number(part)] : cur[part]; console.log(cur);' "$1" "$2"
 }
 
-[[ "$(json_query "$TMPDIR_EVAL/audit.json" "totals.scanned")" == "15" ]] && pass "audit scans all fixture groups" || fail "audit scans all fixture groups"
+[[ "$(json_query "$TMPDIR_EVAL/audit.json" "totals.scanned")" == "16" ]] && pass "audit scans all fixture groups" || fail "audit scans all fixture groups"
 [[ "$(json_query "$TMPDIR_EVAL/audit.json" "totals.retire_candidates")" == "0" ]] && pass "audit finds no unowned retire candidates" || fail "audit finds no unowned retire candidates"
-[[ "$(json_query "$TMPDIR_EVAL/audit.json" "totals.kept")" == "15" ]] && pass "audit keeps all owned fixture groups" || fail "audit keeps all owned fixture groups"
+[[ "$(json_query "$TMPDIR_EVAL/audit.json" "totals.kept")" == "16" ]] && pass "audit keeps all owned fixture groups" || fail "audit keeps all owned fixture groups"
 
 node - "$TMPDIR_EVAL/audit.json" <<'NODE'
 const fs = require("node:fs");