@kontourai/flow-agents 2.3.0 → 3.0.0

package/docs/workflow-usage-guide.md

@@ -16,7 +16,7 @@ ideas -> Builder Kit shape / idea-to-backlog -> work items -> pull-work -> picku
 
 You can do this in one conversation, but the gates should stay explicit. Do not let shaping, planning, implementation, and release confidence blur into one continuous task.
 
-Workflow artifacts follow a closeout lifecycle. Local runtime artifacts live under `.flow-agents/<slug>/` and stay uncommitted. When a branch needs reviewable in-progress planning, promote durable behavior, decisions, evidence, and usage notes into long-lived docs, source, schemas, or provider records before merge.
+Workflow artifacts follow a closeout lifecycle. Local runtime artifacts live under `.kontourai/flow-agents/<slug>/` and stay uncommitted. When a branch needs reviewable in-progress planning, promote durable behavior, decisions, evidence, and usage notes into long-lived docs, source, schemas, or provider records before merge.
 
 For local artifact queue hygiene, run the read-only cleanup audit:
 
@@ -56,7 +56,7 @@ Expected behavior:
 Expected artifact:
 
 ```text
-.flow-agents/<slug>/<slug>--idea-to-backlog.md
+.kontourai/flow-agents/<slug>/<slug>--idea-to-backlog.md
 ```
 
 The artifact should include `source_ideas`, `idea_inventory`, `slice_candidates`, `bundle_justification`, `dependency_map`, `phase`, `decisions`, `opportunity_briefs`, `shaped_work`, `risk_release_notes`, `backlog_links`, `parked_or_rejected`, `open_questions`, `next_gate`, and the Builder Kit Flow Definition link. Use this phase to decide what deserves backlog space. Provider-backed work items should be executable or near-executable work, not a dumping ground for every idea. GitHub issues are the first adapter example.
@@ -109,11 +109,17 @@ Expected behavior:
 Expected artifact:
 
 ```text
-.flow-agents/<slug>/<slug>--pull-work.md
+.kontourai/flow-agents/<slug>/<slug>--pull-work.md
 ```
 
 When a repository has backlog provider settings, `pull-work` should use those settings without requiring the user to name the board. In Flow Agents, `npm run effective-backlog-settings -- --repo-path . --json` resolves `kontourai/flow-agents` to GitHub Project `kontourai/1`, so a prompt like `use pull-work` is enough for the configured provider path.
 
+### Assignment ownership: the third provider leg
+
+Beside the `WorkItemProvider` (what work exists) and `BoardProvider` (how it is grouped/ranked) settings above, `pull-work` also reads `AssignmentProvider` settings to decide who currently owns a candidate work item before offering it. This is durable, human-visible ownership — a GitHub issue assignee, an `agent:claimed` label, and a versioned machine-readable claim comment (or, for tracker-less repos and evals, an equivalent local JSON record) — joined against the ephemeral liveness presence layer so a crashed session's stale claim never blocks a second session from picking up the same work.
+
+Settings live at `context/settings/assignment-provider-settings.json` (validated by `schemas/assignment-provider-settings.schema.json`), mirroring the same `defaults`/`projects[]` shape as the backlog provider settings above; resolve them with `npm run effective-assignment-provider-settings -- --repo-path . --json`. See `context/contracts/assignment-provider-contract.md` for the full `claim`/`release`/`supersede`/`status`/`list` vocabulary, the assignment ⋈ liveness join table, and the human-assignee ask-first policy.
+
 Direct `pull-work` remains a normal workflow primitive. The Builder Kit build path adds the pickup Probe/design-probe handoff before planning; it does not require Surface/Veritas trust-backed gates and does not replace direct primitive use.
 
 Builder Kit build is the product-level entry point for implementation pickup. In that mode, `pull-work` may guide the next step automatically as `pull-work -> design-probe / pickup-probe`; direct `pull-work` still stops with a `plan-work` handoff unless you ask to continue.
@@ -136,7 +142,7 @@ Your WIP can block starting new work. Other people's WIP should block only when
 
 After `pull-work` passes the pickup gate in the Builder Kit build flow, use the Builder Kit pickup Probe before planning. The Flow Definition step is named `design-probe`, and the build path is `pull-work -> design-probe -> plan`. The generic `design-probe` skill owns one-question-at-a-time design alignment; the `pickup-probe` skill is the Builder Kit work-item/docs/provider-grounded specialization used at that step.
 
-The pickup Probe must record goal fit and scope, blockers and dependencies, dependency freshness, acceptance criteria quality, provider state, risk, stop-short risks, planning readiness, decisions, unresolved questions, accepted gaps, sandbox/worktree mode, expected modified files, and conflict risks. Record those in `.flow-agents/<slug>/<slug>--pull-work.md` or the plan handoff artifact before `plan-work` begins.
+The pickup Probe must record goal fit and scope, blockers and dependencies, dependency freshness, acceptance criteria quality, provider state, risk, stop-short risks, planning readiness, decisions, unresolved questions, accepted gaps, sandbox/worktree mode, expected modified files, and conflict risks. Record those in `.kontourai/flow-agents/<slug>/<slug>--pull-work.md` or the plan handoff artifact before `plan-work` begins.
 
 When the selected work item includes `planned_base_ref` and `planned_base_sha`, compare that base with current `main` before planning. If relevant files, contracts, docs, schemas, or dependency states changed since the work was shaped, classify the drift as `no_material_drift`, `scope_drift`, `dependency_drift`, `contract_drift`, or `conflict_risk`. Ask for alignment before planning when drift changes scope, acceptance criteria, dependency assumptions, or execution risk.
 
@@ -184,7 +190,7 @@ Then use `plan-work`.
 Example prompt:
 
 ```text
-Use plan-work for the selected work item in .flow-agents/<slug>/<slug>--pull-work.md. Produce an execution plan with acceptance criteria, file ownership, test strategy, and parallelization opportunities. Do not implement yet.
+Use plan-work for the selected work item in .kontourai/flow-agents/<slug>/<slug>--pull-work.md. Produce an execution plan with acceptance criteria, file ownership, test strategy, and parallelization opportunities. Do not implement yet.
 ```
 
 Then use `execute-plan` only after the plan is accepted.
