@ai-dev-methodologies/rlp-desk 0.14.6 → 0.15.1

package/src/node/runner/campaign-main-loop.mjs

@@ -10,7 +10,12 @@ import { shellQuote } from '../util/shell-quote.mjs';
 import { ONE_MILLION_BETA, wantsOneMillionContext } from '../constants.mjs';
 import { initCampaign } from '../init/campaign-initializer.mjs';
 import { LEGACY_DESK_REL, resolveDeskRoot } from '../util/desk-root.mjs';
-import { writeSentinelExclusive } from '../shared/fs.mjs';
+import {
+  lockSentinelFile as defaultLockSentinelFile,
+  stampAckField as defaultStampAckField,
+  unlockSentinelFile,
+  writeSentinelExclusive,
+} from '../shared/fs.mjs';
 import {
   TimeoutError,
   WorkerExitedError,
@@ -29,7 +34,10 @@ import {
 } from '../reporting/campaign-reporting.mjs';
 import {
   createPane as defaultCreatePane,
+  killPaneProcess as defaultKillPaneProcess,
   sendKeys as defaultSendKeys,
+  sendRawKey as defaultSendRawKey,
+  waitForProcessExit as defaultWaitForProcessExit,
 } from '../tmux/pane-manager.mjs';
 
 const execFileAsync = promisify(execFile);
@@ -128,6 +136,39 @@ function buildPaths(rootDir, slug, env = process.env) {
 };
 }
 
