@kontourai/flow-agents 3.1.0 → 3.2.0

package/scripts/ci/trust-reconcile.js

@@ -522,32 +522,139 @@ const DELIVERY_DIR = 'delivery';
 
 /**
  * Single seam: every delivery/ path resolution in this file routes through here.
- * #335 (per-session delivery paths, e.g. delivery/<session-slug>/<filename> instead of
- * one shared path) is expected to change ONLY this function's body — e.g. glob
- * delivery/<slug-glob>/<filename> and return every match in a defined precedence order,
- * or
- * resolve the current PR's session slug and return its single subpath. discoverBundle()
- * and discoverDeclaredMarker() both iterate whatever candidates this returns and pick the
- * first existing one, so a future per-session layout composes with zero call-site changes.
+ *
+ * #335/#379 (per-session delivery paths) is IMPLEMENTED here now, not deferred: a shared
+ * `delivery/<filename>` guarantees a git merge conflict between ANY two concurrent
+ * deliveries — and a conflicting (DIRTY) PR gets NO `pull_request` workflows scheduled, so
+ * the required Trust Reconcile check silently never runs (field incidents #330/#358/#378).
+ * The fix is per-session paths so concurrent deliveries write to DISTINCT files and never
+ * contend.
+ *
+ * Returned candidate order (precedence, first is highest):
+ *   1. the flat `delivery/<filename>` — kept FIRST for full back-compat. A repo that never
+ *      adopts per-session layout sees byte-identical behavior; an already-committed flat
+ *      bundle from before this change still resolves.
+ *   2. `delivery/<slug>/<filename>` for every immediate subdirectory of `delivery/`, sorted
+ *      by name for determinism.
+ *
+ * Ordering here is ONLY the tie-break / fallback. Which candidate actually reconciles is
+ * decided by COMMIT-OWNERSHIP (discoverBundle() + bundleAttestsThisChange()), not directory
+ * order: among the candidates, the one whose checkpoint attests an ancestor-or-equal commit
+ * of THIS change wins, and stale siblings from other concurrent sessions are ignored.
+ * discoverBundle() and discoverDeclaredMarker() both iterate whatever this returns, so the
+ * per-session layout composes with zero call-site changes.
  */
 function resolveDeliveryCandidates(repoRoot, filename) {
-  return [path.join(repoRoot, DELIVERY_DIR, filename)];
+  const deliveryRoot = path.join(repoRoot, DELIVERY_DIR);
+  const candidates = [path.join(deliveryRoot, filename)];
+  // #379: append delivery/<slug>/<filename> for each immediate subdirectory of delivery/.
+  // readdirSync is best-effort — a missing delivery/ (or an unreadable one) yields just the
+  // flat candidate, never throws.
+  let entries = [];
+  try {
+    entries = fs.readdirSync(deliveryRoot, { withFileTypes: true });
+  } catch {
+    entries = [];
+  }
+  const subdirs = entries
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .sort();
+  for (const name of subdirs) {
+    candidates.push(path.join(deliveryRoot, name, filename));
+  }
+  return candidates;
 }
 
 /**
  * Auto-discover the delivery bundle when no explicit path is provided.
- * Checks delivery/trust.bundle, then delivery/trust.checkpoint.json under repo root
- * (via resolveDeliveryCandidates()). Returns null if neither is present — the caller
- * then falls through to delivery/DECLARED marker resolution (ADR 0022 §1); bundle
- * absence is no longer fail-open on its own.
+ *
+ * Gathers every existing candidate — flat `delivery/trust.bundle`, flat
+ * `delivery/trust.checkpoint.json`, and their `delivery/<slug>/…` per-session siblings (via
+ * resolveDeliveryCandidates()) — with trust.bundle preferred over trust.checkpoint.json.
+ *
+ * #379 (per-session, ownership-aware selection): when `changeSha` is known, the candidate
+ * whose checkpoint attests an ancestor-or-equal commit of THIS change wins (same
+ * bundleAttestsThisChange() semantics the flat staleness gate already uses). Stale/older
+ * siblings from OTHER concurrent sessions are ignored.
+ *
+ * PREFER-NEWEST among owning candidates. More than one candidate can legitimately "own" the
+ * change at once: an inherited FLAT bundle's commit_sha can be a real ancestor of HEAD in a
+ * merge-commit repo (it was committed on the trunk's linear history before this branch
+ * point), AND this session's fresh per-session bundle attests a NEWER ancestor (the delivery
+ * commit right before HEAD). "First-fresh-wins" would then select the STALE inherited flat
+ * bundle purely because it sorts first — reconciling last delivery's claims against this
+ * change's CI. So among all owning candidates we pick the one attesting the NEWEST commit
+ * (the descendant-most: the owning candidate whose commit_sha every other owning candidate's
+ * commit_sha is an ancestor of), via the same `git merge-base --is-ancestor` primitive. This
+ * makes an inherited/older owning bundle HARMLESS whether or not it was ever pruned — the
+ * fresh per-session bundle wins on recency, not on being deleted first.
+ *
+ * When no candidate owns this change (or `changeSha` is unknown, e.g. a local run with no
+ * TRUST_RECONCILE_SHA), the first existing candidate is returned so the caller's staleness
+ * gate below handles it exactly as before: a stale bundle is treated as absent, a malformed
+ * one still raises the Step 2 read error.
+ *
+ * Returns null if no candidate exists at all — the caller then falls through to
+ * delivery/DECLARED marker resolution (ADR 0022 §1); bundle absence is not fail-open.
  */