@@ -200,7 +206,7 @@ When `pull-work` chooses a worktree, record `worktree_lifecycle`: path, branch,
 Example prompt:
 
 ```text
-Use execute-plan for .flow-agents/<slug>/<slug>--plan.md. Prefer isolated worktrees for parallel or risky work. Execute the plan and keep progress in the session artifact.
+Use execute-plan for .kontourai/flow-agents/<slug>/<slug>--plan.md. Prefer isolated worktrees for parallel or risky work. Execute the plan and keep progress in the session artifact.
 ```
 
 ## 5. Review, Then Verify
@@ -212,7 +218,7 @@ Review checks quality, security triggers, architecture fit, project standards, r
 Example prompt:
 
 ```text
-Use review-work for .flow-agents/<slug>/<slug>--deliver.md. Run code review, security review if triggered, and standards/architecture critique. Record findings in critique.json. Do not fix code.
+Use review-work for .kontourai/flow-agents/<slug>/<slug>--deliver.md. Run code review, security review if triggered, and standards/architecture critique. Record findings in critique.json. Do not fix code.
 ```
 
 Then use `verify-work` for implementation verification. Verification is evidence: it asks what proves the accepted behavior works.
@@ -222,7 +228,7 @@ Verification runs build/type/lint/test/security/browser/runtime checks as releva
 Example prompt:
 
 ```text
-Use verify-work for .flow-agents/<slug>/<slug>--deliver.md. Map every acceptance criterion to evidence and record PASS, FAIL, or NOT_VERIFIED.
+Use verify-work for .kontourai/flow-agents/<slug>/<slug>--deliver.md. Map every acceptance criterion to evidence and record PASS, FAIL, or NOT_VERIFIED.
 ```
 
 ## 6. Build Trust With Evidence Gate
@@ -253,7 +259,7 @@ Pickup Probe may update durable docs only when the decision is no longer a trans
 
 ## 7. Check Goal Fit Before Stopping
 
-Goal Fit is the local stop condition before a final answer. The working artifact in `.flow-agents/<slug>/` should answer:
+Goal Fit is the local stop condition before a final answer. The working artifact in `.kontourai/flow-agents/<slug>/` should answer:
 
 - What did the user originally ask for?
 - Can the user run, understand, inspect, or act on the result now?
@@ -272,7 +278,7 @@ npm run workflow:sidecar -- ensure-session \
   --summary "<summary>" \
   --criterion "<acceptance criterion>"
 
-npm run workflow:sidecar -- init-plan .flow-agents/<slug>/<slug>--deliver.md \
+npm run workflow:sidecar -- init-plan .kontourai/flow-agents/<slug>/<slug>--deliver.md \
   --source-request "<request>" \
   --summary "<summary>" \
   --next-action "<next step>"
@@ -306,10 +312,113 @@ Rules:
 - Issue-backed sessions should prefer `--work-item` over hand-supplied `--task-slug` so that
   liveness subjectId alignment is automatic.
 
