@kontourai/flow-agents 3.3.0 → 3.4.1

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

@@ -17,9 +17,8 @@
  *
  * Scope: the gate evaluates the session's current task (.kontourai/flow-agents/current.json)
  * when set, so an unrelated active workflow elsewhere in the repo does not gate
- * this stop. It also never hard-blocks a pre-execution (not-yet-started) task on
- * mere incompleteness — only genuine false-completion signals (a claimed pass the
- * capture log or evidence.json contradicts) block before execution begins.
+ * this stop. A pre-execution sidecar remains warning-only unless it has an active
+ * canonical Flow run; once Flow is active, its unfinished gate remains blocking.
  */
 
 'use strict';
@@ -42,9 +41,12 @@ const {
 const {
   flowAgentsArtifactRoot,
   flowAgentsArtifactRootsForRead,
+  resolveSharedRepoRoot,
+  warnIfFailingOpenInsideGitTree,
 } = require('./lib/local-artifact-paths');
 const { resolveActor, isUnresolvedActor, detectRuntime } = require('./lib/actor-identity.js');
 const { readCurrentPointer } = require('./lib/current-pointer.js');
+const { isRunnableCommandText, isAmbiguousAbsenceCommand } = require('./lib/runnable-command.js');
 
 const MAX_STDIN = 1024 * 1024;
 const ACTIVE_STATUSES = new Set([
@@ -66,10 +68,9 @@ const WORKFLOW_SESSION_TYPES = new Set(['deliver', 'delivery', 'fix-bug', 'execu
 const SIDECAR_NAMES = new Set(['state.json', 'handoff.json', 'trust.bundle']);
 const OPTIONAL_SIDECAR_NAMES = new Set();
 
-// A workflow that has not started execution is EXPECTED to be incomplete, so the
-// Stop gate must not hard-block on its missing DOD / Goal Fit / not-done state.
-// Only genuine false-completion signals block a pre-execution task; execution
-// onward gates fully.
+// A sidecar that has not started execution is normally expected to be incomplete.
+// An active canonical Flow run is the exception: its current gate remains live and
+// blocks Stop even while the projected sidecar is in pickup or planning.
 const PRE_EXECUTION_STATUSES = new Set(['new', 'planning', 'planned', 'backlog']);
 const PRE_EXECUTION_PHASES = new Set(['idea', 'backlog', 'pickup', 'planning']);
 
@@ -78,19 +79,48 @@ const PRE_EXECUTION_PHASES = new Set(['idea', 'backlog', 'pickup', 'planning']);
 // not block an unrelated session.
 const TERMINAL_STATUSES = new Set(['done', 'delivered', 'accepted', 'archived', 'complete', 'completed']);
 
+function isTerminalDeliveredState(state) {
+  if (!state || typeof state !== 'object') return false;
+  const status = normalizedStatus(state.status || '');
+  const phase = normalizedStatus(state.phase || '');
+  return TERMINAL_STATUSES.has(status) || phase === 'done';
+}
+
 function parseJson(raw) {
   try { return JSON.parse(raw || '{}'); } catch { return {}; }
 }
 
 function findRepoRoot(startDir) {
-  let dir = path.resolve(startDir || process.cwd());
+  const resolvedStartDir = path.resolve(startDir || process.cwd());
+  // #357: prefer git's SHARED common-dir root (the primary checkout's repo root, resolved
+  // identically from any linked worktree) before falling back to the plain `.git`/AGENTS.md
+  // ancestor walk below. Without this, a worktree's OWN `.git` FILE (not the shared `.git`
+  // DIRECTORY) satisfies `fs.existsSync(path.join(dir, '.git'))` at the very first directory
+  // checked, so the walk always stopped at the worktree root instead of resolving to the
+  // shared primary checkout — see src/lib/local-artifact-root.ts's resolveSharedRepoRoot doc
+  // comment for the full rationale. Fails open to the walk below (unchanged) when git is
+  // unavailable, `resolvedStartDir` is not inside a git working tree, or the command fails —
+  // this is also exactly today's behavior in the single-checkout case, where
+  // `--git-common-dir` resolves to `.git` under `resolvedStartDir` itself.
+  const sharedRoot = resolveSharedRepoRoot(resolvedStartDir);
+  if (sharedRoot) return sharedRoot;
+  let dir = resolvedStartDir;
   const root = path.parse(dir).root;
   for (let depth = 0; dir && depth < 40; depth++) {
-    if (fs.existsSync(path.join(dir, '.git')) || fs.existsSync(path.join(dir, 'AGENTS.md'))) return dir;
+    if (fs.existsSync(path.join(dir, '.git'))) {
+      // #413 iteration-2 Fix 1: resolveSharedRepoRoot failed above even though a `.git` entry
+      // exists right here — git resolution was ATTEMPTED and FAILED (corrupted gitlink, bad
+      // GIT_DIR, git unavailable, etc.), not merely "no git repo at all". Loud, not silent —
+      // see warnIfFailingOpenInsideGitTree's own doc comment for the full rationale. This walk
+      // still returns `dir` (the ancestor-walk fallback is preserved unchanged) after warning.
+      warnIfFailingOpenInsideGitTree(resolvedStartDir, dir);
+      return dir;
+    }
+    if (fs.existsSync(path.join(dir, 'AGENTS.md'))) return dir;
     if (dir === root) break;
     dir = path.dirname(dir);
   }
-  return path.resolve(startDir || process.cwd());
+  return resolvedStartDir;
 }
 
 function walkMarkdown(dir, out = []) {
@@ -577,6 +607,9 @@ function sidecarGuidance(root, artifactDir, activeFlowStep) {
   if (state && state.next_action && normalizedStatus(state.next_action.status) !== 'done') {
     const next = state.next_action;
     warnings.push(`${base} next action: ${safeOneLine(next.summary)}${next.target_phase ? ` (target phase: ${safeOneLine(next.target_phase, 80)})` : ''}`);
+    if (Array.isArray(next.skills) && next.skills.length) warnings.push(`${base} required skills: ${next.skills.map(skill => safeOneLine(skill, 80)).join(' -> ')}`);
+    if (Array.isArray(next.operations) && next.operations.length) warnings.push(`${base} required operations: ${next.operations.map(operation => safeOneLine(operation, 80)).join(' -> ')}`);
+    if (next.command) warnings.push(`${base} next command: ${safeOneLine(next.command, 240)}`);
   }
 
   // ── Evidence verdict + checks: bundle-first, fallback to evidence.json ────
@@ -686,10 +719,58 @@ function normalizeCommand(value) {
   return String(value || '').replace(/\s+/g, ' ').trim();
 }
 
+/**
+ * #362 (iteration-2 fix item 4/LOW): single-sourced human-facing remediation phrase for an
+ * ambiguous bare grep/diff exit-1 command. Every emission site below (captureCrossReference's
+ * capture-log cross-reference branch, its live-backstop-re-run branch, and
+ * capturedFailReconciliation's ambiguous bucket) interpolates this constant rather than
+ * re-duplicating the literal string — mirrors how `isAmbiguousAbsenceCommand` itself is
+ * single-sourced (required once from ./lib/runnable-command.js, never reimplemented per call
+ * site). Cross-ref: src/cli/workflow-sidecar.ts keeps its OWN copy of the shared fragment
+ * (`AMBIGUOUS_REMEDIATION_ADVICE`) for its two record-time emission sites — the two files do not
+ * share a module for this string, so each file single-sources independently.
+ */
+const AMBIGUOUS_REMEDIATION = "re-record this check as a self-asserting command ('! grep ...' or 'grep -c ... | grep -qx 0')";
+
+/**
+ * #362: a bare (non-self-asserting) grep/diff exit 1 is exit-code-AMBIGUOUS (zero
+ * matches/no diff — could be the author's intended PASS for an absence check, or an
+ * unintended miss for a presence check), not a genuine FAIL. This is the SAME narrow,
+ * two-binary-only carve-out `isAmbiguousAbsenceCommand` already applies at capture time
+ * (`evidence-capture.js`'s `observeResult`) — reused here (not reimplemented) so a log
+ * entry's `observedResult` and this re-derivation from raw exitCode can never disagree.
+ * Exit codes >=2 for grep/diff remain hard FAILs (real tool errors) — this carve-out is
+ * exactly exitCode === 1, nothing wider.
+ *
+ * Iteration-2 (re-plan) finding #3 (HIGH): `ambiguous` now has TWO distinct origins, threaded
+ * via the additive `absenceAmbiguous` discriminator so existing #362 callers are unaffected:
+ *   - absence-ambiguous (#362 carve-out): `exitCode===1` on a bare grep/diff — the command
+ *     genuinely RAN and produced exit 1. `absenceAmbiguous:true`.
+ *   - no-signal-ambiguous (rule-3 default): `observedResult==='ambiguous'` with no exit code
+ *     recoverable (e.g. an unreadable codex host banner) — capture saw the command run but got
+ *     NO usable pass/fail signal. `absenceAmbiguous:false`.
+ * Callers that need the #362-specific grep/diff wording/HARD_BLOCK branch on `absenceAmbiguous`;
+ * callers that just need "was this ambiguous at all" keep using `ambiguous`.
+ *
+ * @param {{command?: string, observedResult?: string, exitCode?: number}} entry
+ * @returns {{failed: boolean, ambiguous: boolean, absenceAmbiguous: boolean}}
+ */
+function classifyLogEntry(entry) {
+  const exitCode = Number.isInteger(entry.exitCode) ? entry.exitCode : null;
+  const absenceAmbiguous = exitCode === 1 && isAmbiguousAbsenceCommand(entry.command);
+  const ambiguous = entry.observedResult === 'ambiguous' || absenceAmbiguous;
+  if (ambiguous) return { failed: false, ambiguous: true, absenceAmbiguous };
+  const failed = entry.observedResult === 'fail' || (exitCode !== null && exitCode !== 0);
+  return { failed, ambiguous: false, absenceAmbiguous: false };
+}
+
 /**
  * Read command-log.jsonl into a map of normalized-command -> aggregate outcome.
  * If the same command was run more than once, a single FAIL makes the aggregate
- * a fail (a caught false-completion must not be masked by a later pass-claim).
+ * a fail (a caught false-completion must not be masked by a later pass-claim). A
+ * bare grep/diff exit-1 (#362) is carved out as `ambiguous` rather than `failed` — it
+ * is surfaced as a distinct warning class by callers, never silently dropped, and
+ * never treated as a hard block.
  */
 function readCommandLog(artifactDir) {
   const file = path.join(artifactDir, 'command-log.jsonl');
@@ -704,11 +785,13 @@ function readCommandLog(artifactDir) {
     if (!entry || typeof entry.command !== 'string') continue;
     const key = normalizeCommand(entry.command);
     if (!key) continue;
-    const failed = entry.observedResult === 'fail' || (Number.isInteger(entry.exitCode) && entry.exitCode !== 0);
+    const { failed, ambiguous, absenceAmbiguous } = classifyLogEntry(entry);
     const prev = byCommand.get(key);
     byCommand.set(key, {
       ran: true,
       failed: failed || (prev ? prev.failed : false),
+      ambiguous: !failed && (ambiguous || (prev ? prev.ambiguous : false)),
+      absenceAmbiguous: !failed && (absenceAmbiguous || (prev ? prev.absenceAmbiguous : false)),
       exitCode: Number.isInteger(entry.exitCode) ? entry.exitCode : (prev ? prev.exitCode : null),
     });
   }
@@ -720,7 +803,9 @@ function readCommandLog(artifactDir) {
  * The LAST entry for each command wins (unlike readCommandLog which makes FAIL sticky).
  * Used for both capturedFailReconciliation and captureCrossReference (Fix C): we want to
  * know the LAST result, so a genuine re-run-to-pass clears the earlier FAIL. Only an actual
- * re-run (new PASS entry in the log) clears it — a new claim cannot change the log.
+ * re-run (new PASS entry in the log) clears it — a new claim cannot change the log. #362: a
+ * bare grep/diff exit-1 is carved out as `ambiguous` (via the shared `classifyLogEntry`), not
+ * `failed` — same rationale as `readCommandLog` above.
  */
 function readLatestCommandLog(artifactDir) {
   const file = path.join(artifactDir, 'command-log.jsonl');
@@ -735,11 +820,13 @@ function readLatestCommandLog(artifactDir) {
     if (!entry || typeof entry.command !== 'string') continue;
     const key = normalizeCommand(entry.command);
     if (!key) continue;
-    const failed = entry.observedResult === 'fail' || (Number.isInteger(entry.exitCode) && entry.exitCode !== 0);
-    // LAST entry wins — genuine re-run-to-pass overwrites the earlier FAIL.
+    const { failed, ambiguous, absenceAmbiguous } = classifyLogEntry(entry);
+    // LAST entry wins — genuine re-run-to-pass overwrites the earlier FAIL/ambiguous.
     byCommand.set(key, {
       ran: true,
       failed,
+      ambiguous,
+      absenceAmbiguous,
       exitCode: Number.isInteger(entry.exitCode) ? entry.exitCode : null,
     });
   }
@@ -915,28 +1002,8 @@ function verifyCommandLogChain(artifactDir) {
  *       FLOW_AGENTS_GOAL_FIT_RECHECK=true (the RCE-risky opt-in path).
  * Returns { argv, cwd, source } or null when nothing trusted resolves.
  */
-// WS8 (AC10b): a kind:"command" evidence ref's excerpt/command must be a literally runnable
-// shell command, not a prose description of a manual verification step. This heuristic
-// rejects prose so the goal-fit backstop never spawns `bash -lc "<a sentence>"` and
-// misreports the resulting shell error as a caught false-completion. Pairs with the rule
-// stated in context/contracts/planning-contract.md (AC11).
-function isRunnableCommandText(text) {
-  const s = typeof text === 'string' ? text.trim() : '';
-  if (!s) return false;
-  // Sentence-like prose (a . ! or ? followed by more words) is not a single command.
-  if (/[.!?]\s+\S/.test(s)) return false;
-  const first = s.split(/\s+/)[0] || '';
-  // WS8 (AC10b, iteration 2): the first-token allowlist is broadened to the common
-  // real-world verify binaries a project's runnable evidence names (git, tsc, eslint,
-  // python/python3, docker, curl, jq, diff, grep, test) so honest command evidence is not
-  // misclassified as prose. Still fail-closed for genuinely non-command prose: a bare
-  // sentence whose first token is none of these (and carries no path prefix or shell
-  // metacharacter) is rejected rather than executed.
-  const knownBinary = /^(npm|npx|pnpm|yarn|node|bash|sh|zsh|make|just|task|cargo|go|pytest|tox|deno|bun|ruby|rake|mvn|gradle|dotnet|swift|flutter|dart|git|tsc|eslint|python|python3|docker|curl|jq|diff|grep|test)$/.test(first)
-    || first.startsWith('./') || first.startsWith('/') || first.includes('/');
-  const hasShellMeta = /[|&;<>()$`]/.test(s);
-  return knownBinary || hasShellMeta;
-}
+// WS8 (AC10b): isRunnableCommandText now lives in ./lib/runnable-command.js (single
+// source of truth shared with workflow-sidecar.ts's record-time validation, #412).
 
 function resolveTrustedCommand(root, artifactDir, check, acceptance) {
   // (a) acceptance criterion command for the matching criterion.
@@ -946,6 +1013,32 @@ function resolveTrustedCommand(root, artifactDir, check, acceptance) {
     // is not a runnable shell command is malformed-evidence — reported distinctly, not
     // executed, and not conflated with a caught false-completion.
     if (!isRunnableCommandText(fromAcceptance)) return { malformed: fromAcceptance };
+    // DIALECT-PRESERVATION INVARIANT (#362): from THIS POINT ONWARD, `fromAcceptance` MUST be
+    // passed through to argv[2] unmodified from `acceptanceCommandFor`'s return value — never
+    // re-trimmed, re-escaped, re-quoted, or reconstructed from a parsed/tokenized form. The
+    // recorded command's regex dialect and flags (e.g. `grep -E '(foo|bar)'`'s ERE alternation/
+    // grouping, or any other -E/-P/-G flag combination) are part of the evidence-ref text itself;
+    // re-deriving the command string from anything other than this exact `fromAcceptance` value
+    // would silently reinterpret an ERE-recorded pattern as BRE (or vice versa) on re-run,
+    // corrupting the very check this backstop exists to confirm.
+    //
+    // KNOWN ACCEPTED UPSTREAM BOUNDARY: this guarantee begins at `acceptanceCommandFor`'s return
+    // value, NOT at the raw evidence-ref text — it is NOT "byte-for-byte, exactly as recorded in
+    // the evidence ref" (a prior version of this comment overclaimed that). `acceptanceCommandFor`
+    // derives `fromAcceptance` via `normalizeCommand` (~line 686: `.replace(/\s+/g, ' ').trim()`),
+    // which collapses whitespace runs and trims BEFORE this invariant's scope begins. Regex
+    // dialect metacharacters (-E, |, +, (), etc.) are single characters/short tokens, not
+    // whitespace, so they are untouched by this collapse and survive intact — but a literal
+    // multi-space or tab run *inside* a recorded pattern (e.g. two spaces in `grep -E 'foo  bar'`)
+    // does NOT survive verbatim; it is already collapsed to one space by the time it reaches this
+    // function. That is a pre-existing, accepted normalization boundary (not introduced by this
+    // invariant, and not something this invariant claims to cover) — not a dialect-preservation
+    // gap.
+    // `runBackstop` (below) preserves this invariant on its side by reading `trusted.argv[2]`
+    // verbatim rather than re-joining `argv` with spaces — see runBackstop's own
+    // DIALECT-PRESERVATION INVARIANT comment for that half of the contract.
+    // A regression eval (evals/integration/test_goal_fit_hook.sh, "#362 dialect preservation")
+    // pins this end-to-end with a `grep -E` ERE-only alternation construct.
     return { argv: ['bash', '-lc', fromAcceptance], cwd: root, source: 'acceptance' };
   }
 
@@ -1045,6 +1138,33 @@ function resolveBackstopMode() {
   return 'block';
 }
 
+/**
+ * #362: `classification` is a three-state result (`'pass'`/`'fail'`/`'ambiguous'`) rather than
+ * the old boolean `passed` — `'ambiguous'` iff the re-run command text is a bare (non-negated,
+ * non-count-asserted, non-chained) `grep`/`diff` invocation (`isAmbiguousAbsenceCommand`) AND
+ * `exitCode === 1` (zero matches/no diff — could be the author's intended PASS for an absence
+ * check, never silently coerced to pass OR fail). `'fail'` iff `exitCode !== 0` and not the
+ * ambiguous case (this still includes exitCode >= 2 for grep/diff — a real tool error, e.g. a
+ * missing file — which stays a hard fail, proving the carve-out is narrowly scoped). `'pass'`
+ * iff `exitCode === 0`. `trusted.argv.join(' ')` is passed to `isAmbiguousAbsenceCommand` (it
+ * already unwraps a `bash -lc '<command>'` wrapper on its own, so the `['bash', '-lc', cmd]`
+ * shape `resolveTrustedCommand`'s acceptance/model-command sources produce is inspected
+ * correctly; a `declared`-manifest-target argv like `['npm', 'test']` simply never matches
+ * `grep`/`diff` as its first token, so it is never misclassified ambiguous).
+ *
+ * DIALECT-PRESERVATION INVARIANT (#362): `commandText` below MUST be `trusted.argv[2]`'s value,
+ * verbatim — never re-derived, re-joined, or re-quoted from `trusted.argv`. The recorded
+ * command's exact dialect/flags (e.g. `grep -E '(foo|bar)'`'s ERE alternation) are part of the
+ * evidence ref text; re-joining `argv` with spaces (or any other reconstruction) would silently
+ * reintroduce a BRE/ERE dialect mismatch — the exact bug this invariant exists to prevent. This
+ * mirrors the equivalent invariant on `resolveTrustedCommand`'s `acceptance` branch below (search
+ * DIALECT-PRESERVATION INVARIANT there, including its accepted whitespace-collapse boundary
+ * note) — the same recorded string must survive unmodified from `acceptanceCommandFor`'s return
+ * value through to this spawnSync call.
+ *
+ * @param {{argv: string[], cwd: string}} trusted
+ * @returns {{ran: boolean, exitCode?: number, classification?: 'pass'|'fail'|'ambiguous', error?: string, timedOut?: boolean}}
+ */
 function runBackstop(trusted) {
   const result = spawnSync(trusted.argv[0], trusted.argv.slice(1), {
     cwd: trusted.cwd,
@@ -1055,7 +1175,19 @@ function runBackstop(trusted) {
   });
   if (result.error) return { ran: false, error: result.error.code || result.error.message };
   if (result.signal) return { ran: false, error: `killed (${result.signal})`, timedOut: result.signal === 'SIGKILL' || result.signal === 'SIGTERM' };
-  return { ran: true, passed: result.status === 0, exitCode: result.status };
+  const exitCode = result.status;
+  // The `['bash', '-lc', <command-text>]` shape resolveTrustedCommand's acceptance/
+  // model-command sources produce carries the ORIGINAL recorded command text verbatim in
+  // argv[2] — pass THAT (not a re-joined/re-quoted `argv.join(' ')`, which would lose the
+  // shell-quoting isAmbiguousAbsenceCommand's `bash -lc '...'` unwrap regex requires) to the
+  // heuristic. A `declared`-manifest-target argv (e.g. `['npm', 'test']`) has no such wrapper;
+  // joining it is fine since its first token is never `grep`/`diff` anyway.
+  const commandText = (trusted.argv.length === 3 && trusted.argv[0] === 'bash' && trusted.argv[1] === '-lc')
+    ? trusted.argv[2]
+    : trusted.argv.join(' ');
+  const ambiguous = exitCode === 1 && isAmbiguousAbsenceCommand(commandText);
+  const classification = ambiguous ? 'ambiguous' : (exitCode === 0 ? 'pass' : 'fail');
+  return { ran: true, exitCode, classification };
 }
 
 /**
@@ -1081,6 +1213,8 @@ function captureCrossReference(root, artifactDir, activeFlowStep) {
   const base = relative(root, artifactDir);
   const backstopMode = resolveBackstopMode();
   const warnings = [];
+  const captureState = readJsonFile(path.join(artifactDir, 'state.json'));
+  const terminalDelivered = isTerminalDeliveredState(captureState);
 
   // AC3 fail-closed: detect a missing command log in a post-execution session.
   // When state.json confirms the session is past the planning phase (commands should
@@ -1094,7 +1228,6 @@ function captureCrossReference(root, artifactDir, activeFlowStep) {
   {
     const logFileMissing = !fs.existsSync(path.join(artifactDir, 'command-log.jsonl'));
     if (logFileMissing) {
-      const captureState = readJsonFile(path.join(artifactDir, 'state.json'));
       if (captureState) {
         const capturePhase = normalizedStatus(captureState.phase || '');
         const captureStatus = normalizedStatus(captureState.status || '');
@@ -1194,6 +1327,23 @@ function captureCrossReference(root, artifactDir, activeFlowStep) {
       if (logged.failed) {
         const exit = Number.isInteger(logged.exitCode) ? ` (exitCode:${logged.exitCode})` : '';
         warnings.push(`${base} evidence check ${id}: capture log CONTRADICTS claimed pass — command "${safeOneLine(cmd, 120)}" was recorded as FAIL${exit}. This is a caught false-completion.`);
+      } else if (logged.ambiguous && logged.absenceAmbiguous) {
+        // #362: a bare grep/diff logged exit 1 — ambiguous (zero matches/no diff), not a
+        // caught false-completion. Distinct warning class, never silently dropped, never a
+        // hard block. UNCHANGED (byte-identical) — iteration-2 (re-plan) finding #3 Decision A
+        // keeps this absence-ambiguous branch verbatim; only the sibling no-signal branch below
+        // is new.
+        const exit = Number.isInteger(logged.exitCode) ? ` (exitCode:${logged.exitCode})` : '';
+        warnings.push(`${base} evidence check ${id}: capture log shows command "${safeOneLine(cmd, 120)}" exited 1${exit} — for bare grep/diff this may mean zero matches/no differences (PASS for an absence check) or an unintended miss (FAIL for a presence check); NOT_VERIFIED (ambiguous): ${AMBIGUOUS_REMEDIATION} to remove the ambiguity.`);
+      } else if (logged.ambiguous) {
+        // Iteration-2 (re-plan) finding #3 (HIGH), Decision A: generic no-signal-ambiguous — the
+        // rule-3 default (`observedResult:'ambiguous'`, no exit code recoverable, e.g. an
+        // unreadable/missing codex host banner). This is NOT the #362 grep/diff carve-out (no
+        // `absenceAmbiguous`), so the message is grep/diff-FREE and accurate for any command.
+        // Deliberately does NOT contain `NOT_VERIFIED (ambiguous)`, `caught false-completion`, or
+        // `status:` so it MISSES HARD_BLOCK (warn-only on a terminal/pre-execution stop) while
+        // `evidence check` / `NOT_VERIFIED —` still match FULL_BLOCK (blocks a non-terminal stop).
+        warnings.push(`${base} evidence check ${id}: claimed pass but NOT_VERIFIED — command "${safeOneLine(cmd, 120)}" was captured with no deterministic pass/fail signal (no exit code observed on this host); a pass requires positive evidence. Re-run it to produce a definitive exit code, or record it as not_verified/accepted_gap.`);
       } else if (hasLaunderingOperator(cmd)) {
         // Fix D: exit-code laundering. The captured exit-0 is not trustworthy — the command
         // baked in '|| true' / '|| :' / '; true' / '; exit 0' / '| true' to mask the real result.
@@ -1219,17 +1369,30 @@ function captureCrossReference(root, artifactDir, activeFlowStep) {
       warnings.push(`${base} evidence check ${id}: claimed pass but NOT_VERIFIED — command "${safeOneLine(cmd, 120)}" was never captured and no trusted command (acceptance criterion / declared manifest target) resolves to re-run it. Set FLOW_AGENTS_GOAL_FIT_RECHECK=true to opt into re-running the model's free-form command.`);
       continue;
     }
+    if (terminalDelivered && trusted.source === 'model-command (FLOW_AGENTS_GOAL_FIT_RECHECK)') {
+      // Terminal delivered/done sessions have finalized evidence. Do not turn
+      // model-asserted command text into a new RECHECK false-completion. Captured
+      // execution evidence and CI/L2 checks remain the anchors for terminal tasks.
+      warnings.push(`${base} evidence check ${id}: malformed-evidence — terminal delivered/done session recorded model-command text asserted by FLOW_AGENTS_GOAL_FIT_RECHECK ("${safeOneLine(cmd, 120)}"); it was NOT re-run on a terminal session. Captured-execution evidence and CI/L2 checks remain the anchors.`);
+      continue;
+    }
     const outcome = runBackstop(trusted);
     if (!outcome.ran) {
       warnings.push(`${base} evidence check ${id}: claimed pass but NOT_VERIFIED — trusted backstop (${trusted.source}) could not run (${safeOneLine(outcome.error, 80)}).`);
       continue;
     }
-    if (!outcome.passed) {
+    if (outcome.classification === 'ambiguous') {
+      // #362: bare grep/diff backstop re-run exited 1 — ambiguous, not a caught
+      // false-completion. Never silently PASS (a presence check recorded without
+      // negation could genuinely be a miss) and never silently dropped.
+      const note = `${base} evidence check ${id}: trusted backstop (${trusted.source}) re-run of "${trusted.argv.join(' ')}" exited 1 — for grep/diff this may mean zero matches/no differences (PASS for an absence check) or an unintended miss (FAIL for a presence check); NOT_VERIFIED (ambiguous): ${AMBIGUOUS_REMEDIATION} to remove the ambiguity.`;
+      warnings.push(note);
+    } else if (outcome.classification === 'fail') {
       const note = `${base} evidence check ${id}: trusted backstop (${trusted.source}) re-run of "${trusted.argv.join(' ')}" FAILED with exit ${outcome.exitCode}, contradicting the claimed pass. This is a caught false-completion.`;
       if (backstopMode === 'off') warnings.push(`${note} [backstop in warn mode — not blocking]`);
       else warnings.push(note);
     }
-    // backstop passed → claim deterministically confirmed by re-run, no warning.
+    // backstop classification 'pass' → claim deterministically confirmed by re-run, no warning.
   }
 
   return warnings;
@@ -1289,7 +1452,18 @@ function capturedFailReconciliation(root, artifactDir, taskStatus) {
     if (!info.failed && hasLaunderingOperator(cmd)) launderedPass.set(cmd, info);
   }
 
-  if (latestFails.size === 0 && launderedPass.size === 0) return []; // Nothing to flag
+  // Iteration-2 fix item 4 (HIGH, ambiguity-must-not-slip-terminal-stops): a THIRD bucket —
+  // commands whose LATEST capture is `ambiguous` (a bare, non-self-asserting grep/diff exit 1;
+  // #362) — collected separately from `latestFails`, never merged into it. An ambiguous capture
+  // is NOT a caught false-completion (it may genuinely be the author's intended pass for an
+  // absence check) — it gets its own distinct re-record-self-asserting message below, never the
+  // "caught false-completion" accusation `latestFails`/`launderedPass` use.
+  const latestAmbiguous = new Map(); // cmd -> {failed:false, ambiguous:true, exitCode}
+  for (const [cmd, info] of latestLog) {
+    if (!info.failed && info.ambiguous) latestAmbiguous.set(cmd, info);
+  }
+
+  if (latestFails.size === 0 && launderedPass.size === 0 && latestAmbiguous.size === 0) return []; // Nothing to flag
 
   const base = relative(root, artifactDir);
   const warnings = [];
@@ -1305,8 +1479,8 @@ function capturedFailReconciliation(root, artifactDir, taskStatus) {
     if (c && c.id) claimById.set(c.id, c);
   }
 
-  // commandsToCheck: FAIL-latest commands + laundered-pass commands
-  const commandsToCheck = new Set([...latestFails.keys(), ...launderedPass.keys()]);
+  // commandsToCheck: FAIL-latest commands + laundered-pass commands + ambiguous-latest commands
+  const commandsToCheck = new Set([...latestFails.keys(), ...launderedPass.keys(), ...latestAmbiguous.keys()]);
 
   // For each relevant command, track what claims say about it.
   // cmdAcc: cmd → {passClaims: [...], ackClaims: []}
@@ -1377,6 +1551,43 @@ function capturedFailReconciliation(root, artifactDir, taskStatus) {
     }
   }
 
+  // Iteration-2 fix item 4 (HIGH): THIRD bucket — commands whose latest capture is `ambiguous`
+  // AND some claim asserts pass for them. This is deliberately gated on `acc.passClaims.length >
+  // 0` (mirroring Case A / Fix D above) — an ambiguous capture with NO pass-claim at all is not
+  // reconciled here (nothing was asserted against it to reconcile), matching the existing
+  // no-over-block guarantee for incidental runs. When a claim DOES assert pass for an ambiguous
+  // command, this is a DISTINCT re-record-self-asserting message — NEVER the "caught
+  // false-completion" accusation Case A/Fix D use, since a bare grep/diff exit 1 may genuinely be
+  // the author's intended pass (zero matches/no differences for an absence check). This bucket
+  // still BLOCKS a terminal stop (via HARD_BLOCK's dedicated ambiguous pattern below) because the
+  // claim is asserting something the capture cannot actually confirm — recording is not the same
+  // as verified completion.
+  for (const [cmd, ambiguousInfo] of latestAmbiguous) {
+    const exit = Number.isInteger(ambiguousInfo.exitCode) ? ambiguousInfo.exitCode : null;
+    const exitStr = exit !== null ? ` (exit ${exit})` : '';
+    const acc = cmdAcc.get(cmd);
+    if (acc && acc.passClaims.length > 0) {
+      const claim = acc.passClaims[0];
+      if (ambiguousInfo.absenceAmbiguous) {
+        // #362 absence-ambiguous — UNCHANGED (byte-identical) message + HARD_BLOCK marker.
+        warnings.push(
+          `${base} captured command '${safeOneLine(cmd, 120)}' last ran AMBIGUOUS${exitStr} ` +
+          `(bare grep/diff exit 1 — zero matches/no differences) and claim ${safeOneLine(claim.subjectId || claim.id, 80)} ` +
+          `(${safeOneLine(claim.claimType, 48)}) asserts pass — NOT_VERIFIED (ambiguous): ${AMBIGUOUS_REMEDIATION} and re-run it, then re-record the claim.`
+        );
+      } else {
+        // Iteration-2 (re-plan) finding #3 Decision A: generic no-signal-ambiguous (no exit code
+        // ever recoverable) — grep/diff-FREE wording, misses HARD_BLOCK, still matches FULL_BLOCK
+        // via `NOT_VERIFIED —` so a non-terminal stop still blocks.
+        warnings.push(
+          `${base} captured command '${safeOneLine(cmd, 120)}' last ran with no deterministic pass/fail signal${exitStr} ` +
+          `(no exit code observed on this host) and claim ${safeOneLine(claim.subjectId || claim.id, 80)} ` +
+          `(${safeOneLine(claim.claimType, 48)}) asserts pass — NOT_VERIFIED — re-run it to produce a definitive exit code, then re-record the claim.`
+        );
+      }
+    }
+  }
+
   return warnings;
 }
 
@@ -1639,16 +1850,30 @@ function missingBundleOrStateSignal(artifactDir, activeFlowStep) {
 //
 // HARD_BLOCK: always blocks, even for pre-execution and terminal tasks.
 //   Fires on genuine false-completion signals (a claimed pass the capture log or
-//   evidence.json contradicts), integrity failures, and gate misconfiguration.
+//   evidence.json contradicts), integrity failures, gate misconfiguration, and — iteration-2 fix
+//   item 4 (HIGH) — the unified ambiguous-with-a-pass-claim signal (`NOT_VERIFIED (ambiguous)`,
+//   built from the shared AMBIGUOUS_REMEDIATION const). ALL THREE emission sites — the capture-log
+//   shortcut in captureCrossReference, the live re-run in runBackstop, and the THIRD bucket in
+//   capturedFailReconciliation — emit this same marker, and it is DELIBERATELY distinct text from
+//   `caught false-completion` (never the false-completion accusation for a bare grep/diff exit 1,
+//   which may genuinely be the author's intended pass). All three DELIBERATELY match HARD_BLOCK,
+//   so an ambiguous claimed-pass BLOCKS a terminal/pre-execution stop in every config
+//   (evidence.json-only, never-captured, and captured+bundle) — a claim asserting pass for a
+//   command whose exit code cannot actually confirm that is not a verified completion either. Do
+//   NOT revert any of the three sites back to plain `NOT_VERIFIED —` text: that would desync them
+//   from HARD_BLOCK and reopen the terminal-stop ambiguous bypass. (The genuinely non-ambiguous
+//   `NOT_VERIFIED —` cases — never-captured, backstop-disabled, no-trust-bundle, etc. — are a
+//   separate, unrelated class: they stay warn-only for a terminal/pre-execution stop and only
+//   block a non-terminal stop via FULL_BLOCK's broader `NOT_VERIFIED —` pattern, unchanged.)
 //
 // FULL_BLOCK: fires for execution-onward tasks (post-planning, non-terminal).
 //   Includes all HARD_BLOCK patterns plus completeness/hygiene and not-done state.
 //
 // Both are used in analyze() for blocking decisions AND in run() for the AC2
 // MAX_BLOCKS hard-block guard (preventing auto-release of hard blocks).
-const HARD_BLOCK = /contradicts evidence\.json|caught false-completion|evidence verdict:|evidence check .+ status:|critique status|critique open|required sidecar is missing|command-log integrity check FAILED|gate misconfiguration:|exit-code-laundered/;
+const HARD_BLOCK = /contradicts evidence\.json|caught false-completion|evidence verdict:|evidence check .+ status:|critique status|critique open|required sidecar is missing|command-log integrity check FAILED|gate misconfiguration:|exit-code-laundered|NOT_VERIFIED \(ambiguous\)/;
 // FULL_BLOCK adds: workflow-state hygiene, surface-unavailable fail-closed, missing log.
-const FULL_BLOCK = /status:|Definition Of Done|Goal Fit|sidecar validation:|contradicts evidence\.json|workflow state|evidence verdict|evidence check|NOT_VERIFIED gap|critique status|critique open|next action|caught false-completion|NOT_VERIFIED —|command-log integrity check FAILED|gate misconfiguration:|surface unavailable —|expected capture log is missing|exit-code-laundered|malformed-evidence/;
+const FULL_BLOCK = /status:|Definition Of Done|Goal Fit|sidecar validation:|contradicts evidence\.json|workflow state|evidence verdict|evidence check|NOT_VERIFIED gap|critique status|critique open|next action|caught false-completion|NOT_VERIFIED —|command-log integrity check FAILED|gate misconfiguration:|surface unavailable —|expected capture log is missing|exit-code-laundered|malformed-evidence|NOT_VERIFIED \(ambiguous\)/;
 
 async function analyze(root, now = Date.now()) {
   const flowAgentsDirs = flowAgentsArtifactRootsForRead(root);
@@ -1740,7 +1965,8 @@ async function analyze(root, now = Date.now()) {
   // Use module-scope HARD_BLOCK / FULL_BLOCK (defined above analyze()).
   // pre-execution/terminal tasks: only HARD_BLOCK signals cause a block.
   // execution-onward tasks: FULL_BLOCK signals cause a block.
-  const blockRe = (preExecution || terminal) ? HARD_BLOCK : FULL_BLOCK;
+  const activeFlowRun = gateState && gateState.flow_run && normalizedStatus(gateState.flow_run.status) === 'active';
+  const blockRe = ((preExecution && !activeFlowRun) || terminal) ? HARD_BLOCK : FULL_BLOCK;
   const blocking = warnings.some(w => {
     // Capture cross-reference warn-mode notes never block (operator opted out).
     if (/\[backstop in warn mode — not blocking\]/.test(w)) return false;
@@ -1994,6 +2220,10 @@ function releaseOnNonTerminalStop(root, artifactDir) {
 
     const state = readJsonFile(path.join(artifactDir, 'state.json'));
     if (!state) return; // AC5: no state.json — nothing to gate a release decision on.
+    if (state.flow_run && normalizedStatus(state.flow_run.status) === 'active') {
+      process.stderr.write(`[Hook] Goal Fit: stop-hook release skipped for active Flow run "${safeOneLine(state.flow_run.run_id || state.task_slug || 'unknown', 80)}"; continuation remains governed by Flow state.\n`);
+      return;
+    }
 
     const sidecar = loadWorkflowSidecarBuilt();
     if (!sidecar) {