-function discoverBundle(repoRoot) {
+function discoverBundle(repoRoot, changeSha) {
+  const candidates = [];
   for (const filename of ['trust.bundle', 'trust.checkpoint.json']) {
     for (const candidate of resolveDeliveryCandidates(repoRoot, filename)) {
-      if (fs.existsSync(candidate)) return candidate;
+      if (fs.existsSync(candidate)) candidates.push(candidate);
     }
   }
-  return null;
+  if (candidates.length === 0) return null;
+
+  const deliveryRoot = path.join(repoRoot, DELIVERY_DIR);
+  const hasPerSession = candidates.some((c) => path.dirname(c) !== deliveryRoot);
+
+  // Ownership-aware selection (#379). Only meaningful when we know this change's sha; a
+  // candidate that fails to parse is skipped here (never treated as owning) — if it turns
+  // out to be the only candidate, it is still returned below so Step 2's "failed to read
+  // bundle" diagnostic fires unchanged.
+  if (changeSha) {
+    const owning = []; // { candidate, bundleSha } — every candidate that attests this change
+    for (const candidate of candidates) {
+      let json = null;
+      try {
+        json = JSON.parse(fs.readFileSync(candidate, 'utf8'));
+      } catch {
+        json = null;
+      }
+      if (!json) continue;
+      const { fresh, bundleSha } = bundleAttestsThisChange(repoRoot, candidate, json, changeSha);
+      if (fresh) owning.push({ candidate, bundleSha });
+    }
+    if (owning.length > 0) {
+      // Prefer the owning candidate attesting the NEWEST (descendant-most) commit. `best` is
+      // upgraded to a candidate whose commit is a strict descendant of the current best's —
+      // i.e. best.sha is an ancestor of cand.sha. Every owning entry has a non-null bundleSha
+      // (bundleAttestsThisChange returns fresh=false otherwise). Ties / incomparable siblings
+      // keep the earlier (candidate-order) entry, so the flat path still wins a genuine tie.
+      let best = owning[0];
+      for (let i = 1; i < owning.length; i++) {
+        const cand = owning[i];
+        if (cand.bundleSha !== best.bundleSha && isAncestorCommit(repoRoot, best.bundleSha, cand.bundleSha)) {
+          best = cand;
+        }
+      }
+      if (hasPerSession) {
+        process.stdout.write(`[trust-reconcile] #379: selected delivery candidate ${path.relative(repoRoot, best.candidate)} — attests this change ${changeSha} (${candidates.length} candidate(s) present across flat + per-session delivery/<slug>/; ${owning.length} owning, newest wins; older/stale ignored)\n`);
+      }
+      return best.candidate;
+    }
+    // No candidate attests this change. When per-session candidates were in play, emit a
+    // loud, grep-stable concurrency hint (#379) so the next agent can tell a concurrent
+    // per-session collision apart from a plain stale/absent bundle — the per-candidate
+    // stale line still prints in runTrustReconcile's staleness gate for the returned one.
+    if (hasPerSession) {
+      const rels = candidates.map((c) => path.relative(repoRoot, c)).join(', ');
+      process.stdout.write(`[trust-reconcile] #379: examined ${candidates.length} delivery candidate(s) (flat + per-session delivery/<slug>/); none attests this change ${changeSha}. If this is a concurrent-delivery collision, the OWNING session's bundle is not on this ref — re-publish this session's delivery, or check whether main moved under the PR. Candidates: ${rels}\n`);
+    }
+  }
+  return candidates[0];
 }
 
 /**
@@ -813,22 +920,30 @@ function resolveDeclaredExemption(repoRoot, ctx) {
  * src/cli/workflow-sidecar.ts). trust.bundle itself carries NO commit/branch metadata
  * (schemaVersion 5: {schemaVersion, source, claims, evidence, policies, events} — confirmed
  * by inspection), so when the discovered bundle IS trust.bundle, this falls through to its
- * sibling delivery/trust.checkpoint.json (same resolveDeliveryCandidates() seam) for the
- * binding — publishDelivery() always copies both together.
+ * SIBLING trust.checkpoint.json for the binding — publishDelivery() always writes both
+ * together into the SAME directory.
+ *
+ * #379: the sibling is resolved from the bundle's OWN directory (path.dirname(bundlePath)),
+ * not from a global resolveDeliveryCandidates() scan. In the per-session layout each session
+ * gets its own delivery/<slug>/ dir, and a global scan would cross-contaminate — pairing a
+ * per-session trust.bundle with the FLAT (or a different session's) trust.checkpoint.json and
+ * reading the wrong commit binding. Same-directory resolution is identical to the prior
+ * behavior for the flat layout (delivery/trust.bundle ↔ delivery/trust.checkpoint.json) and
+ * correct for per-session.
  */
 function extractBundleCommitSha(repoRoot, bundlePath, bundleJson) {
   if (bundleJson && typeof bundleJson.commit_sha === 'string' && bundleJson.commit_sha.trim()) {
     return bundleJson.commit_sha.trim();
   }
-  for (const candidate of resolveDeliveryCandidates(repoRoot, 'trust.checkpoint.json')) {
-    if (candidate === bundlePath || !fs.existsSync(candidate)) continue;
+  const siblingCheckpoint = path.join(path.dirname(bundlePath), 'trust.checkpoint.json');
+  if (siblingCheckpoint !== bundlePath && fs.existsSync(siblingCheckpoint)) {
     try {
-      const checkpoint = JSON.parse(fs.readFileSync(candidate, 'utf8'));
+      const checkpoint = JSON.parse(fs.readFileSync(siblingCheckpoint, 'utf8'));
       if (checkpoint && typeof checkpoint.commit_sha === 'string' && checkpoint.commit_sha.trim()) {
         return checkpoint.commit_sha.trim();
       }
     } catch {
-      // Malformed sibling checkpoint — no usable binding from it; keep looking / fall through.
+      // Malformed sibling checkpoint — no usable binding from it; fall through to null.
     }
   }
   return null;
@@ -907,14 +1022,17 @@ function runTrustReconcile({ bundle = null, commands = [], repoRoot = null, mani
   // (.github/workflows/trust-reconcile.yml) never passes --bundle; it always relies on
   // auto-discovery, which is exactly the path PR #278's stale-bundle incident went through.
   const explicitBundlePath = bundle || process.env.TRUST_RECONCILE_BUNDLE || null;
-  let bundlePath = explicitBundlePath || discoverBundle(resolvedRepoRoot) || null;
-  const bundleWasAutoDiscovered = !explicitBundlePath && !!bundlePath;
 
-  // Scope-matching context (ref/actor/sha) — resolved once, reused by both the
-  // bundle-ownership staleness check below and the delivery/DECLARED exemption path
-  // further down (bundle-absent branch).
+  // Scope-matching context (ref/actor/sha) — resolved once, reused by ownership-aware
+  // auto-discovery (#379, immediately below), the bundle-ownership staleness check further
+  // down (ADR 0022 addendum §2), and the delivery/DECLARED exemption path (bundle-absent
+  // branch). Resolved BEFORE auto-discovery because discoverBundle() now uses scopeCtx.sha
+  // to pick, among per-session candidates, the one that attests THIS change.
   const scopeCtx = resolveScopeContext(resolvedRepoRoot);
 
+  let bundlePath = explicitBundlePath || discoverBundle(resolvedRepoRoot, scopeCtx.sha) || null;
+  const bundleWasAutoDiscovered = !explicitBundlePath && !!bundlePath;
+
   // Event-scoped enforcement (ADR 0022 addendum, part 4): bundle-required enforcement
   // (and the staleness-gate consequence of it, immediately below) applies ONLY when this
   // run is gating a proposed change. A push run on main happens AFTER the gating PR run

package/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/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 };