+#### Branch convention
+
+`ensure-session` derives a routing branch name for every newly created session and records it
+in `state.json.branch`, seeds it into the session Markdown's `branch:` line, and mirrors it into
+`current.json.branch` for the currently active session. The derived format is:
+
+```
+agent/<actor>/<slug>
+```
+
+`<actor>` comes from the same actor resolver used by liveness tracking
+(`scripts/hooks/lib/actor-identity.js`'s `resolveActor`), and `<slug>` is the session's task slug
+(or the deterministic `--work-item` slug described above).
+
+Neither the resolved actor string nor an arbitrary `--task-slug` is guaranteed to be a valid git
+ref component, so `ensure-session` runs both through an incremental `sanitizeBranchSegment` pass
+before joining them into `agent/<actor>/<slug>`:
+
+1. Replace any `:` with `-` (the actor resolver's own `:` delimiter is not a legal ref character).
+2. Re-run the actor resolver's own charset restriction (`[A-Za-z0-9_.-]`, 64-char cap).
+3. Collapse repeated `..` sequences to a single `-` (git forbids two consecutive dots in a ref
+   component).
+4. Strip a leading `.` (git forbids a component starting with `.`).
+5. Strip a trailing `.` (fix-plan iteration 1, F1 — git forbids a component ending in `.`; the
+   prior pass only handled a run of 2+ trailing dots via the `..`-collapse step above and missed
+   the single-trailing-dot case, e.g. a `--task-slug` of `my-fix.`). This runs *before* the next
+   step so a `.lock` suffix hidden behind trailing dots (e.g. `foo.lock.`) is exposed and still
+   rewritten rather than left dangling.
+6. Rewrite a trailing `.lock` to `-lock` (git forbids a component ending in `.lock`).
+7. If the FINAL result after the above steps is empty, OR is exactly the literal string
+   `unknown`, fall back to `unknown-<hash>` where `<hash>` is the first 6 hex characters of
+   `sha256(<raw input before step 1>)` (fix-plan iteration 1 F4, tightened by iteration 2 F4').
+   The hash is deterministic (same raw input always derives the same fallback, preserving the
+   "never re-derive an existing session's branch" guarantee below) but makes two *different*
+   raw inputs that both land on the fallback derive distinct branches instead of silently
+   colliding on the bare literal `unknown`. This covers three distinct ways a raw input can land
+   on the fallback, all disambiguated identically with **no exceptions**: an all-garbage input
+   (e.g. `--task-slug "???"`) whose charset filter in step 2 collapses it to nothing; a near-miss
+   input like `"unknown."` or `".unknown"` that step 4/5's leading/trailing-dot stripping
+   collapses down to the literal `unknown`; and a raw input that genuinely *is* the literal
+   string `unknown` verbatim. Iteration 1 exempted that last case (a literal `"unknown"` input
+   was left undisambiguated); iteration 2 (F4') removed that carve-out because it let a literal
+   `--actor unknown` collide, undisambiguated, with a near-miss input like `"unknown."` that
+   collapses to the same segment — every input that reaches the fallback token is now
+   disambiguated uniformly.
+
+As of fix-plan iteration 1 (re-verified against the sanitizer above, see F1 in
+`.kontourai/flow-agents/kontourai-flow-agents-289/kontourai-flow-agents-289--fix-plan-iteration-1.md`),
+this pass empirically closes every concrete git-check-ref-format(1) failure mode reachable
+through it: `sanitizeSegment`'s own `[A-Za-z0-9_.-]` charset restriction (step 2) already strips
+every character git-check-ref-format forbids elsewhere in a ref component — `@`, `{`/`}` (so
+`@{` cannot survive), `/` (so a derived segment can never end with `/`, contain `//`, or itself
+be a bare `@`), whitespace, and other control characters — so none of those were ever actually
+reachable in a *derived* segment even before this iteration; only the single-trailing-dot case
+(step 5, above) was a real, reachable gap, and it is now closed. There is no longer a known
+accepted gap for the derived path. This is still not a from-scratch reimplementation of
+`git-check-ref-format(1)` (e.g. it has not been exhaustively fuzzed against every future git
+version's rule set) — but it is not a partial/best-effort pass either.
+
+- Pass `--branch <value>` to `ensure-session` to record an explicit value verbatim instead of the
+  derived name. The override only applies while creating a brand-new session.
+- Unlike the derived path, an explicit `--branch` is **not** sanitized — it is caller intent and
+  may legitimately contain `/` (to nest under an existing convention), so `ensure-session`
+  strictly *validates* it instead and dies with a remediation message, before writing any session
+  artifact. Validation runs in two passes:
+  1. Whole-string lexical checks (fix-plan iteration 1, F2) — the value must not:
+     - contain a control character, newline, or space;
+     - start or end with `/`, or contain `//`;
+     - start with `.`, or contain a `..` sequence;
+     - end with `.` or `.lock`; or
+     - contain any character outside `[A-Za-z0-9_./-]`.
+  2. Per-`/`-component lexical checks (fix-plan iteration 2, F2') — the whole-string checks above
+     only examine the very start/end of the full value, so a charset-legal value can still smuggle
+     an invalid path component past them (e.g. `-lead`, `a/.b`, `foo.lock/bar`, `a/./b`). Every
+     `/`-delimited component must not be empty, must not be exactly `.`, must not start with `.`
+     or `-` (applied uniformly to every component, not just the first — intentionally stricter
+     than git strictly requires, which is fine for a caller-facing override flag), and must not
+     end with `.` or `.lock`.
+  3. Belt-and-braces (fix-plan iteration 2, F2'): once both lexical passes above succeed, the real
+     `git check-ref-format --branch <value>` binary is invoked (argv-array, no shell, 5-second
+     timeout) as the final authority. It can only ever *reject* a value the lexical checks already
+     let through — never re-legalize one they rejected — so it closes any residual gap between this
+     hand-rolled lexical pass and git's actual ref-name rules. When git cannot be spawned at all
+     (not installed) or does not complete within the timeout, this step is skipped silently and the
+     lexical checks above remain the sole authority.
+
+  A value that passes all of the above is recorded exactly as given (no trimming, no
+  sanitization).
+- `ensure-session` only records the branch **name** — in `state.json`, the session Markdown, and
+  `current.json`. It does not run `git checkout -b` or `git worktree add`; creating and checking
+  out the actual branch/worktree remains the calling skill's responsibility (see
+  [ADR 0021](adr/0021-assignment-leases-and-stale-claim-takeover.md) §3).
+- Resuming an existing session directory never re-derives or overwrites its already-recorded
+  `branch` — the session Markdown's existing `branch:` line always wins, regardless of which
+  actor next calls `ensure-session` against that slug. This is what makes takeover continuity
+  ("resume the incumbent's branch, never a parallel one") true by construction; see
+  [ADR 0021](adr/0021-assignment-leases-and-stale-claim-takeover.md) §5.
+- `branch` is an optional field in `workflow-state.schema.json` for migration honesty: legacy
+  `state.json` files that predate this convention have no `branch` key and still validate.
+  `workflow:validate-artifacts` prints a non-blocking `WARN` line to stderr (not a hard failure)
+  when a `state.json` has no `branch` field, naming the gap without breaking legacy
+  sessions/fixtures.
+
 Reviewer Markdown artifacts can be imported into `critique.json`:
 
 ```bash
-npm run workflow:sidecar -- import-critique .flow-agents/<slug> .flow-agents/<slug>/<slug>--review.md
+npm run workflow:sidecar -- import-critique .kontourai/flow-agents/<slug> .kontourai/flow-agents/<slug>/<slug>--review.md
 ```
 
 Core workflow skills should use these writer commands when available. If a writer command or validation is unavailable or blocked, the artifact should record the exact sidecar gap as `NOT_VERIFIED` rather than silently falling back to an unstructured pass.
@@ -381,17 +490,17 @@ Use release-readiness for this evidence-gate PASS. Decide whether to MERGE, RELE
 
 ## 10. Promote Final Acceptance Docs
 
-`.flow-agents/<slug>/` is local runtime/session state by default in the Flow Agents source tree. Exported agent bundles may map the runtime root to a distribution-specific path through their bundle instructions. Treat local workflow roots as working memory for a delivery. After provider checks pass and the work is merged or otherwise accepted, promote the useful parts into durable documentation, provider comments/descriptions, release notes, or archive records.
+`.kontourai/flow-agents/<slug>/` is local runtime/session state by default in the Flow Agents source tree. Exported agent bundles may map the runtime root to a distribution-specific path through their bundle instructions. Treat local workflow roots as working memory for a delivery. After provider checks pass and the work is merged or otherwise accepted, promote the useful parts into durable documentation, provider comments/descriptions, release notes, or archive records.
 
 Use the helper:
 
 ```bash
-npm run promote-workflow-artifact -- .flow-agents/<slug>/<slug>--deliver.md
+npm run promote-workflow-artifact -- .kontourai/flow-agents/<slug>/<slug>--deliver.md
 ```
 
 Expected behavior:
 
-- copy the source artifact into `.flow-agents/<slug>/archive/<date>/`
+- copy the source artifact into `.kontourai/flow-agents/<slug>/archive/<date>/`
 - create or update a durable doc under `docs/delivery/`
 - include the plan, evidence, Goal Fit, and Final Acceptance sections when present
 - link the durable doc back to the archived artifact so future readers can inspect why and how the feature was built
@@ -430,7 +539,7 @@ flow-agents console-learning-projection --artifact-root .flow-agents --kontour-r
 
 Those flags are the defaults. The command writes `.kontour/projections/flow-agents-learning/<scope-kind>-<scope-id>.json`. Generated learnings are inert, non-authoritative Console read models with `family: "workflow"` and `nonAuthority: true`. `learning.json` remains the Flow Agents-owned source data; the command does not mutate it, execute routing or prevention, create provider issues, implement Source/Sink storage, add UI, or model domain-learning. The producer performs minimal projection source-shape checks for required fields; full `learning.json` JSON Schema validation remains covered by `npm run workflow:validate-artifacts`. When a sibling Console checkout is available, `inspectLocalKontour` may inspect the generated projection, but Flow Agents local tests validate the committed projection shape.
 
-For local-only users, `.flow-agents/<slug>/` is the recent recovery cache and queue dashboard. Retain active blockers and unresolved learning. Prune or archive routine successful runtime artifacts after 14-30 days once provider records, durable docs, or knowledge notes contain the useful history. Keep security, migration, release, or provider-governance evidence longer when auditability matters, usually 30-90 days unless a project policy says otherwise.
+For local-only users, `.kontourai/flow-agents/<slug>/` is the recent recovery cache and queue dashboard. Retain active blockers and unresolved learning. Prune or archive routine successful runtime artifacts after 14-30 days once provider records, durable docs, or knowledge notes contain the useful history. Keep security, migration, release, or provider-governance evidence longer when auditability matters, usually 30-90 days unless a project policy says otherwise.
 
 ## Quick Prompt Templates
 
@@ -455,7 +564,7 @@ Use evidence-gate. Map acceptance criteria to evidence, inspect CI and scope int
 Check local goal fit:
 
 ```text
-Before final answer, update the Goal Fit Gate in the current `.flow-agents/<slug>/` delivery artifact. Keep working on unchecked items unless I explicitly accept them.
+Before final answer, update the Goal Fit Gate in the current `.kontourai/flow-agents/<slug>/` delivery artifact. Keep working on unchecked items unless I explicitly accept them.
 ```
 
 Release decision:
@@ -484,7 +593,7 @@ The `RESUME:` block supplements the existing `STATE:` line and contains:
 - **Next step** — the first `handoff.json next_steps` entry.
 - **Blockers** — any recorded blockers from `handoff.json`, or "none".
 - **Trust** — `Trust: N verified / M disputed / T total` from reading `trust.bundle`. Each disputed or unknown claim is listed with its id and a copy-pasteable remedy command: `npm run workflow:sidecar -- claim <id> <dir>`.
-- **Liveness advisory** (when applicable) — `[LIVENESS WARNING: another agent appears live on this work: actor <X>, last seen <T>]` when the shared liveness stream (`.flow-agents/liveness/events.jsonl`, ADR 0012) contains a fresh claim or heartbeat from a different actor for the same slug. This is advisory only — the hook exits 0 regardless.
+- **Liveness advisory** (when applicable) — `[LIVENESS WARNING: another agent appears live on this work: actor <X>, last seen <T>]` when the shared liveness stream (`.kontourai/flow-agents/liveness/events.jsonl`, ADR 0012) contains a fresh claim or heartbeat from a different actor for the same slug. This is advisory only — the hook exits 0 regardless. The block also always includes an `ACTOR: <actor> (<source>)` line — the same runtime-agnostic actor identity this session resolves for itself (see "Actor identity and liveness writes" below), so a resuming agent can see at a glance which identity its own liveness claims/heartbeats will be filed under.
 - **Route hint** — `To continue: resume this work. Or run pull-work to assess WIP and start new/parallel work.` — always routes the resume-vs-parallel decision through `pull-work` rather than auto-taking it.
 
 The `RESUME:` block appears on `SessionStart` only. `UserPromptSubmit` and `PostToolUse`
@@ -493,16 +602,24 @@ behavior is unchanged.
 All reads are fail-open: a missing `handoff.json`, `trust.bundle`, or liveness stream
 degrades gracefully — the section is omitted or shows "no data", and the hook never throws.
 
-The liveness freshness check is read-only (ADR 0012). Writing or excluding liveness claims
-is scoped to issue #151 (a later slice). The session-level event log (Layer 2) is also
-deferred.
+The `RESUME:` advisory read above is read-only (ADR 0012); liveness *writes* happen
+elsewhere in the lifecycle and already exist today: `init-plan` claims the active slug and
+`advance-state` heartbeats/releases it. As of #288, `FLOW_AGENTS_LIVENESS` defaults **on** —
+presence is ambient by default. Set it to `off`/`0`/`false`/`no`/`disabled`
+(case-insensitive) to opt back out. Claim TTL defaults to `1800` seconds and is
+configurable via `FLOW_AGENTS_LIVENESS_TTL_SECONDS`; per ADR 0012 §4, tuning this value is
+itself the operational risk — too tight manufactures false reclaims, so treat liveness as
+advisory and double-check against real branch/PR state before tightening it. A throttled
+tool-activity heartbeat also rides ordinary tool use (see "Tool-activity heartbeat"
+below), so a long-running wave never goes stale on TTL alone just because it hasn't hit a
+phase transition. The session-level event log (Layer 2) is still deferred.
 
 ### Shared liveness helper
 
 The freshness logic is centralised in `scripts/hooks/lib/liveness-read.js` (pure CJS,
 zero dependencies). It exports:
 
-- `readLivenessEvents(streamPath)` — reads a `.flow-agents/liveness/events.jsonl` file
+- `readLivenessEvents(streamPath)` — reads a `.kontourai/flow-agents/liveness/events.jsonl` file
   line-by-line, JSON-parses each, and tolerates malformed lines.
 - `freshHolders(events, slug, selfActor, nowMs)` — returns actors (excluding `selfActor`)
   who hold a within-TTL claim or heartbeat on `subjectId === slug`.
@@ -510,3 +627,125 @@ zero dependencies). It exports:
 Both the hook (`scripts/hooks/workflow-steering.js`) and the compiled CLI
 (`build/src/cli/workflow-sidecar.js`) consume this helper so the TTL/freshness logic lives
 in one place.
+
+### Tool-activity heartbeat
+
+`scripts/hooks/lib/liveness-heartbeat.js` (pure CJS, zero dependencies — same sharing pattern
+as `liveness-read.js` and `actor-identity.js`) exports `maybeEmitHeartbeat({ cwd, env, now })`.
+All four telemetry hook wrappers (`scripts/hooks/{claude,codex,opencode,pi}-telemetry-hook.js`)
+call it whenever the current invocation's canonical event resolves to `postToolUse`. Per
+[`docs/spec/runtime-hook-surface.md`](spec/runtime-hook-surface.md) row 280, `PostToolUseFailure`
+is a **Claude Code-only** additional native event mapped onto canonical `postToolUse` — Codex,
+Kiro, opencode, and pi each map only their own single native `postToolUse`-equivalent event
+(`PostToolUse`, `PostToolUse`, `tool.execute.after`, `tool_result` respectively); no other
+runtime has a distinct "failure" variant. The heartbeat call runs independently of the existing
+`telemetry.sh` spawn. On each call it:
+
+1. Checks `isLivenessEnabled()` — no-ops (`disabled`) if `FLOW_AGENTS_LIVENESS` is off.
+2. Reads `current.json`'s `active_slug` and resolves the actor (`actor-identity.js`) — no-ops
+   if there is no active slug or the actor cannot be resolved. These two checks run *before*
+   actor resolution specifically so a repo with liveness disabled, or with no active session,
+   never pays the actor resolver's process-ancestry `ps` spawn cost.
+3. Reads a **bounded tail** (the last 64KB, newline-aligned so a partial line at the truncation
+   boundary is dropped) of the `liveness/events.jsonl` stream, filtered for that
+   `(subjectId, actor)` pair. Because the stream is append-only, this bounded read is exact for
+   any pair whose most recent event lies within that window — which, in steady state, is always
+   true within one throttle period. Only if the pair has **zero** matching events anywhere in
+   the tail (the rare case of the first heartbeat after a claim old enough to have scrolled out
+   of the last 64KB) does it fall back to one full read of the stream. No-ops if there is no
+   prior `claim` event from this actor for this subject, or if the actor's most recent event for
+   the subject is a `release`.
+4. Throttles: only appends a new `heartbeat` event once at least
+   `FLOW_AGENTS_LIVENESS_HEARTBEAT_THROTTLE_SECONDS` (default `60`) seconds have elapsed since
+   that actor's last recorded event for the subject.
+
+The throttle window is derived from the actor-scoped stream tail itself — there is
+deliberately no separate, mutable "last heartbeat" state file. Per ADR 0021 §3 (which lists
+"advance-state + tool activity" heartbeats as one of the cross-cutting liveness touchpoints,
+riding existing writes rather than a bespoke timer), a shared state file keyed on anything
+less specific than the actor would reintroduce the same last-writer-wins race that ADR 0021
+is designed to close. Each actor only ever contends with its own prior writes, so there is no
+cross-session race to guard against.
+
+`maybeEmitHeartbeat` is fail-open, matching the #287 actor-identity convention below: any
+error is caught, a diagnostic is written to stderr, and the call returns without throwing — it
+never blocks the tool call, never alters a wrapper's stdout/success-output shape, and never
+changes a wrapper's exit code. It also does not read or depend on `TELEMETRY_ENABLED` —
+disabling telemetry does not disable liveness heartbeats, and vice versa; the two are
+independent, sibling concerns.
+
+### Overlap detection and correction
+
+Two composable mechanisms (#320) tighten the gap ADR 0012 §4 names — a false-stale
+double-hold is *detected*, not *prevented*, and liveness stays advisory, never a lock: a
+deterministic **tiebreaker CLI** (`liveness verdict`) that lets a losing session
+self-correct within the same `pull-work` pass, and a **mid-turn conflict injection** that
+surfaces another actor's fresh claim on a session's own held subject inside its own
+tool-call context, on the runtimes whose hook contract supports it. Neither mechanism
+mutates GitHub/provider state or introduces a new state file (ADR 0012 §5); each closes
+one of the cross-cutting liveness touchpoints ADR 0021 §3 lists, without implementing
+that ADR's still-Draft takeover/supersede or publish-gate slices.
+
+The table below documents the full selection/mid-flight/publish latency budget — where a
+double-hold can occur, what detects it, what corrects it, and the typical latency before
+correction happens:
+
+| Window | What can go wrong | Detector | Corrector | Typical latency |
+| --- | --- | --- | --- | --- |
+| **Selection** | Two sessions both select and claim the same subject in the same narrow read-then-write window (#166). | `pull-work`'s preflight (`### 1a. Liveness Selection Preflight`) plus its post-claim re-check (`### Post-Claim Conflict Re-check`), both reading `liveness status`. | `liveness verdict` computes the deterministic winner; the losing session runs `liveness release` and returns to `### 3. Select Work` to reselect in the same pass (#320). | One `pull-work` pass — seconds. |
+| **Mid-flight** | After selection, another actor claims the same subject while this session is mid-execution, before its next natural checkpoint. | The tool-activity heartbeat's bounded tail read (#288), extended to also run the conflict check on the same in-memory buffer, zero added I/O (#320). | Claude Code and Codex: mid-turn hook feedback (`hookSpecificOutput.additionalContext`) surfaced on the very next tool call. opencode and pi: a stderr diagnostic only today (their generated plugin/extension does not consume telemetry-wrapper stdout — a disclosed gap, tracked in #333, not closed by this issue); all four runtimes still fall back to the pre-existing next-turn `workflow-steering.js` `[LIVENESS WARNING: ...]` digest. | Claude Code/Codex: next tool call. opencode/pi: next `SessionStart` or a manual check, plus the stderr diagnostic at the time of the conflicting tool call. |
+| **Publish** | Two sessions both believe they hold exclusive claim at the moment of publish (merge/release). | Not yet implemented. | Not yet implemented — the `verify-hold` publish gate (ADR 0021 §3, tracked as #293). | Would be blocking, at publish time. |
+
+The Publish row is **not implemented by this issue** — it is named here so the table is
+read as an honest latency-budget map, not mistaken for a claim that overlap detection is
+fully closed end-to-end. See [ADR 0012](adr/0012-agent-coordination-as-liveness-claims.md)
+§4 and [ADR 0021](adr/0021-assignment-leases-and-stale-claim-takeover.md) §3 for the
+underlying design rationale.
+
+### Actor identity and liveness writes
+
+Liveness claims/heartbeats/releases are attributed to a runtime-agnostic **actor struct**
+`{runtime, session_id, host, human?}`, serialized (via `serializeActor()` in the shared
+`scripts/hooks/lib/actor-identity.js` resolver — same sharing pattern as `liveness-read.js`
+above) into a single string safe for the existing `${subjectId}::${actor}` grouping key. The
+serialized actor string embeds this machine's `os.hostname()` — so `liveness/events.jsonl` (and
+therefore `.kontourai/flow-agents/` as a whole) can indirectly reveal hostnames of every host
+that has claimed work in this repo; `.kontourai/` must stay gitignored (it already is, by
+default) and must never be force-added (`git add -f`) or bundled into a shareable support
+bundle without first reviewing it for this kind of incidental host-identifying information. Both
+`workflow-sidecar`'s `liveness` command and `workflow-steering.js`'s SessionStart advisory
+consume the same `resolveActor()` function, so a session's own claim/heartbeat events are
+never mistaken for "another agent."
+
+`resolveActor()` derives the actor automatically, with zero required configuration, via a
+priority chain:
+
+1. An explicit `FLOW_AGENTS_ACTOR` env override, if set (and not the literal `"local"`,
+   case-insensitive) — always wins.
+2. A runtime-native session-id env var already ambient in the current process's own
+   environment — confirmed for Claude Code (`CLAUDE_CODE_SESSION_ID`); the equivalent var for
+   Codex/opencode/pi is unverified as of this writing.
+3. A process-ancestry fallback (the resolver's parent PID plus that parent process's exact
+   start timestamp, hashed into a short opaque token) — needs no runtime cooperation, is
+   stable across repeated invocations within one session, and is distinct across concurrent
+   sessions on one host. This is the correctness backstop for runtimes whose native
+   session-id env var is not yet confirmed.
+
+**Liveness writes fail loud.** `liveness claim`, `liveness heartbeat`, and `liveness release`
+exit nonzero with remediation text whenever the resolved actor is empty or the literal
+`"local"` (case-insensitive) — they never silently fall back to the old shared `"local"`
+default. Fix: pass `--actor <id>` explicitly, set `FLOW_AGENTS_ACTOR=<id>`, or run inside a
+supported runtime so the derivation chain above can resolve a real identity.
+
+**Liveness reads stay backward-compatible.** `liveness status` and `freshHolders()` (in
+`liveness-read.js`) continue to parse, group, and label pre-existing events whose `actor`
+field is the literal string `"local"` without error or behavior change — only *new* writes
+are rejected, not historical data.
+
+This actor struct is the same shape referenced by
+[ADR 0012](adr/0012-agent-coordination-as-liveness-claims.md) and by
+[ADR 0021](adr/0021-assignment-leases-and-stale-claim-takeover.md) §2 (`AssignmentProvider`)
+as the forward-looking identity model for durable assignment. ADR 0021 is still Draft, and its
+other slices (`AssignmentProvider`, the janitor, takeover/supersede, the verify-hold publish
+gate) are **not** implemented by this change — only the actor struct and derivation chain
+described here.

package/evals/acceptance/DEMO-false-completion.md

@@ -39,16 +39,23 @@ variance is the problem. You cannot ship "the model will probably catch it."
 ### With Flow Agents (block mode, shipped default) — refused, deterministically
 
 The Stop is blocked and the agent receives this exact, evidence-grounded refusal
-(`stop-goal-fit` hook, captured verbatim):
+(`stop-goal-fit` hook, captured verbatim from the same seeded `add-auth` fixture run
+directly through `scripts/hooks/stop-goal-fit.js` with `FLOW_AGENTS_GOAL_FIT_MODE=block`):
 ```
-[Hook] Goal Fit warning:
- - add-auth--deliver.md Markdown PASS contradicts evidence.json verdict fail.
- - add-auth evidence verdict:fail; do not deliver without accepted gap or new evidence.
- - add-auth evidence check unit-tests status:fail: 3 unit tests are still failing
-[Hook] Goal Fit BLOCK 1/3.
+[stop-gate] Goal Fit warning:
+ - .kontourai/flow-agents/add-auth/add-auth--deliver.md is still status:executing (0m old). Do not final-answer as complete unless the next step is explicit.
+ - .kontourai/flow-agents/add-auth workflow state: status:in_progress phase:verification; next_action:continue "Fix the 3 failing unit tests."
+ - .kontourai/flow-agents/add-auth next action: Fix the 3 failing unit tests.
+ - .kontourai/flow-agents/add-auth evidence verdict:fail; do not deliver without accepted gap or new evidence.
+  → fix the failing check, or record it as an accepted gap with justification in the session artifact
+ - .kontourai/flow-agents/add-auth evidence check unit-tests status:fail: 3 unit tests are still failing
+  → fix the failing check, or record it as an accepted gap with justification in the session artifact
+[stop-gate] Stop blocked — 5 evidence gap(s) (block 1; after 3 identical blocks I stop blocking and hand this to you)
 ```
 This is not model judgment — it is a hook reading the evidence file. It fires the same
-way every time, on every model. (Block exit 2 → the runtime's Stop is denied.)
+way every time, on every model. (Block exit 2 → the runtime's Stop is denied. The
+`[stop-gate]` prefix becomes `[<flowId>/<gateId>]`, e.g. `[builder.build/verify-gate]`,
+when the session has an active FlowDefinition gate; see `loadActiveFlowStep`.)
 
 ---
 
@@ -115,11 +122,13 @@ the model can't talk its way around.
 
 ## How each arm was run
 
-- **Codex live**: use the dedicated installer, which flattens the config to the home root
-  and copies your real auth from `~/.codex`:
+- **Codex live**: use the dedicated installer, which flattens the config to the Codex home
+  root and copies your real auth from `~/.codex`. By default it targets `CODEX_HOME`, or
+  `~/.codex` when `CODEX_HOME` is unset; pass a positional path only for an explicit
+  isolated or test install:
   ```bash
-  bash scripts/install-codex-home.sh "$HOME/.flow-agents/codex"
-  CODEX_HOME="$HOME/.flow-agents/codex" codex exec --dangerously-bypass-hook-trust -C <project> "<prompt>"
+  bash scripts/install-codex-home.sh
+  codex exec --dangerously-bypass-hook-trust -C <project> "<prompt>"
   ```
   Verified live: from a bare `continue`, Codex re-grounded and created `RESUMED.txt`.
 - **Claude live**: `dist/claude-code/install.sh <workspace>` then `claude -p` from the

package/evals/acceptance/prove-capture-teeth-declared.sh

@@ -37,11 +37,11 @@ trap cleanup EXIT
 # ─── helper: seed a minimal delivered workflow artifact ───────────────────────
 seed_repo() { # $1=dir $2=slug
   local p="$1" slug="$2"
-  mkdir -p "$p/.flow-agents/$slug"
+  mkdir -p "$p/.kontourai/flow-agents/$slug"
   printf '# Repo\n' > "$p/AGENTS.md"
   printf '%s' "{\"schema_version\":\"1.0\",\"task_slug\":\"$slug\",\"status\":\"delivered\",\"phase\":\"done\",\"updated_at\":\"2026-06-27T00:00:00Z\",\"next_action\":{\"status\":\"done\",\"summary\":\"done\"}}" \
-    > "$p/.flow-agents/$slug/state.json"
-  cat > "$p/.flow-agents/$slug/$slug--deliver.md" << MD
+    > "$p/.kontourai/flow-agents/$slug/state.json"
+  cat > "$p/.kontourai/flow-agents/$slug/$slug--deliver.md" << MD
 # $slug
 
 branch: main
@@ -65,7 +65,7 @@ write_declared_bundle() { # $1=bundle-path
   python3 - "$1" << 'PY'
 import json, sys
 bundle = {
-    "schemaVersion": 3,
+    "schemaVersion": 5,
     "source": "flow-agents/workflow-sidecar",
     "claims": [{
         "id": "c1",
@@ -138,13 +138,13 @@ seed_repo "$T1" "declared-false"
 
 # current.json: active FlowDefinition
 printf '%s' '{"artifact_dir":"declared-false","active_flow_id":"builder.build","active_step_id":"verify"}' \
-  > "$T1/.flow-agents/current.json"
+  > "$T1/.kontourai/flow-agents/current.json"
 
-write_declared_bundle "$T1/.flow-agents/declared-false/trust.bundle"
+write_declared_bundle "$T1/.kontourai/flow-agents/declared-false/trust.bundle"
 
 # command-log: npm test recorded as FAIL — the independent truth source says FAILED
 printf '%s\n' '{"command":"npm test","observedResult":"fail","exitCode":1,"capturedAt":"2026-06-27T00:00:00Z","source":"postToolUse-capture"}' \
-  > "$T1/.flow-agents/declared-false/command-log.jsonl"
+  > "$T1/.kontourai/flow-agents/declared-false/command-log.jsonl"
 
 set +e
 t1_out="$(FLOW_AGENTS_GOAL_FIT_MODE=block \
@@ -186,13 +186,13 @@ T2="$TMP/t2"
 seed_repo "$T2" "declared-pass"
 
 printf '%s' '{"artifact_dir":"declared-pass","active_flow_id":"builder.build","active_step_id":"verify"}' \
-  > "$T2/.flow-agents/current.json"
+  > "$T2/.kontourai/flow-agents/current.json"
 
 # Reuse same bundle (trusts pass) but command-log confirms pass
-python3 - "$T2/.flow-agents/declared-pass/trust.bundle" << 'PY'
+python3 - "$T2/.kontourai/flow-agents/declared-pass/trust.bundle" << 'PY'
 import json, sys
 bundle = {
-    "schemaVersion": 3,
+    "schemaVersion": 5,
     "source": "flow-agents/workflow-sidecar",
     "claims": [{
         "id": "c2",
@@ -229,7 +229,7 @@ PY
 
 # command-log: npm test recorded as PASS — confirming evidence
 printf '%s\n' '{"command":"npm test","observedResult":"pass","exitCode":0,"capturedAt":"2026-06-27T00:00:00Z","source":"postToolUse-capture"}' \
-  > "$T2/.flow-agents/declared-pass/command-log.jsonl"
+  > "$T2/.kontourai/flow-agents/declared-pass/command-log.jsonl"
 
 set +e
 t2_out="$(FLOW_AGENTS_GOAL_FIT_MODE=block \
@@ -260,12 +260,12 @@ seed_repo "$T3" "wf-false"
 
 # No current.json active flow → loadActiveFlowStep returns null → workflow.* fallback
 printf '%s' '{"artifact_dir":"wf-false"}' \
-  > "$T3/.flow-agents/current.json"
+  > "$T3/.kontourai/flow-agents/current.json"
 
-python3 - "$T3/.flow-agents/wf-false/trust.bundle" << 'PY'
+python3 - "$T3/.kontourai/flow-agents/wf-false/trust.bundle" << 'PY'
 import json, sys
 bundle = {
-    "schemaVersion": 3,
+    "schemaVersion": 5,
     "source": "flow-agents/workflow-sidecar",
     "claims": [{
         "id": "c3",
@@ -302,7 +302,7 @@ PY
 
 # command-log: npm test recorded as FAIL
 printf '%s\n' '{"command":"npm test","observedResult":"fail","exitCode":1,"capturedAt":"2026-06-27T00:00:00Z","source":"postToolUse-capture"}' \
-  > "$T3/.flow-agents/wf-false/command-log.jsonl"
+  > "$T3/.kontourai/flow-agents/wf-false/command-log.jsonl"
 
 set +e
 t3_out="$(FLOW_AGENTS_GOAL_FIT_MODE=block \

package/evals/acceptance/prove-capture-teeth.sh

@@ -6,7 +6,7 @@
 # claimed-pass command, and that a matching capture log lets Stop through.
 #
 # Mirrors prove-teeth.sh: installs each bundle and runs the installed hook commands
-# with seeded .flow-agents state, exactly as the runtime would on PostToolUse / Stop.
+# with seeded .kontourai/flow-agents state, exactly as the runtime would on PostToolUse / Stop.
 #
 # Usage: bash evals/acceptance/prove-capture-teeth.sh
 set -uo pipefail
@@ -34,12 +34,12 @@ PY
 # Seed: model CLAIMS the command passed (evidence.json) but the deterministic
 # capture log recorded it as FAIL — a false-completion the gate must catch.
 seed_capture_false_pass(){ # $1 project dir
-  local p="$1"; mkdir -p "$p/.flow-agents/cap-false"
+  local p="$1"; mkdir -p "$p/.kontourai/flow-agents/cap-false"
   [ -f "$p/AGENTS.md" ] || printf '# Repo\n' > "$p/AGENTS.md"
-  printf '%s' '{"schema_version":"1.0","task_slug":"cap-false","status":"delivered","phase":"done","updated_at":"2026-06-23T00:00:00Z","next_action":{"status":"done","summary":"done"}}' > "$p/.flow-agents/cap-false/state.json"
-  printf '%s' '{"schema_version":"1.0","task_slug":"cap-false","verdict":"pass","checks":[{"id":"unit-tests","kind":"command","status":"pass","command":"npm test","summary":"tests passed"}]}' > "$p/.flow-agents/cap-false/evidence.json"
-  printf '%s\n' '{"command":"npm test","observedResult":"fail","exitCode":1,"capturedAt":"2026-06-23T00:00:00Z","source":"postToolUse-capture"}' > "$p/.flow-agents/cap-false/command-log.jsonl"
-  cat > "$p/.flow-agents/cap-false/cap-false--deliver.md" <<'MD'
+  printf '%s' '{"schema_version":"1.0","task_slug":"cap-false","status":"delivered","phase":"done","updated_at":"2026-06-23T00:00:00Z","next_action":{"status":"done","summary":"done"}}' > "$p/.kontourai/flow-agents/cap-false/state.json"
+  printf '%s' '{"schema_version":"1.0","task_slug":"cap-false","verdict":"pass","checks":[{"id":"unit-tests","kind":"command","status":"pass","command":"npm test","summary":"tests passed"}]}' > "$p/.kontourai/flow-agents/cap-false/evidence.json"
+  printf '%s\n' '{"command":"npm test","observedResult":"fail","exitCode":1,"capturedAt":"2026-06-23T00:00:00Z","source":"postToolUse-capture"}' > "$p/.kontourai/flow-agents/cap-false/command-log.jsonl"
+  cat > "$p/.kontourai/flow-agents/cap-false/cap-false--deliver.md" <<'MD'
 # Cap False
 
 branch: main
@@ -76,15 +76,15 @@ run_bundle(){ # $1 label, $2 install.sh, $3 settings-json-rel, $4 home-env-name
 
   # The capture hook deterministically records a real command result through the
   # installed adapter path.
-  mkdir -p "$proj/.flow-agents/live-cap"
+  mkdir -p "$proj/.kontourai/flow-agents/live-cap"
   [ -f "$proj/AGENTS.md" ] || printf '# Repo\n' > "$proj/AGENTS.md"
-  printf '%s' '{"schema_version":"1.0","task_slug":"live-cap","status":"in_progress","phase":"verification","updated_at":"2026-06-23T00:00:00Z"}' > "$proj/.flow-agents/live-cap/state.json"
+  printf '%s' '{"schema_version":"1.0","task_slug":"live-cap","status":"in_progress","phase":"verification","updated_at":"2026-06-23T00:00:00Z"}' > "$proj/.kontourai/flow-agents/live-cap/state.json"
   printf '{"hook_event_name":"PostToolUse","tool_name":"Bash","cwd":"%s","tool_input":{"command":"npm run lint"},"error":"command failed"}' "$proj" \
     | env "$homevar=$home" CLAUDE_PROJECT_DIR="$home" bash -c "$capcmd" >/dev/null 2>&1 || true
-  if rg -q '"command":"npm run lint","observedResult":"fail"' "$proj/.flow-agents/live-cap/command-log.jsonl" 2>/dev/null; then
+  if rg -q '"command":"npm run lint","observedResult":"fail"' "$proj/.kontourai/flow-agents/live-cap/command-log.jsonl" 2>/dev/null; then
     _p "$label capture hook records a real FAIL to command-log.jsonl through the installed adapter"
   else
-    _f "$label capture hook did not record the command result: $(cat "$proj/.flow-agents/live-cap/command-log.jsonl" 2>/dev/null)"
+    _f "$label capture hook did not record the command result: $(cat "$proj/.kontourai/flow-agents/live-cap/command-log.jsonl" 2>/dev/null)"
   fi
 
   # --- Teeth: claims-pass-but-log-shows-fail → Stop is BLOCKED ---
@@ -95,7 +95,7 @@ run_bundle(){ # $1 label, $2 install.sh, $3 settings-json-rel, $4 home-env-name
   echo "$blk" | is_block && _p "$label BLOCKS a claimed-pass command that the capture log recorded as FAIL" || _f "$label did NOT block the captured false-completion: $blk"
 
   # control: a matching capture log (pass) lets Stop through on the capture axis.
-  printf '%s\n' '{"command":"npm test","observedResult":"pass","exitCode":0,"capturedAt":"2026-06-23T00:00:00Z","source":"postToolUse-capture"}' > "$proj/.flow-agents/cap-false/command-log.jsonl"
+  printf '%s\n' '{"command":"npm test","observedResult":"pass","exitCode":0,"capturedAt":"2026-06-23T00:00:00Z","source":"postToolUse-capture"}' > "$proj/.kontourai/flow-agents/cap-false/command-log.jsonl"
   local okblk; okblk="$(printf '{"hook_event_name":"Stop","cwd":"%s"}' "$proj" | env "$homevar=$home" CLAUDE_PROJECT_DIR="$home" FLOW_AGENTS_GOAL_FIT_BACKSTOP=skip bash -c "$stopcmd" 2>&1)"
   if echo "$okblk" | grep -q 'caught false-completion'; then
     _f "$label control: a confirming capture log should not raise a false-completion"