@kontourai/flow-agents 3.1.0 → 3.3.0

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

@@ -104,8 +104,9 @@ const fixtureOwnerPolicies = new Map([
     ["evals/fixtures/pull-work-provider", { owners: ["evals/integration/test_pull_work_provider.sh"], classification: "work item provider normalization fixtures" }],
     ["evals/fixtures/pull-work-wip-shepherding", { owners: ["evals/static/test_workflow_skills.sh"], classification: "WIP shepherding state fixtures" }],
     ["evals/fixtures/surface-trust", { owners: ["evals/integration/test_workflow_sidecar_writer.sh"], classification: "Surface trust evidence fixtures" }],
-    ["evals/fixtures/trust-reconcile-exploits", { owners: ["evals/integration/test_trust_reconcile_negatives.sh"], classification: "WS8 trust-reconcile anti-gaming exploit fixtures (frozen negative regressions)" }],
-    ["evals/fixtures/trust-reconcile-mixed-bundle", { owners: ["evals/integration/test_trust_reconcile_mixed_bundle.sh"], classification: "WS8 trust-reconcile mixed-evidence end-to-end proof fixture" }],
+    ["evals/fixtures/reconcile-preflight", { owners: ["evals/integration/test_reconcile_preflight.sh"], classification: "#356 reconcile-preflight shape fixtures not already covered by trust-reconcile-exploits (un-superseded disputed critique, standalone disputed session-local claim)" }],
+    ["evals/fixtures/trust-reconcile-exploits", { owners: ["evals/integration/test_trust_reconcile_negatives.sh", "evals/integration/test_reconcile_preflight.sh"], classification: "WS8 trust-reconcile anti-gaming exploit fixtures (frozen negative regressions); also reused by the #356 local reconcile-preflight eval (same shapes, no forked copies)" }],
+    ["evals/fixtures/trust-reconcile-mixed-bundle", { owners: ["evals/integration/test_trust_reconcile_mixed_bundle.sh", "evals/integration/test_reconcile_preflight.sh"], classification: "WS8 trust-reconcile mixed-evidence end-to-end proof fixture; also reused by the #356 reconcile-preflight eval as its CLEAN-BUNDLE (AC4) case" }],
     ["evals/fixtures/trust-reconcile-ws3", { owners: ["evals/integration/test_trust_reconcile_negatives.sh"], classification: "WS8 AC6 backward-compat fixture: real ws3-kit-dependencies-namespacing old-style bundle" }],
     ["evals/fixtures/usage-feedback", { owners: ["evals/integration/test_usage_feedback_import.sh", "evals/integration/test_usage_feedback_outcomes.sh", "evals/integration/test_usage_feedback_report.sh"], classification: "usage feedback import/outcome fixtures" }],
     ["evals/fixtures/veritas-governance-adapter", { owners: ["evals/integration/test_veritas_governance_adapter.sh"], classification: "Veritas governance adapter fixtures" }],

package/context/contracts/artifact-contract.md

@@ -44,8 +44,7 @@ candidate selector — do not build new discovery logic. `active_wip`,
 `active_learning_followup`, `cleanup_candidate`, and `invalid` sessions are **never**
 archival candidates on age alone.
 
-Procedure (documented; archival itself remains a deliberate, non-automated move — the audit
-tool "does not delete, archive," by design):
+Procedure (manual, hand-driven):
 
 1. `node build/src/cli/workflow-artifact-cleanup-audit.js <artifact-root>` to classify.
 2. From the `terminal_done` bucket, select those whose `state.json` `updatedAt` predates the
@@ -53,6 +52,21 @@ tool "does not delete, archive," by design):
 3. Move each selected `<artifact-root>/<slug>/` to `<artifact-root>/archive/<slug>/`
    (a human-reviewed or explicitly-invoked move — not a silent background job).
 
+Automated `--apply` mode: `workflow-artifact-cleanup-audit --apply` (see
+`docs/workflow-artifact-lifecycle.md`'s "Apply Mode" section) automates the
+`cleanup_candidate`/aged-`terminal_done` selection above, but archive-moves to a
+*different*, sibling destination — `.kontourai/flow-agents-archive/<date>-<runid>/<slug>/`,
+next to the artifact root, not `<artifact-root>/archive/<slug>/`. The run-scoped,
+sibling root keeps two same-day `--apply` runs from colliding and keeps the artifact
+root's own scan set stable while a run is in progress; it is not a replacement for the
+in-tree `<artifact-root>/archive/<slug>/` convention above, which remains the right
+destination for a manual, hand-driven move. `--apply` never deletes anything (archive-move
+only) and is gated by hard safety rails (never `active_wip`/`active_learning_followup`,
+never a held liveness claim, never inside the freshness window, never an infrastructure
+directory, never a substantive session misclassified `invalid` by a schema nit) — see the
+doc section for the full model, including the `--apply-ambiguous` second gate and the
+`MANIFEST.md`/`--confirm` evidence record.
+
 ## Persistence Integrity
 
 Writing a durable artifact must **fail loud, never fail-open.** If a record (state, evidence, a

package/context/contracts/assignment-provider-contract.md

@@ -94,7 +94,7 @@ delivers all four:
 | --- | --- | --- | --- |
 | `claim` | the claiming session | at selection | **#290 (this issue)** |
 | `claim` / `supersede` | `ensure-session`'s pre-entry ownership guard (a SECOND mutator, alongside `assignment-provider claim`) | on session entry, before any session directory is created — `free` establishes a claim, `reclaimable` requires explicit `--supersede-stale` | **#291** |
-| `clean_release` | the incumbent (Stop hook / terminal `advance-state`) | session end — unassign + handoff comment | #292 |
+| `clean_release` | the incumbent (Stop hook / terminal `advance-state`) | session end — unassign + handoff comment | **#292** — the Stop hook (`scripts/hooks/stop-goal-fit.js`) on clean non-terminal session end: liveness release + local-file assignment release (`performLocalRelease`) run inline; for the github provider the hook cannot run `gh`, so it honestly defers via a `provider_release_pending` handoff intent rather than pretending to complete the release |
 | `supersede` | the successor, inside the takeover protocol | after the grace beat | #294 |
 | `crash_no_successor` | nobody, initially; corrected by the next actor to want the subject, or the janitor | lazily, or on a janitor sweep | out of scope — the Console relay's first cross-machine duty (ADR 0021 §4/§7) |
 

package/context/contracts/execution-contract.md

@@ -67,6 +67,84 @@ model backs which delegate role. This contract only says where to read it.
   fallback in the session/task artifact — do not block delegation on datum
   being present.
 
+### Tier ladder
+
+The delegate roles form a cost/capability ladder that both escalation and the
+Goodhart guard below reference. Lowest to highest:
+
+```
+delegate-mechanical  <  delegate-implementation  <  delegate-design
+```
+
+`orchestrator` is off-ladder — it is the session's own model (planning, gates,
+adversarial verification), typically inherited rather than overridden, and sits
+above `delegate-design` for escalation purposes. `extraction-default` is a
+non-delegate role (bulk extraction) and is not part of this ladder.
+
+### Escalation on gate failure
+
+Delegate at the step's hinted tier, then let the gates enforce cost safety:
+
+- Dispatch the delegate at the tier its skill hint names (a cheap tier for
+  mechanical/fully-specified work).
+- On a review or verify **gate FAILURE of that delegate's output**, re-dispatch
+  the **fix** one tier higher on the ladder — `delegate-mechanical` failures
+  escalate to `delegate-implementation`, `delegate-implementation` failures to
+  `delegate-design`, and a `delegate-design` failure escalates to the
+  `orchestrator` / a human decision. Do not re-dispatch the fix at the same
+  tier that already failed its gate.
+- Record every escalation in the session artifact (see *Routing decisions in
+  the run artifact* below) with the tier it climbed **from**, so the run shows
+  why a more expensive model was used.
+- This is the fail-closed cost story: cheap tiers are safe **because** the gates
+  catch their misses and escalate. Routing cheap-by-default never weakens
+  verification — an ungated cheap delegate is what this ladder exists to prevent.
+
+### Goodhart guard (review/verify never cheaper than the work)
+
+Review and verify roles resolve at a tier **greater than or equal to** the tier
+of the work they check; they never auto-downgrade below it.
+
+- If the checked work was produced at `delegate-design`, its reviewer/verifier
+  resolves `delegate-design` (or `orchestrator`) — never `delegate-implementation`
+  or `delegate-mechanical`.
+- If the checked work was produced at `delegate-implementation`, its
+  reviewer/verifier resolves at `delegate-implementation` or higher.
+- Rationale: a cheaper checker rubber-stamping a more capable worker's output
+  defeats the gate and turns the routing table into a Goodhart target (optimize
+  the cost metric, lose the thing the metric was a proxy for). The gate must be
+  at least as capable as the work, or the fail-closed escalation story above is
+  hollow.
+
+### Routing decisions in the run artifact
+
+Record each delegation's resolved role and model on the session artifact so a
+downstream economics record (`flow-agents#349`) can price role assignments and a
+baseline harness (`flow-agents#350`) can A/B tiers. Use the sidecar writer's
+`record-agent-event` (additive `--role` / `--model` / `--escalated-from` flags):
+
+```bash
+# per-delegation routing decision
+npm run workflow:sidecar -- record-agent-event \
+  --agent-id <delegate-id> --kind delegation --status active \
+  --role <resolved-role> --model "<resolved-model@provider>" \
+  --summary "<what was delegated>"
+
+# an escalate-on-gate-failure re-dispatch
+npm run workflow:sidecar -- record-agent-event \
+  --agent-id <delegate-id> --kind escalation --status active \
+  --role <higher-tier-role> --model "<resolved-model@provider>" \
+  --escalated-from <lower-tier-role> \
+  --summary "<gate that failed> failed at <lower-tier-role>; fix re-dispatched one tier higher"
+```
+
+These land as top-level `role`, `model`, and (for escalations) `escalated_from`
+fields on the JSONL event under `agents/<agent-id>/events.jsonl`. The shape is
+additive: events without a routing decision are byte-identical to before, so no
+existing consumer breaks. An economics consumer reads events where `role` is
+present as one priced delegation each; `escalated_from` marks the entries that
+cost more because a gate caught a cheaper tier.
+
 ## Completion Rules
 
 Execution is complete only when:

package/context/scripts/hooks/config-protection.js

@@ -180,7 +180,9 @@ function checkProtectedPathPattern(filePath) {
   // copy a forged bundle here to corrupt the CI trust check.
   // SAFE: publishDelivery writes via fs.copyFileSync (not Write/Edit tool).
   // RESIDUAL: runtime-constructed paths and fs writes are unaffected.
-  if (/(?:^|\/)delivery\/trust\.bundle$/.test(norm)) {
+  // #379: the optional (?:[^/]+\/)? segment also covers the per-session path
+  // delivery/<slug>/trust.bundle — the forgery surface moved with the write path.
+  if (/(?:^|\/)delivery\/(?:[^/]+\/)?trust\.bundle$/.test(norm)) {
     return {
       name: "delivery/trust.bundle",
       reason: "an agent could write a forged bundle to corrupt the CI trust-reconcile anchor",
@@ -189,7 +191,8 @@ function checkProtectedPathPattern(filePath) {
 
   // delivery/trust.checkpoint.json -- the signed checkpoint companion.
   // SAFE: publishDelivery writes via fs.copyFileSync, NOT via Write/Edit tool.
-  if (/(?:^|\/)delivery\/trust\.checkpoint\.json$/.test(norm)) {
+  // #379: optional (?:[^/]+\/)? segment also covers delivery/<slug>/trust.checkpoint.json.
+  if (/(?:^|\/)delivery\/(?:[^/]+\/)?trust\.checkpoint\.json$/.test(norm)) {
     return {
       name: "delivery/trust.checkpoint.json",
       reason: "an agent could forge a signed delivery by writing a tampered checkpoint",
@@ -421,7 +424,9 @@ function checkCommandForBypass(command) {
  * .kontourai/flow-agents/<slug>/trust.bundle, and deprecated runtime-shaped
  * .flow-agents equivalents.
  */
-const REDIRECT_PROTECTED_RE = /(?:^|\/|~\/)(\.bash_profile|\.bashrc|\.profile|\.zprofile|\.zshrc)$|(?:^|\/)\.claude\/settings(?:\.local)?\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/current\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/current\/[^/]+\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/\.goal-fit-block-streak\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/[^/]+\/state\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/[^/]+\/trust\.bundle$|(?:^|\/)delivery\/trust\.bundle$|(?:^|\/)delivery\/trust\.checkpoint\.json$/;
+// #379: the delivery/ arms carry an optional (?:[^/]+\/)? segment so redirects/tee to the
+// per-session path delivery/<slug>/trust.bundle (+ checkpoint) are caught, not just the flat path.
+const REDIRECT_PROTECTED_RE = /(?:^|\/|~\/)(\.bash_profile|\.bashrc|\.profile|\.zprofile|\.zshrc)$|(?:^|\/)\.claude\/settings(?:\.local)?\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/current\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/current\/[^/]+\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/\.goal-fit-block-streak\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/[^/]+\/state\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/[^/]+\/trust\.bundle$|(?:^|\/)delivery\/(?:[^/]+\/)?trust\.bundle$|(?:^|\/)delivery\/(?:[^/]+\/)?trust\.checkpoint\.json$/;
 
 /**
  * Return true when a token (an unquoted redirect target or tee argument) matches
@@ -569,8 +574,10 @@ function checkInterpreterWriteToProtected(command) {
  * Delivery-protected path regex: delivery/trust.bundle and delivery/trust.checkpoint.json.
  * These are the CI anchor files whose contents must not be agent-forged.
  * Used by checkCopyMoveToProtected to catch `cp x delivery/trust.bundle`.
+ * #379: the optional (?:[^/]+\/)? segment also catches the per-session path
+ * `cp forged.json delivery/<slug>/trust.bundle`.
  */
-const DELIVERY_COPY_PROTECTED_RE = /(?:^|\/)delivery\/trust\.bundle$|(?:^|\/)delivery\/trust\.checkpoint\.json$/;
+const DELIVERY_COPY_PROTECTED_RE = /(?:^|\/)delivery\/(?:[^/]+\/)?trust\.bundle$|(?:^|\/)delivery\/(?:[^/]+\/)?trust\.checkpoint\.json$/;
 
 /**
  * Return true when a normalized token matches a delivery-protected path.

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

@@ -25,6 +25,7 @@
 'use strict';
 
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
 const { spawnSync } = require('child_process');
 const crypto = require('crypto');
@@ -42,7 +43,7 @@ const {
   flowAgentsArtifactRoot,
   flowAgentsArtifactRootsForRead,
 } = require('./lib/local-artifact-paths');
-const { resolveActor } = require('./lib/actor-identity.js');
+const { resolveActor, isUnresolvedActor, detectRuntime } = require('./lib/actor-identity.js');
 const { readCurrentPointer } = require('./lib/current-pointer.js');
 
 const MAX_STDIN = 1024 * 1024;
@@ -1671,7 +1672,7 @@ async function analyze(root, now = Date.now()) {
     artifacts = artifacts.filter(a => a && hasSidecarPresence(path.dirname(a.file)));
   }
 
-  if (artifacts.length === 0) return { warnings: [], blocking: false };
+  if (artifacts.length === 0) return { warnings: [], blocking: false, latestArtifactDir: null };
 
   const latest = artifacts[0];
   const latestArtifactDir = path.dirname(latest.file);
@@ -1745,7 +1746,7 @@ async function analyze(root, now = Date.now()) {
     if (/\[backstop in warn mode — not blocking\]/.test(w)) return false;
     return blockRe.test(w);
   });
-  return { warnings, blocking, preExecution, gatePrefix: gateLabel(activeFlowStep) };
+  return { warnings, blocking, preExecution, gatePrefix: gateLabel(activeFlowStep), latestArtifactDir };
 }
 
 /**
@@ -1844,12 +1845,266 @@ function remediationFor(warning) {
   return null;
 }
 
+// ─── #292 Wave 2: Stop-hook non-terminal release-with-handoff ────────────────
+//
+// When a session's Stop event fires and the session's state.json status is NOT
+// one of workflow-sidecar.ts's LIVENESS_TERMINAL statuses (delivered/accepted/
+// archived — the SAME set advance-state's terminal path already tests against,
+// imported here rather than re-declared, per AC8), the liveness claim and (for
+// the local-file assignment provider) the durable assignment claim would
+// otherwise sit held until TTL, even though the session has genuinely ended.
+// This closes that gap: always emit a provider-agnostic liveness release (AC1),
+// and for local-file additionally perform the real release inline (AC2), while
+// honestly disclosing (never executing) the equivalent GitHub-provider release
+// as a pending handoff.json intent (AC3). See the plan artifact
+// (.kontourai/flow-agents/kontourai-flow-agents-292/kontourai-flow-agents-292--plan-work.md,
+// "Wave 2") for the full design rationale and the render-don't-execute
+// constraint this deliberately does not cross.
+//
+// Fail-open (AC7): the ENTIRE body runs under one try/catch. Any failure —
+// missing build/, corrupt assignment record, unresolved actor, missing/
+// malformed provider settings — degrades to a single stderr diagnostic and
+// returns, never throwing, never affecting the Stop hook's own exit code or
+// goal-fit's warnings/blocking output (this function's return value is not
+// consumed by that contract at all — it is a pure side effect).
+
+/**
+ * require() the compiled workflow-sidecar.js the same hasBuild/fs.existsSync-guarded
+ * way loadActiveFlowStep() already requires flow-resolver.js. Returns null (never
+ * throws) when build/ is absent or the require fails — the caller treats null as
+ * "the LIVENESS_TERMINAL boundary is unknown; do not guess it" and skips the whole
+ * release (fail-open, never a re-derived duplicate Set — AC8).
+ */
+function loadWorkflowSidecarBuilt() {
+  const packageRoot = path.resolve(__dirname, '..', '..');
+  const builtSidecar = path.join(packageRoot, 'build', 'src', 'cli', 'workflow-sidecar.js');
+  if (!fs.existsSync(builtSidecar)) return null; // hasBuild guard
+  try {
+    const mod = require(builtSidecar);
+    if (!(mod.LIVENESS_TERMINAL instanceof Set)) return null;
+    return mod;
+  } catch {
+    return null; // require failed — fail-open
+  }
+}
+
+/** Same hasBuild-guarded require idiom, for build/src/cli/assignment-provider.js. */
+function loadAssignmentProviderBuilt() {
+  const packageRoot = path.resolve(__dirname, '..', '..');
+  const builtProvider = path.join(packageRoot, 'build', 'src', 'cli', 'assignment-provider.js');
+  if (!fs.existsSync(builtProvider)) return null;
+  try {
+    const mod = require(builtProvider);
+    if (typeof mod.performLocalRelease !== 'function') return null;
+    return mod;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the effective assignment-provider kind for this repo ('local-file' | 'github'),
+ * or null when it cannot be determined. Prefers reading context/settings/
+ * assignment-provider-settings.json directly (project settings first, matching
+ * effective-assignment-provider-settings.ts's own lookup precedence) rather than shelling
+ * out to or refactoring that CLI-shaped file (see plan Unresolved Question 1) — this task's
+ * scope is the Stop hook, not that file. Returns null (never guesses) when no settings file
+ * is present/parseable or names no provider kind for a project entry.
+ *
+ * Deliberately reads ONLY the project settings file (context/settings/
+ * assignment-provider-settings.json relative to repo root) — the common case for this repo
+ * and the one confirmed present. The effective() merge/repo-matching logic in
+ * effective-assignment-provider-settings.ts is intentionally NOT reimplemented here (that
+ * would fork a second merge algorithm); a repo whose provider kind can only be resolved via
+ * global settings or multi-project merge degrades to "unknown, skip assignment-layer
+ * release" rather than guessing.
+ */
+function resolveAssignmentProviderKind(root) {
+  const settingsFile = path.join(root, 'context', 'settings', 'assignment-provider-settings.json');
+  const settings = readJsonFile(settingsFile);
+  if (!settings) return null;
+  const candidates = [];
+  if (settings.defaults && settings.defaults.provider) candidates.push(settings.defaults.provider);
+  if (Array.isArray(settings.projects)) {
+    for (const project of settings.projects) {
+      if (project && project.provider) candidates.push(project.provider);
+    }
+  }
+  const kind = candidates.map(p => p && p.kind).find(k => k === 'local-file' || k === 'github');
+  return kind || null;
+}
+
+/**
+ * Refresh handoff.json by merge (read+spread the existing file's JSON, overwrite only the
+ * fields this task owns), mirroring advanceState's own handoff-write shape
+ * (`{ ...loadJson(...), ...sidecarBase(slug), summary, current_state_ref: "state.json",
+ * next_steps, blockers: [], warnings: [] }`) and current-pointer.js's writePerActorCurrent
+ * write idiom (`fs.writeFileSync(file, JSON.stringify(payload, null, 2) + "\n")`). next_steps
+ * is appended to (not clobbered) when a provider-release next-step is due.
+ */
+function refreshHandoffAfterRelease(artifactDir, slug, state, providerReleasePending, providerReleaseNextCommand) {
+  const file = path.join(artifactDir, 'handoff.json');
+  const existing = readJsonFile(file) || {};
+  const status = state ? normalizedStatus(state.status || 'unknown') : 'unknown';
+  const phase = state ? normalizedStatus(state.phase || 'unknown') : 'unknown';
+  const summary = (state && state.next_action && state.next_action.summary)
+    ? String(state.next_action.summary)
+    : `session ended at status:${status} phase:${phase}`;
+  const existingNextSteps = Array.isArray(existing.next_steps) ? existing.next_steps.slice() : [];
+  const nextSteps = existingNextSteps.slice();
+  if (providerReleasePending && providerReleaseNextCommand && !nextSteps.includes(providerReleaseNextCommand)) {
+    nextSteps.push(providerReleaseNextCommand);
+  }
+  const payload = {
+    ...existing,
+    schema_version: existing.schema_version || '1.0',
+    task_slug: existing.task_slug || slug,
+    summary,
+    current_state_ref: 'state.json',
+    next_steps: nextSteps,
+    ...(providerReleasePending ? { provider_release_pending: true } : {}),
+    ...(providerReleaseNextCommand ? { provider_release_next_command: providerReleaseNextCommand } : {}),
+  };
+  fs.writeFileSync(file, `${JSON.stringify(payload, null, 2)}\n`);
+}
+
+/**
+ * #292 Wave 2: on a Stop event whose resolved session is at a NON-terminal status, release
+ * the session's liveness claim (always, provider-agnostic — AC1) and, for the local-file
+ * assignment provider, its durable assignment claim too (AC2), then refresh handoff.json
+ * (AC4). A terminal-status session (already released by advance-state) is a deliberate no-op
+ * (AC5). For the github provider, never calls render-release or gh — only records an
+ * honestly-labeled pending intent in handoff.json (AC3). Actor-scoped: only ever releases
+ * the CURRENT actor's own held claim (AC6, enforced inside performLocalRelease).
+ *
+ * Called once from run(), reusing analyze()'s already-resolved latestArtifactDir — this
+ * function does not re-derive "what is the active session" a second time.
+ *
+ * Fail-open (AC7): the entire body is wrapped in one try/catch. Any failure degrades to a
+ * single stderr diagnostic and returns, never throwing, never affecting the Stop hook's exit
+ * code or goal-fit's warnings/blocking contract (this function's return value is unused by
+ * that contract).
+ *
+ * @param {string} root - repo root (as resolved by findRepoRoot)
+ * @param {string|null} artifactDir - analyze()'s already-resolved latestArtifactDir
+ */
+function releaseOnNonTerminalStop(root, artifactDir) {
+  try {
+    if (!artifactDir) return; // no active session resolved — nothing to release.
+
+    const state = readJsonFile(path.join(artifactDir, 'state.json'));
+    if (!state) return; // AC5: no state.json — nothing to gate a release decision on.
+
+    const sidecar = loadWorkflowSidecarBuilt();
+    if (!sidecar) {
+      process.stderr.write('[Hook] Goal Fit: stop-hook release skipped — build/src/cli/workflow-sidecar.js not available (LIVENESS_TERMINAL boundary unknown).\n');
+      return;
+    }
+
+    const status = normalizedStatus(state.status || 'unknown');
+    if (sidecar.LIVENESS_TERMINAL.has(status)) return; // AC5: terminal — advance-state already released.
+
+    // Slug: artifact dir's basename, or state.json's own task_slug field — reuse whichever
+    // this file already has, never a new slug-derivation rule.
+    const slug = (state.task_slug && String(state.task_slug).trim()) || path.basename(artifactDir);
+
+    const { actor } = resolveActor(process.env);
+    if (isUnresolvedActor(actor)) {
+      process.stderr.write(`[Hook] Goal Fit: stop-hook release skipped for "${safeOneLine(slug, 80)}" — actor identity is unresolved; never releasing under a synthetic identity.\n`);
+      return;
+    }
+
+    const flowAgentsDir = path.dirname(artifactDir);
+    const nowIso = new Date().toISOString();
+
+    // AC1: ALWAYS emit the liveness release, regardless of provider kind — liveness is
+    // provider-agnostic and this is the ONE shared writer every other liveness emitter uses.
+    try {
+      require('./lib/liveness-write.js').appendLivenessEvent(flowAgentsDir, {
+        type: 'release',
+        subjectId: slug,
+        actor,
+        at: nowIso,
+        source: 'stop-hook',
+      });
+    } catch (err) {
+      process.stderr.write(`[Hook] Goal Fit: stop-hook liveness release failed for "${safeOneLine(slug, 80)}": ${safeOneLine(err && err.message || err, 160)}\n`);
+    }
+
+    // Resolve the effective assignment-provider kind — unknown means "do not guess",
+    // skip the assignment-layer release entirely (fail-open).
+    const providerKind = resolveAssignmentProviderKind(root);
+    if (!providerKind) {
+      process.stderr.write(`[Hook] Goal Fit: stop-hook release — provider kind unknown for "${safeOneLine(slug, 80)}", skipping assignment-layer release (liveness release already emitted).\n`);
+      refreshHandoffAfterRelease(artifactDir, slug, state, false, null);
+      return;
+    }
+
+    let providerReleasePending = false;
+    let providerReleaseNextCommand = null;
+
+    if (providerKind === 'local-file') {
+      const provider = loadAssignmentProviderBuilt();
+      if (!provider) {
+        process.stderr.write('[Hook] Goal Fit: stop-hook local-file release skipped — build/src/cli/assignment-provider.js not available.\n');
+      } else {
+        try {
+          // Mirror assignment-provider.ts's loadActorStruct() exactly: runtime is derived via
+          // detectRuntime (not a literal 'unknown'), since serializeActor()'s comparison key
+          // includes runtime — a mismatched runtime segment here would make performLocalRelease's
+          // AC6 actor-match check wrongly treat this session's own claim as foreign.
+          //
+          // actorKey: opts.actorKey MUST be the same canonical `resolveActor(env).actor` string
+          // already resolved above (`actor`) — the identical bare-or-triple form
+          // computeEffectiveState()'s holderActorKey preference (`record.actor_key ||
+          // serializeActor(record.actor)`) and performLocalRelease's mirrored ownership check
+          // both key on. Without this, an explicit-override actor's release-side comparison
+          // would fall back to serializeActor(releasedBy) — a re-derived triple that never
+          // equals the stored bare actor_key — and this hook would wrongly treat its own claim
+          // as foreign (the #291 seam, relocated to the release path; see performLocalRelease's
+          // doc comment in src/cli/assignment-provider.ts).
+          const releasedBy = { runtime: detectRuntime(process.env), session_id: actor, host: os.hostname(), human: null };
+          const artifactRoot = flowAgentsArtifactRoot(root);
+          provider.performLocalRelease(artifactRoot, slug, releasedBy, {
+            reason: 'stop-hook non-terminal release',
+            tolerateNoActiveClaim: true,
+            actorKey: actor,
+          });
+        } catch (err) {
+          process.stderr.write(`[Hook] Goal Fit: stop-hook local-file release failed for "${safeOneLine(slug, 80)}": ${safeOneLine(err && err.message || err, 160)}\n`);
+        }
+      }
+    } else {
+      // AC3: github (or any non-local-file kind) — render-don't-execute. Never call
+      // render-release, never invoke gh. Disclose the pending intent honestly.
+      providerReleasePending = true;
+      providerReleaseNextCommand = `npm run workflow -- assignment-provider status --provider github --subject-id "${slug}" ...   # then: assignment-provider render-release --provider github --subject-id "${slug}" ... (emits the gh argv to run)`;
+    }
+
+    // AC4: refresh handoff.json — merge, never fully overwrite.
+    refreshHandoffAfterRelease(artifactDir, slug, state, providerReleasePending, providerReleaseNextCommand);
+  } catch (err) {
+    // Fail-open (AC7): any unexpected failure anywhere above (JSON parse error, fs error,
+    // etc.) must never crash the Stop hook or affect its exit code / goal-fit's output.
+    try {
+      process.stderr.write(`[Hook] Goal Fit: stop-hook release logic error (fail-open): ${safeOneLine(err && err.message || err, 160)}\n`);
+    } catch { /* best-effort diagnostic only */ }
+  }
+}
+
 async function run(rawInput) {
   const input = parseJson(rawInput);
   const root = findRepoRoot(input.cwd || process.cwd());
   const mode = resolveGoalFitMode();
   if (mode === 'off') return rawInput;
   const result = await analyze(root);
+  // #292 Wave 2: additive side effect only — never changes analyze()'s warnings/blocking
+  // contract or this function's return value. Reuses analyze()'s already-resolved
+  // latestArtifactDir rather than re-deriving a second "what is the active session" path.
+  // Runs regardless of whether goal-fit itself has any warnings this turn (AC1: the
+  // liveness release must always be attempted on a non-terminal Stop, independent of
+  // whether goal-fit found anything to warn about).
+  releaseOnNonTerminalStop(root, result.latestArtifactDir || null);
   if (result.warnings.length === 0) {
     clearBlockStreak(root);
     return rawInput;
@@ -1939,4 +2194,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { analyze, run, resolveGoalFitMode, uncheckedInSection, findRepoRoot, sidecarGuidance, safeOneLine, captureCrossReference, bundleEnforcement, loadActiveFlowStep, readCommandLog, resolveTrustedCommand, declaredManifestTarget, verifyCommandLogChain, CHAIN_GENESIS_VERIFY, hasLaunderingOperator };
+module.exports = { analyze, run, resolveGoalFitMode, uncheckedInSection, findRepoRoot, sidecarGuidance, safeOneLine, captureCrossReference, bundleEnforcement, loadActiveFlowStep, readCommandLog, resolveTrustedCommand, declaredManifestTarget, verifyCommandLogChain, CHAIN_GENESIS_VERIFY, hasLaunderingOperator, releaseOnNonTerminalStop };

package/context/scripts/hooks/workflow-steering.js

@@ -159,8 +159,25 @@ function latestWorkflowState(root) {
   return states[0] || null;
 }
 
+// #293 AC7 (injection discipline): strips C0 (0x00-0x1F), DEL (0x7F), and C1 (0x80-0x9F,
+// which includes ANSI-CSI-adjacent bytes) BEFORE whitespace-collapse/truncation — mirroring
+// src/cli/workflow-sidecar.ts's stripControlCharsForDisplay / assignment-provider.ts's
+// sanitizeDisplayField exactly (same charset, same rationale: holder/actor/assignee strings
+// sourced from the shared multi-writer liveness stream or an attacker-postable GitHub comment
+// are untrusted display input). Previously this function only collapsed whitespace, so a raw
+// ESC/BEL byte embedded in a hostile actor string passed through unstripped into every steering
+// notice that calls safeStateText (resumeSteering's LIVENESS WARNING block, supersessionSteering's
+// SUPERSEDED notice) — fixed here, in the one shared helper, rather than in each call site.
 function safeStateText(value, maxLength = 240) {
-  const text = String(value || '').replace(/\s+/g, ' ').trim();
+  // Whitespace-collapse FIRST (so an embedded newline/tab becomes a joining space, preserving
+  // the existing multiline-summary neutralization behavior), THEN strip control/ANSI bytes
+  // (#293 AC7) — reversing this order would strip \n before the collapse ever sees it, losing
+  // the join-space between sentences. Only C0/DEL/C1 bytes THAT SURVIVE the collapse (ESC, BEL,
+  // and other non-whitespace control bytes — real \s already became a plain space above) are
+  // stripped, mirroring src/cli/workflow-sidecar.ts's stripControlCharsForDisplay /
+  // assignment-provider.ts's sanitizeDisplayField charset exactly.
+  const collapsed = String(value || '').replace(/\s+/g, ' ').trim();
+  const text = collapsed.replace(/[\u0000-\u001F\u007F-\u009F]/g, '');
   if (text.length <= maxLength) return text;
   return `${text.slice(0, maxLength - 3)}...`;
 }
@@ -411,6 +428,51 @@ function resumeSteering(root, current) {
   }
 }
 
+/**
+ * Compose the every-turn SUPERSEDED steering notice (issue #293).
+ *
+ * Unlike resumeSteering()'s RESUME block (SessionStart only), this notice must
+ * surface on EVERY turn (UserPromptSubmit as well as SessionStart) once another
+ * actor holds a fresh liveness claim on the caller's own subject — the
+ * "don't publish, you may be stale" signal the verify-hold gate backstops at
+ * publish time. Reuses the SAME liveness-only join resumeSteering()'s liveness
+ * advisory block already performs (freshHolders(events, slug, selfActor, now)),
+ * not a second computation.
+ *
+ * freshHolders() already excludes selfActor internally (see
+ * scripts/hooks/lib/liveness-read.js), so any holder returned here is by
+ * definition another actor — no additional self-filter is required.
+ *
+ * Fully fail-open: any error anywhere in this function returns '' rather than
+ * throwing, matching every other steering helper in this file.
+ *
+ * @param {string} root     Repository root
+ * @param {{ file: string, payload: object }} current  Latest active state entry (this actor's own)
+ * @returns {string}
+ */
+function supersessionSteering(root, current) {
+  try {
+    const state = current.payload;
+    const workflowDir = path.dirname(current.file);
+    const slug = state.task_slug || path.basename(workflowDir);
+
+    const resolved = resolveActor(process.env);
+    const selfActor = resolved.actor || 'local';
+
+    const events = flowAgentsArtifactRootsForRead(root)
+      .flatMap(artifactRoot => readLivenessEvents(path.join(artifactRoot, 'liveness', 'events.jsonl')));
+    if (events.length === 0) return '';
+
+    const holders = freshHolders(events, slug, selfActor, Date.now());
+    if (holders.length === 0) return '';
+
+    const holder = holders[0];
+    return `[SUPERSEDED: another agent appears live on this work: actor ${safeStateText(holder.actor)}, last seen ${holder.lastAt}. Your claim on this subject may be stale — do not publish until you re-verify hold (see verify-hold gate) or hand off.]`;
+  } catch {
+    return '';
+  }
+}
+
 function run(rawInput) {
   try {
     const input = JSON.parse(rawInput);
@@ -451,10 +513,19 @@ function run(rawInput) {
       }
     }
 
+    // Every-turn supersession notice (#293): fires on UserPromptSubmit (every turn),
+    // not just SessionStart, so a takeover mid-session keeps surfacing the warning.
+    if (event === 'UserPromptSubmit' && current) {
+      const supersessionHint = supersessionSteering(root, current);
+      if (supersessionHint) hints.push(supersessionHint);
+    }
+
     // SessionStart only: append the RESUME block for richer situational awareness
     if (event === 'SessionStart' && current) {
       const resumeBlock = resumeSteering(root, current);
       if (resumeBlock) hints.push(resumeBlock);
+      const supersessionHint = supersessionSteering(root, current);
+      if (supersessionHint) hints.push(supersessionHint);
     }
 
     if (shouldAppendWorkflowContext) {
@@ -492,6 +563,7 @@ module.exports = {
   safeStateText,
   stateNeedsAmbientSteering,
   resumeSteering,
+  supersessionSteering,
   promptText,
   looksLikeBuilderWork,
   builderWorkflowSteering,