@kontourai/flow-agents 3.1.0 → 3.3.0

package/docs/adr/0022-fail-closed-delivery-reconciliation-with-governed-exemptions.md

@@ -463,3 +463,114 @@ the workflow to fake the post-merge no-op path; this is closed by required code-
 review on `.github/workflows/trust-reconcile.yml` (#225, not yet server-side enforced),
 the same residual class as every other self-asserted CI input this ADR already carries.
 Step 1 (fresh verify) is unaffected by event scoping either way and always runs.
+
+## Addendum (2026-07-04, part 5): per-session delivery paths — concurrent deliveries stop contending (#379)
+
+Owner-approved follow-up closing a structural defect the fail-closed gate's first real
+deliveries surfaced repeatedly: the delivery transport used a SINGLE shared path
+(`delivery/trust.bundle` + `delivery/trust.checkpoint.json`), so every sealed delivery
+force-committed to the SAME two files. Any two concurrent deliveries therefore
+merge-conflict by construction — three seal collisions inside 24h (#330, #358, #378) each
+needed manual conflict resolution. Worse than the conflict itself: **GitHub schedules NO
+`pull_request` workflows for a conflicting (DIRTY) PR** — zero checks, no error — so the
+required Trust Reconcile check silently never re-runs. The symptom reads as "CI vanished,"
+not "conflict." This collision class scales with delivery frequency; ADR 0021's own "work
+area" vocabulary predicted it, and #335 named the `resolveDeliveryCandidates()` seam as the
+fix site.
+
+**Decision (structural): per-session delivery paths.** `publishDelivery()`
+(`src/cli/workflow-sidecar.ts`) writes to `delivery/<slug>/trust.bundle` (+ checkpoint
+companions), where `<slug>` is the session artifact dir's basename, instead of the shared
+flat path. Concurrent deliveries write to DISTINCT files and cannot contend: two deliveries
+add different `delivery/<slug>/` dirs (add/add of different paths — not a conflict), and both
+deleting the same inherited flat/legacy file is a delete/delete (auto-merges — not a
+conflict). The per-session dir NAME is only a collision-avoidance handle; it carries no
+trust weight.
+
+**Reconciler side: ownership-aware discovery, prefer-newest, not first-match.**
+`resolveDeliveryCandidates()` now returns the flat path (FIRST, for full back-compat)
+followed by every `delivery/<slug>/<filename>` (sorted). `discoverBundle()` no longer returns
+the first-existing candidate; it collects every candidate that attests THIS change
+(ancestor-or-equal, the SAME `bundleAttestsThisChange()` binding Addendum part 2 defined) and
+selects the one attesting the **NEWEST** (descendant-most) commit. This prefer-newest rule is
+load-bearing in a **merge-commit** repo (this repo's own history has merge commits, e.g.
+release-please merges): an inherited FLAT bundle's `commit_sha` can be a REAL ancestor of HEAD
+— it was committed on the trunk's linear history before this branch point — so it legitimately
+"owns" the change too, and a naive first-fresh-wins would select that STALE inherited bundle
+purely because it sorts first, reconciling the PREVIOUS delivery's claims against THIS change's
+CI. Prefer-newest makes the fresh per-session bundle win on recency, not on being deleted
+first — which in turn is what lets the cleanup policy leave the flat path in place (below)
+without corrupting selection. (Addendum parts 2/4's squash-merge reasoning still holds for
+squash repos; prefer-newest is the strict generalization that also covers merge-commit repos,
+where "inherited ⇒ non-ancestor" is NOT guaranteed.) `extractBundleCommitSha()` now resolves a
+bundle's sibling checkpoint from the bundle's OWN directory (`path.dirname(bundlePath)`), not a
+global scan — a global scan would pair a per-session bundle with the wrong session's (or the
+flat) checkpoint and read the wrong commit binding. For the flat layout this is byte-identical
+to the prior behavior; for per-session it is the only correct pairing.
+
+**Back-compat (retained, deprecation-noted).** The flat `delivery/trust.bundle` path stays
+fully supported on the READ side: an already-committed flat bundle from before this change,
+or an external adopter that has not migrated, still resolves and reconciles exactly as
+before (regression-locked by the negatives suite's flat-owner-coexist case and the
+unchanged `test_publish_delivery.sh` TEST 3/4 flat-fixture cases). Only the WRITE side moved
+to per-session — writing to both flat and per-session would re-introduce the very contention
+this closes, so the flat path is write-deprecated, read-supported.
+
+**Cleanup policy: supersede-on-publish, per-session dirs only (delivery/ stays bounded).** A
+publishing session prunes every inherited **per-session** seal dir except its own, then
+commits only `delivery/<slug>/`. Per-session dirs are the growth vector (one per delivery) and
+are UNIQUELY named, so pruning one can never conflict with a concurrent PR: two branches
+deleting the same inherited dir is a delete/delete (auto-merges), and each delivery adds its
+own distinct dir. Leaving an inherited per-session dir would be harmless anyway (prefer-newest
+ignores it) — pruning is purely to stop unbounded accumulation. The alternative,
+retain-as-history, was rejected as unbounded growth of permanently-superseded dirs with no
+reader. Pruning is best-effort: a prune failure is logged, never fatal to the delivery.
+
+**The shared flat path is deliberately NOT pruned per-delivery.** An earlier iteration of this
+addendum also pruned the flat `delivery/trust.bundle` legacy seals on every publish (to
+"migrate off" the shared path). That was reverted: during the migration window a concurrent PR
+may still seal to the flat path (this was written while PR #370 had an open flat-path seal),
+and a per-delivery deletion of that file is a **modify/delete conflict** against such a PR → a
+DIRTY PR → precisely the no-CI failure mode this whole change exists to remove. Because the
+flat path is a single fixed location (not a growth vector) and prefer-newest selection makes a
+lingering flat bundle harmless, retaining it costs nothing. Removing the flat legacy seals is a
+one-time cleanup for a **dedicated** PR once no open PR still seals to the flat path — not
+something safely bundled into every delivery.
+
+**The SILENT failure mode (documented, not "solved").** No repo-side code can make GitHub
+run `pull_request` workflows on a conflicted PR — that is platform behavior. Per-session
+paths remove the STRUCTURAL cause (the shared-path conflict) for agent-vs-agent delivery
+contention, which is the overwhelming majority of the incidents. The residual — a PR that
+goes DIRTY for some OTHER reason (a genuine same-file edit conflict with `main`) still gets
+no CI silently — is addressed by making the failure mode LOUD where we can: the deliver
+skill now documents the DIRTY→no-CI symptom and its diagnosis (`gh pr view --json
+mergeStateStatus`), and `discoverBundle()` emits a grep-stable `#379: examined N delivery
+candidate(s) … none attests this change …` concurrency hint so the next agent can tell a
+per-session collision apart from a plain stale/absent bundle. #335's detectability half
+(treating `mergeStateStatus=DIRTY` as a first-class steering/doctor input) remains open and
+is explicitly NOT claimed closed here.
+
+**Security: the forgery surface moved with the write path.** `scripts/hooks/config-protection.js`
+(and its `context/` mirror) protected only the flat `delivery/trust.bundle` /
+`delivery/trust.checkpoint.json` from direct agent Write/Edit/cp/redirect. Its three
+delivery regexes now carry an optional `(?:[^/]+\/)?` segment so `delivery/<slug>/trust.*`
+is equally blocked — otherwise moving the write path would have opened a hand-forgery hole
+one directory down. Regression-locked by `test_gate_lockdown.sh` AC1.26b/c/d. The
+`delivery/*` gitignore already covers per-session dirs (they are force-added deliberately per
+delivery exactly like the flat path).
+
+**Residuals (honest):** (1) the DIRTY→no-CI platform behavior for non-per-session conflicts
+is documented, not eliminated (above). (2) The per-session dir name is derived from the
+local session slug; a colliding slug across two sessions would re-share a path — acceptable
+because ownership is still decided by commit ancestry (a stale same-named sibling is ignored,
+not trusted), and slugs are session-unique in practice. (3) Selection correctness does NOT
+depend on merge strategy: prefer-newest resolves the owning candidate for both squash-merge
+(inherited seals are non-ancestors, trivially not-owning) and merge-commit (inherited seals
+can be ancestors, but attest an OLDER commit than this session's, so they lose on recency)
+histories — the merge-commit case was the concrete defect that forced prefer-newest and is
+regression-locked by `test_trust_reconcile_negatives.sh` §8d against a real git repo. (4) The
+flat legacy seals still on `main` are retained by design (see cleanup policy above) and remain
+until a dedicated one-time cleanup PR; they are harmless (prefer-newest) but do accumulate as a
+single fixed path, not a growth vector. This addendum changes WHERE seals live and HOW the
+owning one is chosen; it does not touch Step 1 (fresh verify), the DECLARED exemption path, or
+any fail-closed verdict — all of which are regression-locked unchanged.

package/docs/coordination-guide.md

@@ -0,0 +1,370 @@
+---
+title: Parallel-Session Coordination Guide
+---
+
+# Parallel-Session Coordination Guide
+
+This is the plain-language, end-to-end explanation of how Flow Agents lets **many sessions work the
+same repository at once** without two of them silently taking the same work, redoing each other's
+effort, or clobbering one another's changes at publish time.
+
+> **Which doc do I want?** This page is the *living reference* for coordination — the model and the
+> four guard points, as actually shipped. The frozen [ADRs](adr/) (0012, 0021, 0020, 0022) are the
+> immutable record of *why* each decision was made; this guide is where you look to understand *what
+> runs today*. The [System Guidebook](agent-system-guidebook.md) is the broader map of the whole
+> operating layer. For the optional hosted tier that turns this local substrate into a team-wide
+> fleet view, see [Flow Agents × Console](integrations/flow-agents-console.md).
+
+---
+
+## The problem, in one paragraph
+
+You want to run *X* parallel Builder sessions and never think about collisions. That means four
+moments in a session's life must be fenced: **selection** (don't pick work someone already holds),
+**entry** (don't re-enter a subject someone else owns), **mid-flight** (notice fast if an overlap
+happened anyway, and correct it), and **publish** (never let a session that was superseded while it
+slept push over the session that replaced it). Everything else is convenience; those four are the
+safety. Flow Agents makes all four advisory-by-default and cheap, with exactly **one hard fence** —
+at publish — because a false block anywhere else would just annoy you, while a missing block at
+publish loses work.
+
+## The mental model: two independent streams, joined
+
+Coordination is not one lock. It's **two independent, append-only signals about a subject** (a work
+item / slug), joined at read time into a single *effective state*:
+
+| Stream | Question it answers | Lifetime | Where it lives |
+| --- | --- | --- | --- |
+| **Liveness** | "Is someone *actively working* right now?" | Ephemeral — TTL-reaped, heartbeat-refreshed | `liveness/` event stream ([ADR 0012](adr/0012-agent-coordination-as-liveness-claims.md)) |
+| **Assignment** | "Who *durably owns* this subject?" | Durable — an explicit claim record / GitHub assignee | `AssignmentProvider` ([ADR 0021](adr/0021-assignment-leases-and-stale-claim-takeover.md)) |
+
+Neither alone is enough. Liveness without assignment can't tell a crashed session from a finished
+one. Assignment without liveness can't tell an actively-working owner from a stale lease nobody is
+servicing. **Joined**, they answer the only question that matters — *can I safely take this?* — and
+the answer degrades gracefully when one signal is missing.
+
+Here is the lifecycle, mapped to the code that fences each moment:
+
+| Session phase | Guard point | Command / hook | Effect |
+| --- | --- | --- | --- |
+| **Selection** | pull-work preflight | `pull-work` skill → `assignment-provider status` | Excludes `held`/`reclaimable`; asks first on `human-held` |
+| **Entry** | ensure-session ownership guard | `workflow-sidecar ensure-session` | `free`→claim; `reclaimable`+`--supersede-stale`→take over; `human-held`→ask |
+| **Mid-flight** | liveness heartbeat + supersession steering | Activity hooks + `workflow-steering.js` | Refreshes the claim; warns every turn if you were superseded |
+| **Exit** | Stop-hook clean release | Stop hook → `liveness release` + assignment release | Frees both streams, leaves a handoff note |
+| **Publish** | verify-hold gate (**the one hard fence**) | `workflow-sidecar verify-hold` inside `publishDelivery` | Blocks a superseded/zombie session from pushing |
+
+The rest of this guide walks each layer bottom-up: first *who am I* (the actor model — the part that
+caused the most bugs, so it goes first), then the two streams, then the join, then each guard point,
+then how delivery itself is made tamper-resistant.
+
+---
+
+## 1. The actor model — "who am I?"
+
+Every claim, heartbeat, and ownership check is attributed to an **actor**. Getting actor identity
+subtly wrong is what caused nearly every hard bug in this substrate (#291, #292, #293), so understand
+this section before the rest.
+
+### The resolution chain
+
+`resolveActor(env)` (in `scripts/hooks/lib/actor-identity.js`, mirrored in `src/cli`) returns
+`{ actor, source }` by trying four sources in strict priority order:
+
+1. **`explicit-override`** — `FLOW_AGENTS_ACTOR` is set. The actor is the **bare token** you provided,
+   verbatim. Source string: `"explicit-override"`.
+2. **`runtime-session-id:<runtime>`** — the host runtime exposes a native session id (e.g. Claude
+   Code). The actor is a **serialized triple** `runtime:session:host`. Source string:
+   `"runtime-session-id:<runtime>"`.
+3. **`process-ancestry`** — no session id; identity is derived by walking the process tree. Also a
+   serialized triple. Source string: `"process-ancestry"`.
+4. **`unresolved`** — nothing worked. Source string: `"unresolved"`.
+
+The `"local"` literal default from the old design is **retired as an error, not a fallback** — a
+shared default actor structurally defeats collision detection on the one machine (your laptop) where
+co-located sessions are most likely.
+
+### The seam that caused the bugs: flat token vs. serialized triple
+
+Here is the trap. An **override** actor is a *bare token* (`alice`). A **derived** actor is a
+*serialized triple* (`claude:sess-abc:host`). So there are two different string forms for "the
+actor," and they **diverge for override actors but agree for derived actors**:
+
+- `resolveActor(env).actor` → the canonical form (bare token for overrides; triple for derived).
+- `serializeActor(actorStruct)` → **always** a triple `<runtime>:<session>:<host>`. For an override
+  actor the struct's `<runtime>` is whatever the reconstructing site fills in (`detectRuntime()`,
+  typically `unknown`, in `assignment-provider.ts`), so it serializes to something like
+  `unknown:alice:host` — **not** equal to the bare `alice` the rest of the system uses. The exact
+  prefix doesn't matter; what matters is that the serialized form is a triple and the canonical form
+  is a bare token, so the two **diverge for override actors** (and happen to agree for derived ones).
+
+Every other surface — `liveness whoami`, `liveness claim --actor`, per-actor `current.json`,
+pull-work's `--self-actor` — uses the canonical `resolveActor().actor` form. If a self-recognition
+check compared the *serialized* form of a stored claim against the *canonical* self, an override
+session would **fail to recognize its own claim** and either double-claim or false-block itself.
+
+### The fix: a canonical `actor_key` on every record
+
+Claim records carry an explicit `actor_key` field (schema ≥ 1.0): the canonical
+`resolveActor(env).actor` string of the claiming actor. Self-recognition and the liveness join always
+compare against **this**, with a backward-compatible fallback for pre-#291 records:
+
+```
+holderActorKey = record.actor_key || serializeActor(record.actor)
+```
+
+A record written by a current session has `actor_key` and compares canonically; an old record without
+it falls back to `serializeActor`, reproducing pre-#291 behavior exactly. This one field is why the
+override/derived divergence no longer bites.
+
+### Stable vs. unstable identity (this powers the publish gate)
+
+The `source` matters beyond attribution. An identity is **stable** if it came from
+`explicit-override` or `runtime-session-id:*` — those are reproducible across a session's lifetime. It
+is **unstable** if it came from `process-ancestry` or `unresolved` — those can shift (e.g. a CI job
+with a different process tree on each step). The publish gate (§8) *enforces* only for stable
+identities and degrades to advisory for unstable ones, because a hard block keyed on an identity that
+might not reproduce would false-block legitimate work. Making CI identity stable is the subject of the
+forthcoming CI-runtime identity tier (#398).
+
+---
+
+## 2. The liveness stream — "is someone working right now?"
+
+Liveness ([ADR 0012](adr/0012-agent-coordination-as-liveness-claims.md)) is an **advisory,
+append-only** stream of `claim` / `heartbeat` / `release` events, one file under `liveness/`, reaped
+by TTL. It is computed, never authoritative:
+
+- A session **claims** a subject when it starts working it, and **heartbeats** on activity to refresh
+  freshness. Auto-emit is wired into the lifecycle (default-on since #288).
+- A holder is **fresh** if its most recent event is within the TTL window; **stale** otherwise.
+- On clean exit the session emits **release**; on a crash it simply stops heartbeating and ages out.
+
+Liveness answers "active *now*," cheaply and without provider mutation. It cannot, alone, distinguish
+"crashed mid-work" from "finished and moved on" — that's what assignment adds.
+
+Helpers: `scripts/hooks/lib/liveness-read.js` reads the stream; `liveness whoami` prints the current
+actor; `workflow-sidecar liveness claim|heartbeat|release` manage events.
+
+---
+
+## 3. The assignment layer — "who durably owns this?"
+
+The `AssignmentProvider` ([ADR 0021](adr/0021-assignment-leases-and-stale-claim-takeover.md),
+`src/cli/assignment-provider.ts`) is the durable half. It's an abstraction with two implementations
+behind one contract ([`context/contracts/assignment-provider-contract.md`](https://github.com/kontourai/flow-agents/blob/main/context/contracts/assignment-provider-contract.md)):
+
+- **`github`** — maps ownership onto native GitHub primitives: **assignee** (the durable claim),
+  **label** (the state), **comment** (the audit trail). This is the shared-truth provider for a team.
+- **`local-file`** — a per-repo claim record on disk, for solo/offline use.
+
+Operations: `claim`, `release`, `supersede`, `status`, `list`. A claim record is versioned
+(`schema_version: "1.0"`) and carries the canonical `actor_key` (§1), a `claimed_at`, and an
+`audit_trail` of `claim`/`release`/`supersede` transitions.
+
+### Render-don't-execute
+
+A crucial design rule ([ADR 0021](adr/0021-assignment-leases-and-stale-claim-takeover.md), Decision
+1): **the CLI never runs `gh` itself.** For the `github` provider it emits the exact `gh` argv and
+comment bodies as pure data; the skill layer executes them via the harness Bash tool (argv arrays,
+never shell strings). No `gh` subprocess exists in `src/`. This keeps the trust boundary clean and the
+provider testable.
+
+---
+
+## 4. The join — assignment ⋈ liveness → effective state
+
+`computeEffectiveState()` (`src/cli/assignment-provider.ts`) joins the two streams into one of four
+**effective states**, each with a specific machine-readable `reason`. This table *is* the coordination
+logic — everything downstream is a policy over these outcomes:
+
+| effective_state | reason | Meaning |
+| --- | --- | --- |
+| `free` | `no_assignment_no_liveness` | Nobody owns it and nobody is working it. Take it. |
+| `held` | `self_is_holder` | *You* hold it (canonical `actor_key` matches self). Proceed. |
+| `held` | `fresh_liveness_heartbeat` | Someone else holds it **and** is actively heartbeating. Hands off. |
+| `held` | `liveness_claim_present_assignment_lagging` | Liveness present but **no durable assignment yet** — an actively-working session that hasn't recorded a durable claim. |
+| `reclaimable` | `assignment_present_liveness_stale_or_absent` | A durable assignment exists but **nobody is heartbeating** — a stale lease / crashed or finished session. Eligible for takeover. |
+| `human-held` | `assignee_is_human` | A human is assigned. **Ask first**, always. |
+| `human-held` | `assignee_without_claim_record` | A human assignee with no agent claim record. **Ask first.** |
+
+Two subtleties worth internalizing:
+
+- **`held / liveness_claim_present_assignment_lagging`** is "working but not yet durably claimed." It
+  is a *hold* (don't barge in) but it is **not** an assignment-backed conflict — which is exactly why
+  the publish gate treats it as a pass (§8).
+- **`reclaimable`** is the takeover-eligible state: the durable owner is gone (stale/absent liveness)
+  but left a lease. Reclaiming it is deliberate and gated (§7, §10), never automatic.
+
+---
+
+## 5. Guard point 1 — pull-work selection
+
+When a session selects work, the `pull-work` skill computes the join for each candidate and **excludes
+anything not takeable**: `held` and `reclaimable` subjects are filtered out; `human-held` triggers an
+ask-first prompt rather than a silent skip. Only after selection does it **emit** — first a liveness
+claim, then (via render-don't-execute) the assignment claim. This is what stops *N* concurrent sessions
+from all classifying the same issue "ready" and all taking it. Selection reads and writes both streams;
+it never mutates a provider it hasn't been told to.
+
+## 6. Guard point 2 — ensure-session ownership guard
+
+`workflow-sidecar ensure-session` (`src/cli/workflow-sidecar.ts`, `enforceEnsureSessionOwnership`) is
+the fence at **entry** — the moment a session commits to a subject. It computes the effective state and
+branches:
+
+- **`free`** → claim and enter.
+- **`self_is_holder`** → already yours; enter.
+- **`reclaimable`** → enter **only** with an explicit `--supersede-stale`; that performs a `supersede`
+  (recording the takeover in the audit trail) and enters. Without the flag, it stops and explains.
+- **`held` (someone else, fresh)** → stop; someone is actively working it.
+- **`human-held`** → stop and ask first.
+
+It resolves *self* through the same `resolveActor` path and compares on the canonical `actor_key`, so
+an override session recognizes its own in-progress claim (this is the seam from §1). Every untrusted
+field it echoes back (holder actor, `last_at`, branch) is sanitized at construction — see §9.
+
+## 7. Guard point 4 — Stop-hook clean release
+
+On clean session end, the **Stop hook** releases *both* streams: `liveness release` plus an assignment
+release, and writes a **handoff note** so the next session (human or agent) picks up from recorded
+state rather than guesswork. A crash skips this — and that's fine: the liveness claim simply ages out
+to `stale`, the assignment becomes `reclaimable`, and takeover (§10) handles it. Clean release just
+makes the common case instant instead of TTL-delayed.
+
+## 8. Guard point 3 — the verify-hold publish gate (the one hard fence)
+
+This is the **only** place coordination *blocks*, and it earned three fix iterations, so its design is
+the most carefully tuned in the system. It lives in `runVerifyHold` and composes into `publishDelivery`
+(`src/cli/workflow-sidecar.ts`) as a distinct fail-closed tier.
+
+**The scenario it exists for:** a session claims a subject, goes idle (laptop sleeps), gets
+legitimately superseded by another session that finishes and merges. The first session wakes and tries
+to push — over the top of the work that replaced it. Nothing upstream catches this, because the zombie
+*was* the valid holder when it started. The publish gate is the backstop.
+
+**The converged rule — enforce narrowly, degrade safely:**
+
+> The gate **blocks (hard)** only when **(1) the session's identity is stable** (`explicit-override`
+> or `runtime-session-id:*`, or an explicitly-passed `actorKey`) **AND (2) there is a durable
+> assignment conflict** — the effective state is `reclaimable`, an assignment-backed `held`-by-another,
+> or `human-held`. In every other case it **degrades to advisory** and passes.
+
+Concretely:
+
+- **Unstable identity** (`process-ancestry` / `unresolved`) → short-circuits to
+  `{ ok: true, effective_state: "not_evaluated", reason: "actor-identity-unstable-advisory-only" }`.
+  It never hard-blocks on an identity that might not reproduce. (This is why CI, which currently
+  resolves via ancestry, gets advisory treatment — and why #398, giving CI a stable identity, upgrades
+  it to enforcing.)
+- **Liveness-only hold** (`held / liveness_claim_present_assignment_lagging`) → **passes.** There is no
+  durable assignment conflict; blocking here would false-block a legitimate publish.
+- **Genuine durable conflict + stable identity** → throws `NotFreshHolderError`
+  (`.code === "VERIFY_HOLD_NOT_FRESH_HOLDER"`), which `publishDelivery` refuses to swallow.
+
+**Why this doesn't weaken zombie protection:** a superseded session *always* leaves a durable
+assignment record (supersede writes one), and a real interactive session *always* carries a stable
+identity. So the exact case the gate must catch — a stable session whose durable claim was superseded —
+always lands in the enforcing branch. The advisory degradations only ever apply to cases that were
+never a real conflict.
+
+**The load-bearing lesson** (captured as a learning + a deliver-guidance correction): a hard block
+added to a *shared* code path (`publishDelivery` is traversed by every delivery and many tests) must
+**default to advisory and enforce only on high-confidence signals.** Two of the three defects were
+*false-blocks* invisible to all eight acceptance criteria and two review passes — because every AC
+scenario naturally used a stable identity with an assignment record. They only surfaced when CI's broad
+suite ran under a *neutral* (ancestry) identity. Targeted ACs and a broad-suite-under-neutral-identity
+are **different safety nets**; a hard-block-on-shared-path change needs both.
+
+## 9. The injection-safety invariant (everywhere untrusted fields are echoed)
+
+Coordination reads fields written by *other* sessions — actor, holder, `last_at`, branch,
+`artifact_dir`, reason. These are **untrusted** and flow into agent-facing output, so a hostile value
+could inject instructions or blow up a display. The invariant, applied at *construction* (not at print
+time), everywhere such a field crosses into output:
+
+```
+stripControlCharsForDisplay(value).slice(0, 64)   // (larger caps for known-long fields, e.g. reason → 240)
+```
+
+This class recurred across #287/#320/#290/#291/#293. The subtlest miss: sanitizing only the
+*discriminated* field (`actor`) while a sibling (`last_at`) slipped through raw — fixed by sanitizing
+the *whole holder object* at construction. `safeStateText` in `workflow-steering.js` was found to only
+collapse whitespace (not strip control chars) and was hardened. When you add a new field to any
+coordination output, sanitize it at construction — no exceptions.
+
+## 10. Takeover protocol (forthcoming — #294)
+
+Takeover is the deliberate reclaiming of a `reclaimable` subject. The pieces already exist —
+`reclaimable` detection (§4), `--supersede-stale` entry (§6), supersede audit records (§3), and the
+publish gate that catches the woken zombie (§8). #294 is the remaining slice that ties them into a
+first-class protocol: **stale detect → grace beat → supersede → resume the branch**, with the original
+session caught cleanly at publish if it ever wakes. Until it lands, takeover works via the manual
+`ensure-session --supersede-stale` path. *(This section describes intended behavior; #294 is not yet
+shipped.)*
+
+---
+
+## How delivery itself is made tamper-resistant
+
+Coordination decides *who* may publish; the **delivery machinery** makes the publish itself honest and
+non-colliding. Three mechanisms
+([ADR 0020](adr/0020-trust-reconcile-manifest-and-claim-classification.md),
+[ADR 0022](adr/0022-fail-closed-delivery-reconciliation-with-governed-exemptions.md)):
+
+**Per-session delivery paths (#379).** Each session writes its bundle under `delivery/<slug>/` instead
+of a shared `delivery/trust.bundle`. Two sessions delivering concurrently no longer overwrite each
+other; CI selects prefer-newest. (A recurring publish trap: after a soft-reset, `git add -A` would
+stage the *deletion* of other sessions' `delivery/<slug>/` dirs — always restore sibling delivery dirs
+from `origin/main` before committing.)
+
+**Three-tier fail-closed `publishDelivery`.** Publishing passes through, in order:
+1. **fail-soft** — absent/repo-root bundle is tolerated (nothing to publish).
+2. **shape gate (#356)** — `InvalidBundleShapeError` (`.code === "RECONCILE_PREFLIGHT_INVALID_SHAPE"`):
+   an invalid *bundle shape* is refused before anything is copied into `delivery/`.
+3. **hold gate (#293)** — `NotFreshHolderError` (§8): a valid-shaped bundle from a superseded holder is
+   refused.
+
+These are **distinct error types**, asserted by `.code`/`instanceof` (not message text) so a future
+refactor can't silently collapse them.
+
+**reconcile-preflight (#356).** A local, pre-push mirror of the CI reconcile check, sharing
+`scripts/lib/reconcile-shape.js` so it can never drift from CI. It runs the *same* shape classification
+CI enforces, catching an invalid bundle on your laptop instead of in a red CI run. Its one deliberate
+difference is the `onUnderivable` mode: CI passes `'fail'` (fail-closed — an underivable status fails
+the run); the local preflight may pass `'reduce'` (trust a session-local self-reported status when
+re-derivation is unavailable). The default is `'fail'`, so nothing degrades to fail-open by accident.
+
+**Staleness binding (ADR 0022).** A checkpoint's `commit_sha` must be an ancestor of `HEAD`, achieved
+by *sealing at the parent commit*: soft-reset `HEAD~1` → seal → publish → recommit. This binds a bundle
+to the exact history it attests, so a stale bundle can't be replayed onto a moved branch.
+
+The canonical publish sequence that ties coordination + delivery together:
+
+```
+rebase early  →  seal at parent (commit_sha = HEAD~1)  →  reconcile-preflight (local backstop)
+              →  restore sibling delivery/<slug>/ dirs  →  verify-hold  →  push
+```
+
+---
+
+## Where this goes next: the Console tier
+
+Everything above runs **locally** and needs no server — that's the design invariant (the Console is
+never required). The optional [Kontour Console](integrations/flow-agents-console.md) tier turns this
+per-repo substrate into a **team-wide fleet view**: a liveness relay so you can see every teammate's
+active sessions, project/team economics and insight views alongside your own, an in-hub janitor that
+reaps stale claims centrally, and — eventually — a Console-backed `AssignmentProvider` so assignment is
+authoritative across machines. It also makes CI a first-class, attributable participant (paired with
+#398). See the [Flow Agents × Console integration doc](integrations/flow-agents-console.md) for the
+phased plan.
+
+---
+
+## Provenance
+
+This guide is the living reference. The decisions behind it are recorded, immutable, in the ADRs it
+links; the ratified subject decisions live in [`docs/decisions/`](decisions/index.md)
+([agent-coordination](decisions/agent-coordination.md), [trust-reconcile](decisions/trust-reconcile.md)).
+Shipped across issues #287 (actor identity), #288 (liveness), #289 (branches), #166 (pull-work), #320
+(overlap), #290 (AssignmentProvider), #291 (ensure-session guard), #292 (stop-release), #356
+(reconcile-preflight), #293 (verify-hold); #294 (takeover) and #398 (CI identity) forthcoming.

package/docs/decisions/agent-coordination.md

@@ -1,20 +1,37 @@
 ---
-status: needs-decision
+status: current
 subject: Agent coordination
-decided: 2026-07-03
+decided: 2026-07-04
 evidence:
   - kind: adr
     ref: docs/adr/0012-agent-coordination-as-liveness-claims.md
   - kind: adr
     ref: docs/adr/0021-assignment-leases-and-stale-claim-takeover.md
+  - kind: doc
+    ref: docs/coordination-guide.md
 ---
 # Agent coordination
 
-This subject has provenance in frozen ADR history ([0012-agent-coordination-as-liveness-claims.md](../adr/0012-agent-coordination-as-liveness-claims.md), [0021-assignment-leases-and-stale-claim-takeover.md](../adr/0021-assignment-leases-and-stale-claim-takeover.md)) but no living
-decision has been ratified yet under the topic-keyed decision registry
-(`context/contracts/decision-registry-contract.md`). This stub records that the
-subject is open and links the frozen ADR(s) as provenance; it is not a decision.
+**Decision.** Parallel-session coordination is a **two-stream join**: an ephemeral,
+TTL-reaped **liveness** stream ("who is working now") and a durable **assignment** record
+("who owns this") are joined at read time by `computeEffectiveState()` into one of four
+effective states — `free`, `held`, `reclaimable`, `human-held`. Selection, entry, and publish
+are policies over that join. The model is **advisory by default with exactly one hard fence**
+(the verify-hold publish gate), which itself enforces only for stable identities against durable
+conflicts and degrades to advisory otherwise.
 
-When a living decision is ratified for agent coordination, update this
-file's `status` to `current`, add rationale, and keep the `adr` evidence
-links as provenance for the history that led here.
+This is the **living reference**, kept current: [`docs/coordination-guide.md`](../coordination-guide.md).
+The frozen ADRs ([0012](../adr/0012-agent-coordination-as-liveness-claims.md),
+[0021](../adr/0021-assignment-leases-and-stale-claim-takeover.md)) remain immutable provenance
+for *why* each decision was made.
+
+**Rationale.** Two independent signals degrade gracefully when one is missing (liveness alone
+can't tell a crash from a finish; assignment alone can't tell an active owner from a stale
+lease), and an advisory-by-default posture keeps false blocks cheap while concentrating the one
+place a false *miss* is expensive — publish — into a single, carefully-tuned gate.
+
+**Shipped as** #287 (actor identity), #288 (liveness default-on), #289 (branches), #166
+(pull-work), #320 (overlap detect-and-correct), #290 (AssignmentProvider), #291 (ensure-session
+ownership guard), #292 (stop-hook clean release), #293 (verify-hold publish gate). Forthcoming:
+#294 (takeover protocol), #398 (CI-runtime actor identity). The optional fleet tier is
+[Flow Agents × Console](../integrations/flow-agents-console.md).

package/docs/decisions/index.md

@@ -10,7 +10,7 @@ Numbered ADRs under `docs/adr/` are frozen history and are not listed here.
 
 | Topic | Status | Decision |
 | --- | --- | --- |
-| [agent-coordination](./agent-coordination.md) | needs-decision | Agent coordination |
+| [agent-coordination](./agent-coordination.md) | current | Agent coordination |
 | [anti-gaming-trust-security](./anti-gaming-trust-security.md) | needs-decision | Anti-gaming trust security |
 | [context-lifecycle](./context-lifecycle.md) | needs-decision | Context lifecycle |
 | [core-domain-kit-boundary](./core-domain-kit-boundary.md) | needs-decision | Core vs domain kit boundary |
@@ -30,7 +30,7 @@ Numbered ADRs under `docs/adr/` are frozen history and are not listed here.
 | [promotion-gate](./promotion-gate.md) | current | Promotion gate |
 | [standing-directives](./standing-directives.md) | current | Standing directives |
 | [three-hard-boundary-model](./three-hard-boundary-model.md) | needs-decision | Three-hard-boundary model |
-| [trust-reconcile](./trust-reconcile.md) | needs-decision | Trust-reconcile and delivery reconciliation |
+| [trust-reconcile](./trust-reconcile.md) | current | Trust-reconcile and delivery reconciliation |
 | [typescript-source-policy](./typescript-source-policy.md) | current | TypeScript-first source policy |
 | [workflow-enforcement](./workflow-enforcement.md) | needs-decision | Workflow Enforcement |
 | [workflow-trust-state](./workflow-trust-state.md) | needs-decision | Workflow trust state |

package/docs/decisions/trust-reconcile.md

@@ -1,20 +1,53 @@
 ---
-status: needs-decision
+status: current
 subject: Trust-reconcile and delivery reconciliation
-decided: 2026-07-03
+decided: 2026-07-04
 evidence:
   - kind: adr
     ref: docs/adr/0020-trust-reconcile-manifest-and-claim-classification.md
   - kind: adr
     ref: docs/adr/0022-fail-closed-delivery-reconciliation-with-governed-exemptions.md
+  - kind: doc
+    ref: docs/coordination-guide.md
 ---
 # Trust-reconcile and delivery reconciliation
 
-This subject has provenance in frozen ADR history ([0020-trust-reconcile-manifest-and-claim-classification.md](../adr/0020-trust-reconcile-manifest-and-claim-classification.md), [0022-fail-closed-delivery-reconciliation-with-governed-exemptions.md](../adr/0022-fail-closed-delivery-reconciliation-with-governed-exemptions.md)) but no living
-decision has been ratified yet under the topic-keyed decision registry
-(`context/contracts/decision-registry-contract.md`). This stub records that the
-subject is open and links the frozen ADR(s) as provenance; it is not a decision.
+**Decision.** Delivery is **fail-closed with governed exemptions**. `publishDelivery()` passes a
+bundle through three distinct, type-discriminated tiers — fail-soft (absent bundle tolerated) →
+shape gate (`InvalidBundleShapeError`, #356) → hold gate (`NotFreshHolderError`, #293) — and CI's
+reconcile is fail-closed by default (`onUnderivable: 'fail'`). A local `reconcile-preflight`
+mirrors CI's shape check via the *shared* `scripts/lib/reconcile-shape.js` so the two cannot
+drift. Concurrent deliveries are isolated by **per-session paths** (`delivery/<slug>/`, #379), and
+a checkpoint's `commit_sha` must be an ancestor of HEAD (seal-at-parent) so a stale bundle can't be
+replayed onto a moved branch. See the [coordination guide](../coordination-guide.md#how-delivery-itself-is-made-tamper-resistant).
 
-When a living decision is ratified for Trust-reconcile and delivery reconciliation, update this
-file's `status` to `current`, add rationale, and keep the `adr` evidence
-links as provenance for the history that led here.
+**Rationale.** The default must be safe: an underivable status fails the run rather than passing
+it, and a hard block on the shared publish path is applied only on high-confidence signals so it
+never false-blocks legitimate work. The frozen ADRs ([0020](../adr/0020-trust-reconcile-manifest-and-claim-classification.md),
+[0022](../adr/0022-fail-closed-delivery-reconciliation-with-governed-exemptions.md)) hold the
+immutable rationale.
+
+## Implementation note (#356, iteration 1)
+
+A local, pre-push `reconcile-preflight` now exists (`workflow-sidecar reconcile-preflight
+<artifact-dir>`), reusing — never forking — the shape-classification logic CI's
+`scripts/ci/trust-reconcile.js` enforces via the shared `scripts/lib/reconcile-shape.js`
+module. `publishDelivery()` is itself fail-closed on shape-invalidity: it calls the same
+preflight before copying anything into `delivery/`, and refuses to publish a bundle that
+fails the shape check.
+
+The reduced-coverage degradation (trusting a session-local claim's self-reported status when
+CI-side re-derivation is unavailable) is a **LOCAL-preflight-only** opt-in
+(`sessionLocalShapeIssues(..., { onUnderivable: 'reduce' })`). CI's `trust-reconcile.js`
+always calls the shared function with `{ onUnderivable: 'fail' }` (also the function's
+default when no mode is given) and remains fail-closed: when status re-derivation is
+unavailable, every session-local pass-asserting claim becomes a `status-underivable`
+divergence and the run fails, exactly as before the shape logic was extracted.
+
+## Implementation note (#379, per-session delivery paths)
+
+Concurrent deliveries no longer contend on a shared `delivery/trust.bundle`. Each session writes
+its bundle under `delivery/<slug>/`; CI selects prefer-newest. Publishing must **restore sibling
+`delivery/<slug>/` directories** from `origin/main` before committing — after a soft-reset,
+`git add -A` would otherwise stage the deletion of other sessions' delivery dirs that the branch
+predates. This is the standard step in the publish sequence documented in the coordination guide.

package/docs/fixture-ownership.md

@@ -22,9 +22,10 @@ run `npm run validate:source --` and `npm run fixture:retirement-audit --`.
 | `evals/fixtures/hook-influence` | hook influence behavioral cases | `evals/integration/test_hook_influence_cases.sh`, `evals/static/test_workflow_skills.sh`, `scripts/validate-hook-influence-cases.js` | Keep while hook influence cases define agent guidance behavior. |
 | `evals/fixtures/pull-work-provider` | work item provider normalization fixtures | `evals/integration/test_pull_work_provider.sh` | Keep while provider normalization preserves blockers, artifact refs, board membership, and freshness metadata. |
 | `evals/fixtures/pull-work-wip-shepherding` | WIP shepherding state fixtures | `evals/static/test_workflow_skills.sh` | Keep while pull-work documents personal versus global WIP behavior. |
+| `evals/fixtures/reconcile-preflight` | #356 reconcile-preflight shape fixtures not already covered by trust-reconcile-exploits (un-superseded disputed critique, standalone disputed session-local claim) | `evals/integration/test_reconcile_preflight.sh` | Keep while the local `reconcile-preflight` subcommand (#356) is proven against the two shapes trust-reconcile-exploits does not already fixture (un-superseded disputed critique, standalone disputed session-local claim); the other four shapes reuse trust-reconcile-exploits/trust-reconcile-mixed-bundle directly rather than forking near-duplicates. |
 | `evals/fixtures/surface-trust` | Surface trust evidence fixtures | `evals/integration/test_workflow_sidecar_writer.sh` | Keep while sidecar writer maps Surface trust evidence into workflow records. |
-| `evals/fixtures/trust-reconcile-exploits` | WS8 trust-reconcile anti-gaming exploit fixtures (frozen negative regressions) | `evals/integration/test_trust_reconcile_negatives.sh` | Keep while trust-reconcile.js enforces the WS8 iteration-2 soundness properties (no-label test_output, unwaived-assumed, status-misassertion, waiver-on-command); each fixture is a permanent negative regression. |
-| `evals/fixtures/trust-reconcile-mixed-bundle` | WS8 trust-reconcile mixed-evidence end-to-end proof fixture | `evals/integration/test_trust_reconcile_mixed_bundle.sh` | Keep while the trust-reconcile manifest/classification/waiver contract (ADR 0020) is enforced; proves a mixed test_output + session-local + waived bundle passes the CI anchor. |
+| `evals/fixtures/trust-reconcile-exploits` | WS8 trust-reconcile anti-gaming exploit fixtures (frozen negative regressions); also reused by the #356 local reconcile-preflight eval (same shapes, no forked copies) | `evals/integration/test_trust_reconcile_negatives.sh`, `evals/integration/test_reconcile_preflight.sh` | Keep while trust-reconcile.js enforces the WS8 iteration-2 soundness properties (no-label test_output, unwaived-assumed, status-misassertion, waiver-on-command); each fixture is a permanent negative regression. |
+| `evals/fixtures/trust-reconcile-mixed-bundle` | WS8 trust-reconcile mixed-evidence end-to-end proof fixture; also reused by the #356 reconcile-preflight eval as its CLEAN-BUNDLE (AC4) case | `evals/integration/test_trust_reconcile_mixed_bundle.sh`, `evals/integration/test_reconcile_preflight.sh` | Keep while the trust-reconcile manifest/classification/waiver contract (ADR 0020) is enforced; proves a mixed test_output + session-local + waived bundle passes the CI anchor. |
 | `evals/fixtures/trust-reconcile-ws3` | WS8 AC6 backward-compat fixture: real ws3-kit-dependencies-namespacing old-style bundle | `evals/integration/test_trust_reconcile_negatives.sh` | Keep while backward compatibility with pre-classification (all-test_output) bundles is asserted; proves an old-style bundle still FAILS the same way (no silent pass). |
 | `evals/fixtures/usage-feedback` | usage feedback import/outcome fixtures | `evals/integration/test_usage_feedback_import.sh`, `evals/integration/test_usage_feedback_outcomes.sh`, `evals/integration/test_usage_feedback_report.sh` | Keep while usage feedback import, outcome, and report flows accept JSONL fixture input. |
 | `evals/fixtures/veritas-governance-adapter` | Veritas governance adapter fixtures | `evals/integration/test_veritas_governance_adapter.sh` | Keep while the Veritas adapter supports pass, unconfigured, and secret-failure governance paths. |