+// Bug #8 PR-B: default git working-tree probe. Inline (~20 LoC) — no new
+// module per Architect/Critic codex iter 6 consensus. Tests inject a stub via
+// run() option `checkWorkingTree`.
+//   - returns { ok: false, error } when git rev-parse fails (not a repo, etc).
+//   - returns { ok: true, dirty: bool, dirtyFiles[] } otherwise.
+//   - dirtyFiles are raw `git status --porcelain` lines (caller truncates).
+async function _defaultCheckWorkingTree(rootDir) {
+  try {
+    const { stdout: top } = await execFileAsync('git', ['-C', rootDir, 'rev-parse', '--show-toplevel']);
+    const trimmed = top.trim();
+    // macOS `/var` resolves to `/private/var`; symlinks elsewhere too. Compare
+    // canonical realpaths via fs.realpath so the comparison does not fire on
+    // symlink-equivalent paths.
+    const [topCanon, rootCanon] = await Promise.all([
+      fs.realpath(trimmed).catch(() => trimmed),
+      fs.realpath(rootDir).catch(() => rootDir),
+    ]);
+    if (topCanon !== rootCanon) {
+      // Worker is in a sub-tree, not the campaign root. Refuse to classify.
+      return { ok: false, error: `git toplevel ${trimmed} != ${rootDir}` };
+    }
+  } catch (err) {
+    return { ok: false, error: err?.message ?? String(err) };
+  }
+  try {
+    const { stdout } = await execFileAsync('git', ['-C', rootDir, 'status', '--porcelain']);
+    const lines = stdout.split('\n').filter(Boolean);
+    return { ok: true, dirty: lines.length > 0, dirtyFiles: lines };
+  } catch (err) {
+    return { ok: false, error: err?.message ?? String(err) };
+  }
+}
+
 async function exists(targetPath) {
   try {
     await fs.access(targetPath);
@@ -347,6 +388,110 @@ async function readCurrentState(paths, slug, options) {
   };
 }
 
+// PR-A (Bug #10): validate operator-written recovery artifacts. When the
+// operator hand-rolls a `phase=verify` recovery (jq-patches status.json,
+// writes iter-signal.json + done-claim.json by hand, deletes the blocked
+// sentinel), the leader must NOT silently overwrite that work on relaunch.
+// All five checks must pass for the leader to honor the recovery.
+//
+// Returns { ok: boolean, reason: string }. On any failure the caller falls
+// through to the default behavior (worker dispatch) — defensive by design.
+async function _validateOperatorRecoveryArtifacts({ paths, state }) {
+  // 1. iter-signal.json + done-claim.json must both exist and parse.
+  let signal;
+  let doneClaim;
+  try {
+    signal = await readJsonIfExists(paths.signalFile);
+  } catch (err) {
+    return { ok: false, reason: `iter-signal.json parse error: ${err?.message ?? err}` };
+  }
+  if (!signal) return { ok: false, reason: 'iter-signal.json missing' };
+
+  try {
+    doneClaim = await readJsonIfExists(paths.doneClaimFile);
+  } catch (err) {
+    return { ok: false, reason: `done-claim.json parse error: ${err?.message ?? err}` };
+  }
+  if (!doneClaim) return { ok: false, reason: 'done-claim.json missing' };
+
+  // 2. us_id must match status.current_us in BOTH artifacts.
+  if (signal.us_id !== state.current_us) {
+    return {
+      ok: false,
+      reason: `iter-signal.us_id (${signal.us_id}) != status.current_us (${state.current_us})`,
+    };
+  }
+  if (doneClaim.us_id !== state.current_us) {
+    return {
+      ok: false,
+      reason: `done-claim.us_id (${doneClaim.us_id}) != status.current_us (${state.current_us})`,
+    };
+  }
+
+  // 3. iteration must match status.iteration in BOTH artifacts.
+  if (signal.iteration !== state.iteration) {
+    return {
+      ok: false,
+      reason: `iter-signal.iteration (${signal.iteration}) != status.iteration (${state.iteration})`,
+    };
+  }
+  if (doneClaim.iteration !== state.iteration) {
+    return {
+      ok: false,
+      reason: `done-claim.iteration (${doneClaim.iteration}) != status.iteration (${state.iteration})`,
+    };
+  }
+
+  // 4. iter_signal_quality must be 'specific' (not generic / vague).
+  if (signal.iter_signal_quality !== 'specific') {
+    return {
+      ok: false,
+      reason: `iter-signal.iter_signal_quality (${signal.iter_signal_quality}) != 'specific'`,
+    };
+  }
+
+  // 5. Both artifact mtimes must be NEWER than the most recent
+  //    iter-NNN.worker-prompt.md mtime — guards against operator running
+  //    `phase=verify` against stale artifacts from a much earlier iteration.
+  const promptFile = path.join(
+    paths.campaignLogDir,
+    `iter-${String(state.iteration).padStart(3, '0')}.worker-prompt.md`,
+  );
+  let promptMtime = 0;
+  try {
+    const promptStat = await fs.stat(promptFile);
+    promptMtime = promptStat.mtimeMs;
+  } catch {
+    // No worker-prompt.md for this iteration → check vacuously passes
+    // (operator is recovering from a state that never even dispatched yet).
+    promptMtime = 0;
+  }
+  if (promptMtime > 0) {
+    let signalMtime = 0;
+    let doneClaimMtime = 0;
+    try {
+      signalMtime = (await fs.stat(paths.signalFile)).mtimeMs;
+      doneClaimMtime = (await fs.stat(paths.doneClaimFile)).mtimeMs;
+    } catch (err) {
+      return { ok: false, reason: `mtime stat failed: ${err?.message ?? err}` };
+    }
+    if (signalMtime <= promptMtime) {
+      return {
+        ok: false,
+        reason: `iter-signal.json mtime (${signalMtime}) is not strictly newer than worker-prompt mtime (${promptMtime})`,
+      };
+    }
+    if (doneClaimMtime <= promptMtime) {
+      return {
+        ok: false,
+        reason: `done-claim.json mtime (${doneClaimMtime}) is not strictly newer than worker-prompt mtime (${promptMtime})`,
+      };
+    }
+  }
+
+  return { ok: true, reason: 'all five checks passed' };
+}
+
 async function appendIterationAnalytics(paths, state, usId, verdict, options) {
   await appendCampaignAnalytics(paths.analyticsFile, {
     iter: state.iteration,
@@ -534,6 +679,12 @@ export const BLOCK_TAGS = Object.freeze({
   MALFORMED_ARTIFACT: 'malformed_artifact',
   // Backstop (run() try/finally)
   LEADER_EXITED_WITHOUT_TERMINAL_STATE: 'leader_exited_without_terminal_state',
+  // Bug #8 (Plan v6 PR-B): refuse to synthesize verify signal when codex
+  // worker exited without committing. Three new tags route through
+  // _handlePollFailure with reasonOverride/categoryOverride.
+  CODEX_EXIT_NO_DONE_CLAIM: 'codex_exit_no_done_claim',
+  GIT_STATE_UNVERIFIABLE: 'git_state_unverifiable',
+  WORKER_INCOMPLETE_UNCOMMITTED: 'worker_incomplete_uncommitted',
 });
 
 // P1-D Failure Taxonomy classifier. governance §1f locks the reason_category
@@ -619,6 +770,32 @@ function _classifyBlock(source, { verdict, state, slug } = {}) {
       action = 'investigate_leader_logs';
       failureCategory = 'leader_exited_without_terminal_state';
       break;
+    // Bug #8 PR-B — codex worker exited but did not write done-claim. Refuse
+    // to synthesize a verify signal; surface as infra_failure so wrapper does
+    // not retry blindly.
+    case BLOCK_TAGS.CODEX_EXIT_NO_DONE_CLAIM:
+      category = 'infra_failure';
+      recoverable = false;
+      action = 'investigate_pane_logs';
+      failureCategory = 'codex_exit_no_done_claim';
+      break;
+    // Bug #8 PR-B — git status could not be resolved (not a repo, git binary
+    // missing, etc). Without git we cannot prove the working tree is clean,
+    // so refuse to synthesize.
+    case BLOCK_TAGS.GIT_STATE_UNVERIFIABLE:
+      category = 'infra_failure';
+      recoverable = false;
+      action = 'investigate_git_state';
+      failureCategory = 'git_state_unverifiable';
+      break;
+    // Bug #8 PR-B — worker said it was done (done-claim present) but the tree
+    // is dirty. Recoverable: next iteration's worker can finish committing.
+    case BLOCK_TAGS.WORKER_INCOMPLETE_UNCOMMITTED:
+      category = 'metric_failure';
+      recoverable = true;
+      action = 'retry_after_fix';
+      failureCategory = 'worker_incomplete_uncommitted';
+      break;
     default:
       category = 'metric_failure';
       recoverable = false;
@@ -650,9 +827,41 @@ async function _handlePollFailure(error, ctx) {
     options,
     role, // 'worker' | 'verifier' | 'final_verifier' | 'flywheel' | 'guard'
     usIdOverride,
+    // Bug #8 PR-B: when the caller has already classified the failure (e.g.
+    // codex done-claim/git gate), forward an explicit BLOCK_TAGS value as
+    // categoryOverride and a reason string. Named `categoryOverride` per
+    // Plan v6 PRD (it overrides the tag→reason_category mapping). Existing 5
+    // callers omit both and the legacy error→tag mapping below runs unchanged.
+    categoryOverride,
+    reasonOverride,
   } = ctx;
   const usId = usIdOverride ?? state.current_us;
 
+  if (categoryOverride) {
+    state.phase = 'blocked';
+    const classification = _classifyBlock(categoryOverride, { state, slug });
+    const reasonText = reasonOverride ?? `${role} blocked: ${categoryOverride}`;
+    await writeSentinel(paths.blockedSentinel, 'blocked', usId, reasonText, classification, paths);
+    await writeStatus(paths, state, options.onStatusChange, options.now);
+    await generateCampaignReport({
+      slug,
+      reportFile: paths.reportFile,
+      prdFile: paths.prdFile,
+      statusFile: paths.statusFile,
+      analyticsFile: paths.analyticsFile,
+      now: resolveNow(options.now),
+      blockedReason: reasonText,
+      blockedCategory: classification.reason_category,
+    });
+    return {
+      status: 'blocked',
+      usId,
+      reason: reasonText,
+      category: classification.reason_category,
+      statusFile: paths.statusFile,
+    };
+  }
+
   let tag;
   let reason;
   if (error instanceof WorkerExitedError) {
@@ -872,6 +1081,10 @@ async function runFinalSequentialVerify({
   pollForSignal,
   runIntegrationCheck,
   iterTimeoutMs,
+  // Bug #7 Fix-Q/R: optional reaper. Passed from _runCampaignBody so each
+  // per-US verdict kills the verifier TUI before the next per-US dispatch
+  // reuses the same pane. No-op when undefined (legacy/test callers).
+  reapProducer,
 }) {
   const verifierModel = state.final_verifier_model;
 
@@ -893,6 +1106,10 @@ async function runFinalSequentialVerify({
       timeoutMs: iterTimeoutMs,
     });
 
+    if (typeof reapProducer === 'function') {
+      await reapProducer(verifierPaneId, paths.verdictFile);
+    }
+
     if (verdict.verdict !== 'pass') {
       return {
         status: 'continue',
@@ -1078,6 +1295,46 @@ async function _runCampaignBody(slug, options, paths, rootDir) {
   const createPane = options.createPane ?? defaultCreatePane;
   const createSession = options.createSession ?? defaultCreateSession;
   const pollForSignal = options.pollForSignal ?? defaultPollForSignal;
+  // Bug #7 Fix-Q/R: post-sentinel reaper. Producer (claude/codex TUI) must be
+  // interrupted the moment leader has consumed the sentinel; otherwise the
+  // pane lingers in idle prompt and self-reviews for ~2min. lockSentinel
+  // freezes the file mtime as defense-in-depth. All four are injectable so
+  // existing tests with fake sendKeys keep working (us006 createTmuxFakes).
+  const sendRawKey = options.sendRawKey ?? defaultSendRawKey;
+  const waitForProcessExit = options.waitForProcessExit ?? defaultWaitForProcessExit;
+  const killPaneProcess = options.killPaneProcess ?? defaultKillPaneProcess;
+  const lockSentinel = options.lockSentinelFile ?? defaultLockSentinelFile;
+  const stampAckField = options.stampAckField ?? defaultStampAckField;
+  const reapProducer = async (paneId, sentinelFile) => {
+    if (!paneId) return;
+    await killPaneProcess(paneId, {
+      sendRawKey,
+      waitForExit: waitForProcessExit,
+      log: (msg) => console.error(msg),
+    });
+    // PR-0b-narrow AC-H1: after killPaneProcess, wait for the producing
+    // process to actually exit before continuing. waitForProcessExit returns
+    // when pane_current_command resolves to a shell (zsh/bash/sh). Wrapped
+    // in try/catch — failure here is non-fatal but emits a log entry.
+    try {
+      await waitForProcessExit(paneId, { timeoutMs: 5000 });
+    } catch (err) {
+      console.error(`[handshake] waitForProcessExit failed on ${paneId} (${err?.message ?? err}); continuing`);
+    }
+    if (sentinelFile) {
+      await lockSentinel(sentinelFile, { log: (msg) => console.error(msg) });
+      // PR-0b-narrow AC-H2: stamp the leader_ack audit field. Best-effort,
+      // does not block subsequent dispatch.
+      await stampAckField(sentinelFile, {
+        acked_by: 'leader',
+        acked_at: new Date(resolveNow(options.now)).toISOString(),
+        ack_pane_state: 'shell',
+      }, { log: (msg) => console.error(msg) });
+    }
+  };
+  // Bug #8 PR-B: working-tree probe injected (or default execFile git).
+  // Returns { ok: boolean, dirty?: boolean, dirtyFiles?: string[], error?: string }.
+  const checkWorkingTree = options.checkWorkingTree ?? _defaultCheckWorkingTree;
   const runIntegrationCheck = options.runIntegrationCheck ?? (async () => ({ exitCode: 0, summary: 'integration skipped' }));
   const maxIterations = options.maxIterations ?? 100;
   // v5.7 §4.19: campaign-level pollForSignal timeout (Node leader fix).
@@ -1135,6 +1392,28 @@ async function _runCampaignBody(slug, options, paths, rootDir) {
 
   let fixContractPath = null;
 
+  // PR-A (Bug #10): operator-recovery hygiene. If the operator hand-rolled a
+  // `phase=verify` recovery (jq-patches status.json, writes manual artifacts,
+  // deletes the blocked sentinel), the leader MUST honor that work instead of
+  // resetting to phase=worker on relaunch. The validator runs five checks
+  // (see _validateOperatorRecoveryArtifacts); on full pass, _skipNextWorkerDispatch
+  // is set as a one-shot flag consumed at the worker dispatch call site below.
+  // On any failure the leader logs the reason and falls through to default
+  // behavior.
+  if (state.phase === 'verify' && state.iteration > 0) {
+    const validation = await _validateOperatorRecoveryArtifacts({ paths, state });
+    if (validation.ok) {
+      console.error(
+        `[recovery] Resuming verify phase — operator manual recovery detected (us=${state.current_us} iter=${state.iteration}): ${validation.reason}`,
+      );
+      state._skipNextWorkerDispatch = true;
+    } else {
+      console.error(
+        `[recovery] phase=verify ignored, falling through to worker dispatch: ${validation.reason}`,
+      );
+    }
+  }
+
   // P1-E Lane Enforcement: snapshot lane mtimes before each iteration,
   // compare at the top of the next iteration. Drift on read-only artifacts
   // (PRD, test-spec, context) emits a lane_violation_warning event + audit
@@ -1143,6 +1422,11 @@ async function _runCampaignBody(slug, options, paths, rootDir) {
   let _laneSnapshot = await _snapshotLaneMtimes(paths);
 
   while (state.iteration <= maxIterations) {
+    // Bug #7 Fix-R defensive unlock: a 0o444 sentinel left from the previous
+    // iteration must not block the next producer's atomic-rename write.
+    // Idempotent: missing-file calls are no-ops.
+    await unlockSentinelFile(paths.signalFile);
+    await unlockSentinelFile(paths.verdictFile);
     // Audit drift from the prior iteration before doing anything new.
     const _laneSnapshotAfter = await _snapshotLaneMtimes(paths);
     const _laneViolations = await _checkLaneViolations(paths, _laneSnapshot, _laneSnapshotAfter, state, options);
@@ -1191,6 +1475,7 @@ async function _runCampaignBody(slug, options, paths, rootDir) {
           pollForSignal,
           runIntegrationCheck,
           iterTimeoutMs,
+          reapProducer,
         });
       } catch (error) {
         // v5.7 §4.25 — uniform poll-failure handling for final verifier.
@@ -1282,12 +1567,17 @@ async function _runCampaignBody(slug, options, paths, rootDir) {
         });
       }
 
+      // Bug #7 Fix-Q/R: reap flywheel pane before consuming the signal.
+      await reapProducer(state.flywheel_pane_id ?? state.verifier_pane_id, paths.flywheelSignalFile);
+
       state.last_flywheel_decision = flywheelSignal.decision;
       // P0-A multi-mission orchestration: optionally captured from flywheel signal.
       // null when the flywheel did not suggest a next mission. Consumer wrappers
       // poll status.next_mission_candidate to chain missions without code edits.
       // See docs/multi-mission-orchestration.md.
       state.next_mission_candidate = flywheelSignal.next_mission_candidate ?? null;
+      // Bug #7 Fix-R cleanup: unlock before unlink so 0o444 doesn't block.
+      await unlockSentinelFile(paths.flywheelSignalFile);
       await fs.unlink(paths.flywheelSignalFile).catch(() => {});
 
       // Flywheel Guard (independent validation of flywheel decision)
@@ -1320,11 +1610,15 @@ async function _runCampaignBody(slug, options, paths, rootDir) {
           });
         }
 
+        // Bug #7 Fix-Q/R: reap guard pane before mutating state.
+        await reapProducer(guardPaneId, paths.flywheelGuardVerdictFile);
+
         if (!state.flywheel_guard_count[state.current_us]) {
           state.flywheel_guard_count[state.current_us] = 0;
         }
         state.flywheel_guard_count[state.current_us] += 1;
 
+        await unlockSentinelFile(paths.flywheelGuardVerdictFile);
         await fs.unlink(paths.flywheelGuardVerdictFile).catch(() => {});
 
         if (guardVerdict.verdict === 'inconclusive') {
@@ -1404,18 +1698,36 @@ async function _runCampaignBody(slug, options, paths, rootDir) {
       }
     }
 
-    state.phase = 'worker';
-    await writeStatus(paths, state, options.onStatusChange, options.now);
-    await dispatchWorker({
-      iteration: state.iteration,
-      paths,
-      slug,
-      usList,
-      state,
-      sendKeys,
-      workerPaneId: state.worker_pane_id,
-      fixContractPath,
-    });
+    // PR-A (Bug #10): one-shot guard. When the operator's `phase=verify`
+    // recovery was honored at campaign entry, skip both the phase reset and
+    // the worker dispatch — the operator already wrote a valid iter-signal.json
+    // and done-claim.json, so pollForSignal below will pick them up immediately
+    // and the loop continues into the verifier phase. The flag is cleared
+    // after consumption so subsequent iterations dispatch the worker normally.
+    if (state._skipNextWorkerDispatch) {
+      state._skipNextWorkerDispatch = false;
+      console.error(
+        `[recovery] Skipping worker dispatch for iter=${state.iteration} (honoring operator manual recovery)`,
+      );
+      // Persist phase=verify so a subsequent crash-and-relaunch sees the same
+      // contract. writeStatus is intentionally called BEFORE pollForSignal so
+      // the on-disk state matches what we are about to do.
+      state.phase = 'verify';
+      await writeStatus(paths, state, options.onStatusChange, options.now);
+    } else {
+      state.phase = 'worker';
+      await writeStatus(paths, state, options.onStatusChange, options.now);
+      await dispatchWorker({
+        iteration: state.iteration,
+        paths,
+        slug,
+        usList,
+        state,
+        sendKeys,
+        workerPaneId: state.worker_pane_id,
+        fixContractPath,
+      });
+    }
 
     let signal;
     try {
@@ -1432,8 +1744,43 @@ async function _runCampaignBody(slug, options, paths, rootDir) {
       });
     } catch (error) {
       if (error instanceof TimeoutError && parseModelFlag(state.worker_model).engine === 'codex') {
-        // v5.7 — codex CLI exits cleanly after writing signal; if pollForSignal
-        // timed out for codex, synthesize a verify signal so the loop continues.
+        // Bug #8 PR-B 4-way gate: refuse to synthesize verify signal when
+        // codex worker exited without committing real work.
+        //   1. done-claim absent          → BLOCKED infra_failure
+        //   2. git unverifiable           → BLOCKED infra_failure
+        //   3. done-claim + dirty tree    → BLOCKED metric_failure
+        //   4. done-claim + clean tree    → synthesize verify (legacy path)
+        const doneClaimExists = await exists(paths.doneClaimFile);
+        if (!doneClaimExists) {
+          return _handlePollFailure(error, {
+            paths, state, slug, options,
+            role: 'worker',
+            categoryOverride: BLOCK_TAGS.CODEX_EXIT_NO_DONE_CLAIM,
+            reasonOverride:
+              'codex worker exited (timeout) without writing done-claim; refusing to synthesize verify signal',
+          });
+        }
+        const tree = await checkWorkingTree(rootDir);
+        if (!tree.ok) {
+          return _handlePollFailure(error, {
+            paths, state, slug, options,
+            role: 'worker',
+            categoryOverride: BLOCK_TAGS.GIT_STATE_UNVERIFIABLE,
+            reasonOverride:
+              `git status unverifiable (${tree.error ?? 'unknown'}); refusing to synthesize verify signal`,
+          });
+        }
+        if (tree.dirty) {
+          const sample = (tree.dirtyFiles ?? []).slice(0, 5).join(', ');
+          return _handlePollFailure(error, {
+            paths, state, slug, options,
+            role: 'worker',
+            categoryOverride: BLOCK_TAGS.WORKER_INCOMPLETE_UNCOMMITTED,
+            reasonOverride:
+              `worker_incomplete_uncommitted: done-claim present but tree dirty (${sample || 'no file list'})`,
+          });
+        }
+        // Clean tree — preserve the legacy synthesize behaviour.
         signal = {
           iteration: state.iteration,
           status: 'verify',
@@ -1450,6 +1797,11 @@ async function _runCampaignBody(slug, options, paths, rootDir) {
       }
     }
 
+    // Bug #7 Fix-Q/R: reap the worker pane the instant we accept the signal so
+    // claude/codex cannot self-review and rewrite iter-signal.json. Runs even
+    // for the codex-fallback synthesized signal (no-op on a dead pane).
+    await reapProducer(state.worker_pane_id, paths.signalFile);
+
     // US-019 R7 P1-G: verify_partial malformed downgrade.
     // verify_partial requires verified_acs[] to be a non-empty array. Otherwise the verifier
     // has nothing to evaluate and we must treat the signal as broken contract → blocked.
@@ -1519,6 +1871,11 @@ async function _runCampaignBody(slug, options, paths, rootDir) {
       });
     }
 
+    // Bug #7 Fix-Q/R: reap verifier pane immediately after accepting the
+    // verdict — without this the codex/claude TUI keeps running for ~2min and
+    // can rewrite verify-verdict.json (mtime drift observed in 19th launch).
+    await reapProducer(state.verifier_pane_id, paths.verdictFile);
+
     if (verdict.verdict === 'pass') {
       state.consecutive_failures = 0;
       if (!state.verified_us.includes(usId)) {

package/src/node/shared/fs.mjs

@@ -59,3 +59,86 @@ export async function writeSentinelExclusive(targetPath, content) {
   }
   return { wrote: true };
 }
+
+// Bug #7 Fix-R: best-effort chmod 0o444 to freeze a sentinel file once the
+// leader has accepted it. Mirror of scripts/postinstall.js tryLockFile (L104).
+// Some filesystems silently ignore chmod (WSL1/NTFS, tmpfs); we log once and
+// continue. Q (process kill) is the primary defense; R is defense-in-depth.
+let _sentinelLockWarningEmitted = false;
+export async function lockSentinelFile(filePath, { log = (msg) => console.error(msg) } = {}) {
+  try {
+    await fs.chmod(filePath, 0o444);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      // File missing is not an error — sentinel may have been consumed and
+      // unlinked by a concurrent path. Idempotent no-op.
+      return;
+    }
+    if (!_sentinelLockWarningEmitted) {
+      log(`[bug7] chmod 0444 on ${filePath} failed (${err?.code ?? 'unknown'}); post-sentinel write-protection unavailable on this FS.`);
+      _sentinelLockWarningEmitted = true;
+    }
+  }
+}
+
+// Pair to lockSentinelFile. Called before fs.unlink in iter-cleanup paths so
+// subsequent atomic-rename writes never see EACCES on the destination mode.
+// Idempotent — missing file or already-writable is fine.
+export async function unlockSentinelFile(filePath) {
+  try {
+    await fs.chmod(filePath, 0o644);
+  } catch {
+    // best-effort; cleanup proceeds regardless.
+  }
+}
+
+// PR-0b-narrow (Plan v6) — stamp leader handshake ack onto an already-locked
+// sentinel. Best-effort, audit-only: the contract is "if we can write, do; if
+// not, swallow". Callers must NOT depend on the ack landing for hard ordering
+// semantics (use waitForProcessExit + the chmod 0o444 lock for that). The
+// resulting `content.leader_ack` is auxiliary metadata so post-mortem audits
+// can prove which Leader iteration consumed which sentinel.
+//
+// Sequence (mirrored in src/scripts/lib_ralph_desk.zsh::_stamp_ack_field):
+//   1. chmod 0o644 (so we can write — sentinel was locked by lockSentinelFile)
+//   2. JSON.parse
+//   3. merge ack as content.leader_ack
+//   4. atomic write
+//   5. chmod 0o444 (re-lock)
+//
+// All steps wrapped in try/catch; any failure is silently dropped. Failure
+// modes that we deliberately swallow:
+//   - File missing (sentinel was unlinked by a concurrent path).
+//   - Malformed JSON (race with a partial-write window — Bug #7 already gates
+//     this on the read side, but stampAckField may still observe it during
+//     transitional iterations).
+//   - chmod ENOTSUP / WSL1 / NTFS (recorded in Bug #7 fixes).
+export async function stampAckField(filePath, ack, { log = (msg) => console.error(msg) } = {}) {
+  try {
+    await fs.chmod(filePath, 0o644);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return; // sentinel gone — nothing to stamp
+    // chmod failure is non-fatal — try the write anyway in case the FS already allows it
+  }
+  let content;
+  try {
+    const raw = await fs.readFile(filePath, 'utf8');
+    content = JSON.parse(raw);
+  } catch (err) {
+    log(`[stamp-ack] read/parse failed for ${filePath} (${err?.code ?? err?.message ?? 'unknown'}); ack dropped (audit-only)`);
+    // Re-lock if possible — best-effort.
+    try { await fs.chmod(filePath, 0o444); } catch {}
+    return;
+  }
+  if (!content || typeof content !== 'object') {
+    try { await fs.chmod(filePath, 0o444); } catch {}
+    return;
+  }
+  content.leader_ack = ack;
+  try {
+    await fs.writeFile(filePath, `${JSON.stringify(content, null, 2)}\n`, 'utf8');
+  } catch (err) {
+    log(`[stamp-ack] write failed for ${filePath} (${err?.code ?? err?.message ?? 'unknown'}); ack dropped`);
+  }
+  try { await fs.chmod(filePath, 0o444); } catch {}
+}

package/src/node/tmux/pane-manager.mjs

@@ -52,6 +52,12 @@ export async function sendKeys(paneId, command) {
   await runTmux(['send-keys', '-t', paneId, 'Enter'], { paneId });
 }
 
+// Bug #7 Fix-Q: send a raw tmux key (e.g. C-c) without the `-l --` literal-text
+// flag. Distinct from sendKeys() so callers can interrupt a running TUI.
+export async function sendRawKey(paneId, key) {
+  await runTmux(['send-keys', '-t', paneId, key], { paneId });
+}
+
 export async function waitForProcessExit(
   paneId,
   { pollIntervalMs = 100, timeoutMs = 5000 } = {},
@@ -75,3 +81,36 @@ export async function waitForProcessExit(
     paneId,
   });
 }
+
+// Bug #7 Fix-Q: terminate the TUI process producing a sentinel file the moment
+// the leader has accepted it. Without this, claude/codex returns to its idle
+// prompt and continues self-review for 1-2 minutes, racing the next iteration.
+// Mirror of zsh pattern at run_ralph_desk.zsh:2384-2397, 375-376, 529-530.
+// Fail-open: pane may already be dead from prior teardown, or waitForExit may
+// time out — neither aborts the iteration.
+export async function killPaneProcess(
+  paneId,
+  {
+    sendRawKey: sendRawKeyImpl = sendRawKey,
+    waitForExit = waitForProcessExit,
+    gracePeriodMs = 800,
+    exitTimeoutMs = 5000,
+    log = () => {},
+  } = {},
+) {
+  const safeSend = async (key) => {
+    try {
+      await sendRawKeyImpl(paneId, key);
+    } catch (err) {
+      log(`[bug7] killPaneProcess sendRawKey ${key} failed for ${paneId}: ${err?.message ?? err}`);
+    }
+  };
+  await safeSend('C-c');
+  await new Promise((resolve) => setTimeout(resolve, gracePeriodMs));
+  await safeSend('C-c');
+  try {
+    await waitForExit(paneId, { timeoutMs: exitTimeoutMs });
+  } catch (err) {
+    log(`[bug7] killPaneProcess waitForExit failed for ${paneId}: ${err?.message ?? err}`);
+  }
+}