spec-and-loop 3.1.0 → 3.3.2

package/lib/mini-ralph/runner.js

@@ -28,6 +28,14 @@ const DEFAULTS = {
   maxIterations: 50,
   completionPromise: 'COMPLETE',
   taskPromise: 'READY_FOR_NEXT_TASK',
+  // Emitted by the agent when a task's `Stop and hand off if:` clause fires
+  // (i.e. external decision required: revert protected drift, file an
+  // out-of-scope refactor, escalate to a human reviewer, etc). The runner
+  // recognizes this as a *clean* exit distinct from `stalled` — it preserves
+  // the agent's diagnosis under `<ralphDir>/HANDOFF.md` and surfaces
+  // `exitReason='blocked_handoff'` so operators can tell "this task is
+  // genuinely blocked on me" apart from "the loop livelocked."
+  blockedHandoffPromise: 'BLOCKED_HANDOFF',
   tasksMode: false,
   noCommit: false,
   verbose: false,
@@ -48,11 +56,16 @@ const DEFAULTS = {
  * Determine whether an iteration made any forward progress.
  *
  * An iteration is considered productive if any of the following are true:
- *   - OpenCode emitted the task or completion promise
+ *   - OpenCode emitted the task, completion, or blocked-handoff promise
  *   - One or more tasks transitioned to "completed" during the iteration
  *   - At least one repo-tracked file was observed to have changed
  *   - The iteration failed outright (its signal is handled separately)
  *
+ * Note: a blocked-handoff iteration is intentionally excluded from "stalled"
+ * because the agent followed protocol — it surfaced a structured exit, the
+ * runner caught it, and the loop will break this iteration. We never want
+ * to penalize the agent (or the operator) for the canonical hand-off path.
+ *
  * @param {object} iterationSignals
  * @returns {boolean}
  */
@@ -61,6 +74,7 @@ function _iterationIsStalled(iterationSignals) {
   if (iterationSignals.iterationFailed) return false;
   if (iterationSignals.hasCompletion) return false;
   if (iterationSignals.hasTask) return false;
+  if (iterationSignals.hasBlockedHandoff) return false;
   if (iterationSignals.completedTasksCount > 0) return false;
   if (iterationSignals.filesChangedCount > 0) return false;
   return true;
@@ -118,6 +132,243 @@ function _errorText(err) {
   return String(err);
 }
 
+/**
+ * Extract the agent's blocker note from iteration output. The convention is:
+ * the line containing `<promise>BLOCKED_HANDOFF</promise>` MAY be preceded by
+ * a free-text rationale block (any number of lines up to a sentinel header
+ * `## Blocker` / `## Blocker Note` / `Blocker:`), and MAY include `## Why:` /
+ * `## Done-When-Will-Be:` / `## Suggested Next Step:` sections. We capture
+ * everything from the first sentinel header up to the promise tag, with a
+ * fallback to the last 40 non-blank lines preceding the tag if no sentinel
+ * is present, so the operator gets *something* useful even when the agent
+ * skips the structured format.
+ *
+ * @param {string} outputText  full iteration stdout
+ * @param {string} promiseName configured BLOCKED_HANDOFF promise name
+ * @returns {string} the extracted note (empty string if the tag is absent)
+ */
+function _extractBlockerNote(outputText, promiseName) {
+  if (!outputText || !promiseName) return '';
+  const tag = `<promise>${promiseName}</promise>`;
+  const lines = outputText.split(/\r?\n/);
+  let tagIdx = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim() === tag) {
+      tagIdx = i;
+      break;
+    }
+  }
+  if (tagIdx === -1) return '';
+
+  // Look backwards for a sentinel header.
+  const sentinel = /^\s*(##\s*Blocker(\s+Note)?|Blocker:)/i;
+  let startIdx = tagIdx;
+  for (let i = tagIdx - 1; i >= 0; i--) {
+    if (sentinel.test(lines[i])) {
+      startIdx = i;
+      break;
+    }
+  }
+
+  if (startIdx === tagIdx) {
+    // No sentinel — fall back to the last 40 non-blank lines before the tag.
+    const window = [];
+    for (let i = tagIdx - 1; i >= 0 && window.length < 40; i--) {
+      const l = lines[i];
+      if (l.trim()) window.unshift(l);
+    }
+    return window.join('\n').trim();
+  }
+
+  return lines.slice(startIdx, tagIdx).join('\n').trim();
+}
+
+/**
+ * Scan well-known locations for blocker / diagnostic artifacts the agent
+ * may have written during the most recent iteration, and return their
+ * content (truncated) so we can tee it into the next iteration's prompt.
+ *
+ * The motivation is the failure mode we observed in the wild: the agent
+ * writes `<change-baseline>/shared-chrome-invariant-report.txt` with a clear
+ * `STATUS=BLOCKED  REASON=...` diagnosis, then on the next iteration starts
+ * from a blank slate, re-derives the same diagnosis, and burns another full
+ * LLM cycle. By auto-detecting and surfacing the artifact, the agent gets
+ * its own prior diagnosis as input on the next turn, freeing it to either
+ * (a) act on it, or (b) emit BLOCKED_HANDOFF with a richer note.
+ *
+ * Probe paths (relative to ralphDir's parent — i.e. the change root):
+ *   - <ralphDir>/HANDOFF.md
+ *   - <ralphDir>/BLOCKED.md
+ *   - <ralphDir>/blocker.md  /  blocker-note.md
+ *   - <repoRoot>/.ralph/baselines/<change>/*report*.{txt,md}
+ *   - any file under <ralphDir> matching /(blocker|handoff|invariant-report)\.[a-z]+$/i
+ *
+ * We cap the returned text at 1500 chars per artifact and 3 artifacts total
+ * so the feedback block stays bounded. Freshness is required by default to
+ * avoid carrying stale diagnostics forever; when a prior run explicitly ended
+ * with BLOCKED_HANDOFF, the canonical handoff files may be included even when
+ * stale because they are the persisted operator-facing diagnosis.
+ *
+ * @param {string} ralphDir
+ * @param {object} [options] { repoRoot, maxArtifacts = 3, maxCharsEach = 1500, includeStaleHandoff = false }
+ * @returns {Array<{ path: string, content: string, truncated: boolean }>}
+ */
+function _detectBlockerArtifacts(ralphDir, options) {
+  const fs = require('fs');
+  const fsPath = require('path');
+  const opts = Object.assign(
+    {
+      repoRoot: process.cwd(),
+      maxArtifacts: 3,
+      maxCharsEach: 1500,
+      includeStaleHandoff: false,
+    },
+    options || {}
+  );
+
+  if (!ralphDir || !fs.existsSync(ralphDir)) return [];
+
+  const matches = new Map(); // path -> mtimeMs (dedup by absolute path)
+  const isHandoffArtifact = (name) =>
+    /^(handoff|blocked|blocker(-note)?)\.(md|txt)$/i.test(name);
+  const isInteresting = (name) =>
+    isHandoffArtifact(name) ||
+    /(invariant|blocker|handoff).*report\.(md|txt)$/i.test(name) ||
+    /report\.(md|txt)$/i.test(name);
+
+  const consider = (p) => {
+    try {
+      const st = fs.statSync(p);
+      if (!st.isFile()) return;
+      // Files larger than 1MB are almost certainly not human-curated blocker
+      // notes; skip them so we don't load logs or screenshots into the prompt.
+      if (st.size > 1024 * 1024) return;
+      // Only surface artifacts touched within the last ~10 minutes — older
+      // files are almost always stale leftovers from prior runs, and the
+      // failure mode we care about (repeated diagnosis with no progress)
+      // produces fresh writes every iteration.
+      const stale = Date.now() - st.mtimeMs > 10 * 60 * 1000;
+      if (stale && !(opts.includeStaleHandoff && isHandoffArtifact(fsPath.basename(p)))) {
+        return;
+      }
+      matches.set(fsPath.resolve(p), st.mtimeMs);
+    } catch (_) {
+      // ENOENT / permission errors: ignore — this is a best-effort probe.
+    }
+  };
+
+  // 1) Direct ralphDir scan, one level deep. .ralph/ is small, so a flat
+  //    listing is cheap and bounded.
+  try {
+    const entries = fs.readdirSync(ralphDir, { withFileTypes: true });
+    for (const ent of entries) {
+      if (ent.isFile() && isInteresting(ent.name)) {
+        consider(fsPath.join(ralphDir, ent.name));
+      }
+    }
+  } catch (_) { /* ignore */ }
+
+  // 2) Convention-based baseline location used by spec-and-loop changes:
+  //    <repoRoot>/.ralph/baselines/<change>/*report*.{txt,md}
+  //    The change name is the parent directory of ralphDir's parent in the
+  //    OpenSpec layout (e.g. .../changes/<name>/.ralph), so we derive it.
+  try {
+    const changeDir = fsPath.dirname(ralphDir);
+    const changeName = fsPath.basename(changeDir);
+    const baselinesDir = fsPath.join(opts.repoRoot, '.ralph', 'baselines', changeName);
+    if (fs.existsSync(baselinesDir)) {
+      const entries = fs.readdirSync(baselinesDir, { withFileTypes: true });
+      for (const ent of entries) {
+        if (ent.isFile() && isInteresting(ent.name)) {
+          consider(fsPath.join(baselinesDir, ent.name));
+        }
+      }
+    }
+  } catch (_) { /* ignore */ }
+
+  if (matches.size === 0) return [];
+
+  // Sort by mtime descending so the freshest artifact wins when we cap.
+  const sorted = Array.from(matches.entries())
+    .sort((a, b) => b[1] - a[1])
+    .map(([p]) => p);
+
+  const out = [];
+  for (const p of sorted.slice(0, opts.maxArtifacts)) {
+    try {
+      const raw = fs.readFileSync(p, 'utf8');
+      const truncated = raw.length > opts.maxCharsEach;
+      const content = truncated ? raw.slice(0, opts.maxCharsEach) : raw;
+      out.push({
+        path: fsPath.relative(opts.repoRoot, p) || p,
+        content: content.trim(),
+        truncated,
+      });
+    } catch (_) {
+      // Ignore unreadable artifacts.
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Write the agent's blocker note to <ralphDir>/HANDOFF.md with iteration
+ * metadata so an operator can reproduce the context. Appends rather than
+ * overwrites: a single change can hit several BLOCKED_HANDOFFs over time
+ * (operator unblocks, loop resumes, hits a different blocker), and we want
+ * the full audit trail in one file.
+ *
+ * @param {string} ralphDir
+ * @param {object} entry { iteration, task, note, completionPromise, taskPromise }
+ * @returns {string} the absolute path to HANDOFF.md
+ */
+function _writeHandoff(ralphDir, entry) {
+  const fs = require('fs');
+  const fsPath = require('path');
+  if (!fs.existsSync(ralphDir)) {
+    fs.mkdirSync(ralphDir, { recursive: true });
+  }
+  const handoffPath = fsPath.join(ralphDir, 'HANDOFF.md');
+  const ts = new Date().toISOString();
+  const taskLine = entry.task && entry.task !== 'N/A'
+    ? entry.task
+    : '(no task in progress)';
+  const noteBlock = entry.note && entry.note.trim()
+    ? entry.note.trim()
+    : '(agent emitted BLOCKED_HANDOFF without a structured blocker note;\n' +
+      'check the iteration stdout log for the rationale)';
+
+  const section = [
+    '',
+    `## Iteration ${entry.iteration} — ${ts}`,
+    '',
+    `**Task:** ${taskLine}`,
+    '',
+    '**Agent blocker note:**',
+    '',
+    noteBlock,
+    '',
+    '**Operator next step:** investigate the blocker, take one of the actions',
+    'the task spec authorizes (revert / isolate / justify / escalate), then',
+    'rerun `ralph-run` to resume.',
+    '',
+    '---',
+    '',
+  ].join('\n');
+
+  let existing = '';
+  if (fs.existsSync(handoffPath)) {
+    existing = fs.readFileSync(handoffPath, 'utf8');
+  } else {
+    existing = '# Ralph Handoff Log\n\nThis file is appended whenever the loop\n' +
+      'exits with `BLOCKED_HANDOFF`. Each section is one blocker the\n' +
+      'agent surfaced — review newest first.\n';
+  }
+  fs.writeFileSync(handoffPath, existing + section, 'utf8');
+  return handoffPath;
+}
+
 function _appendFatalIterationFailure(ralphDir, entry) {
   errors.append(ralphDir, {
     iteration: entry.iteration,
@@ -155,6 +406,14 @@ function _appendFatalIterationFailure(ralphDir, entry) {
   });
 }
 
+function _summarizeBlockerNote(note, limit = 500) {
+  if (!note || typeof note !== 'string') return '';
+  const oneLine = note.replace(/\s+/g, ' ').trim();
+  if (!oneLine) return '';
+  if (oneLine.length <= limit) return oneLine;
+  return `${oneLine.slice(0, Math.max(0, limit - 1)).replace(/\s+$/, '')}…`;
+}
+
 /**
  * Run the iteration loop.
  *
@@ -175,6 +434,7 @@ async function run(opts) {
   const minIterations = options.minIterations;
   const completionPromise = options.completionPromise;
   const taskPromise = options.taskPromise;
+  const blockedHandoffPromise = options.blockedHandoffPromise;
   const stallThreshold =
     typeof options.stallThreshold === 'number' && options.stallThreshold >= 0
       ? Math.floor(options.stallThreshold)
@@ -200,6 +460,8 @@ async function run(opts) {
     // otherwise start fresh at 1.
     const existingState = state.read(ralphDir);
     const resumeIteration = _resolveStartIteration(existingState, options);
+    const priorRunWasBlockedHandoff =
+      existingState && existingState.exitReason === 'blocked_handoff';
 
     if (options.verbose && resumeIteration > 1) {
       process.stderr.write(
@@ -226,6 +488,9 @@ async function run(opts) {
       resumeIteration > 1 && existingState && existingState.startedAt
         ? existingState.startedAt
         : nowIso;
+    let pendingDirtyPaths = _normalizePendingDirtyPaths(
+      existingState && existingState.pendingDirtyPaths
+    );
 
     state.init(ralphDir, {
       active: true,
@@ -234,6 +499,7 @@ async function run(opts) {
       maxIterations,
       completionPromise,
       taskPromise,
+      blockedHandoffPromise,
       tasksMode: options.tasksMode,
       tasksFile: options.tasksFile || null,
       promptFile: options.promptFile || null,
@@ -245,6 +511,7 @@ async function run(opts) {
       completedAt: null,
       stoppedAt: null,
       exitReason: null,
+      pendingDirtyPaths,
     });
     stateInitialized = true;
 
@@ -269,6 +536,20 @@ async function run(opts) {
           : [];
         const currentTask = _getCurrentTaskDescription(tasksBefore);
         const currentTaskMeta = _getCurrentTaskMeta(tasksBefore);
+        pendingDirtyPaths = _refreshPendingDirtyPaths(pendingDirtyPaths);
+        state.update(ralphDir, { pendingDirtyPaths });
+
+        if (
+          pendingDirtyPaths &&
+          !_samePendingTask(pendingDirtyPaths, currentTaskMeta, currentTask)
+        ) {
+          reporter.note(
+            _formatPendingDirtyPathsBlock(pendingDirtyPaths, currentTaskMeta, currentTask),
+            'error'
+          );
+          exitReason = 'pending_dirty_paths';
+          break;
+        }
 
         reporter.iterationStarted({
           iteration: iterationCount,
@@ -279,6 +560,7 @@ async function run(opts) {
         let result;
         let promptSize = null;
         let responseSize = { bytes: 0, chars: 0, tokens: 0 };
+        let baselineGateConflict = null;
 
         try {
           // Build the prompt for this iteration
@@ -294,8 +576,27 @@ async function run(opts) {
           // dedup collapses identical entries into a single "same failure as
           // iteration N" line, so the 3-entry window is sufficient to surface
           // recurring patterns without bloating the prompt.
+          const recentHistory = history.recent(ralphDir, 3);
+          const fullHistory = history.read(ralphDir);
           const errorEntries = errors.readEntries(ralphDir, 3);
-          const iterationFeedback = _buildIterationFeedback(history.recent(ralphDir, 3), errorEntries);
+          const blockerArtifacts = _detectBlockerArtifacts(ralphDir, {
+            repoRoot: process.cwd(),
+            includeStaleHandoff:
+              priorRunWasBlockedHandoff ||
+              recentHistory.some((entry) => entry && entry.blockedHandoffDetected),
+          });
+          const iterationFeedback = _buildIterationFeedback(
+            recentHistory,
+            errorEntries,
+            blockerArtifacts,
+          );
+          baselineGateConflict = _analyzeBaselineGateConflict(
+            ralphDir,
+            options.tasksFile,
+            currentTaskMeta,
+            fullHistory,
+          );
+          const baselineGateFeedback = _formatBaselineGateFeedback(baselineGateConflict);
 
           // Inject any pending context
           const pendingContext = context.consume(ralphDir);
@@ -303,6 +604,10 @@ async function run(opts) {
           const lessonsSection = lessons.inject(ralphDir, { limit: 15 });
           const promptSections = [renderedPrompt];
 
+          if (baselineGateFeedback) {
+            promptSections.push(`## Baseline Gate Conflict\n\n${baselineGateFeedback}`);
+          }
+
           if (iterationFeedback) {
             promptSections.push(`## Recent Loop Signals\n\n${iterationFeedback}`);
           }
@@ -392,6 +697,14 @@ async function run(opts) {
         const iterationSucceeded = _wasSuccessfulIteration(result);
         const hasCompletion = iterationSucceeded && _containsPromise(outputText, completionPromise);
         const hasTask = iterationSucceeded && _containsPromise(outputText, taskPromise);
+        // Blocked-handoff is also a successful-iteration signal (the agent
+        // followed protocol and explicitly emitted a structured exit). We
+        // treat it as a third top-level outcome alongside completion/task.
+        const hasBlockedHandoff = iterationSucceeded
+          && _containsPromise(outputText, blockedHandoffPromise);
+        const blockerNote = hasBlockedHandoff
+          ? _extractBlockerNote(outputText, blockedHandoffPromise)
+          : '';
         const tasksAfter = options.tasksMode && options.tasksFile
           ? tasks.parseTasks(options.tasksFile)
           : [];
@@ -419,13 +732,42 @@ async function run(opts) {
           result.filesChanged.length > 0 &&
           (hasCompletion || (options.tasksMode && hasTask))
         ) {
+          const filesToStage = _buildAutoCommitAllowlist(
+            _mergePathLists(result.filesChanged, pendingDirtyPaths ? pendingDirtyPaths.files : []),
+            completedTasks,
+            options.tasksFile
+          );
           commitResult = _autoCommit(iterationCount, {
             completedTasks,
-            filesToStage: _buildAutoCommitAllowlist(result.filesChanged, completedTasks, options.tasksFile),
+            filesToStage,
             tasksFile: options.tasksFile,
             verbose: options.verbose,
             reporter,
           });
+          if (commitResult.committed && pendingDirtyPaths) {
+            pendingDirtyPaths = _remainingPendingDirtyPathsAfterCommit(
+              pendingDirtyPaths,
+              commitResult.anomaly
+            );
+            state.update(ralphDir, { pendingDirtyPaths });
+          }
+        }
+
+        if (
+          !commitResult.committed &&
+          Array.isArray(result.filesChanged) &&
+          result.filesChanged.length > 0 &&
+          (_isFailedIteration(result) || hasBlockedHandoff)
+        ) {
+          pendingDirtyPaths = _recordPendingDirtyPaths(pendingDirtyPaths, {
+            iteration: iterationCount,
+            reason: hasBlockedHandoff ? 'blocked_handoff' : 'failed_iteration',
+            task: currentTask,
+            taskNumber: currentTaskMeta.number,
+            taskDescription: currentTaskMeta.description,
+            files: result.filesChanged,
+          });
+          state.update(ralphDir, { pendingDirtyPaths });
         }
 
         // Record iteration in history after commit handling so operator-visible
@@ -435,6 +777,10 @@ async function run(opts) {
           duration,
           completionDetected: hasCompletion,
           taskDetected: hasTask,
+          blockedHandoffDetected: hasBlockedHandoff,
+          ...(blockerNote ? { blockedHandoffNote: _summarizeBlockerNote(blockerNote) } : {}),
+          taskNumber: currentTaskMeta.number,
+          taskDescription: currentTaskMeta.description,
           toolUsage: result.toolUsage || [],
           filesChanged: result.filesChanged || [],
           exitCode: result.exitCode,
@@ -446,6 +792,16 @@ async function run(opts) {
           commitAnomaly: commitResult.anomaly ? commitResult.anomaly.message : '',
           commitAnomalyType: commitResult.anomaly ? commitResult.anomaly.type : '',
           protectedArtifacts: commitResult.anomaly ? commitResult.anomaly.protectedArtifacts || [] : [],
+          ...(baselineGateConflict
+            ? {
+                baselineGateConflictMode: baselineGateConflict.mode,
+                baselineGateRepairAllowedFiles: baselineGateConflict.allowedFiles || [],
+                baselineGateRepairAttempted: _baselineGateRepairAttempted(
+                  baselineGateConflict,
+                  result.filesChanged || []
+                ),
+              }
+            : {}),
           ...(commitResult.anomaly && commitResult.anomaly.ignoredPaths && commitResult.anomaly.ignoredPaths.length > 0
             ? { ignoredPaths: commitResult.anomaly.ignoredPaths }
             : {}),
@@ -472,6 +828,7 @@ async function run(opts) {
           iterationFailed,
           hasCompletion,
           hasTask,
+          hasBlockedHandoff,
           completedTasksCount: completedTasks.length,
           filesChangedCount: Array.isArray(result.filesChanged) ? result.filesChanged.length : 0,
         });
@@ -487,12 +844,15 @@ async function run(opts) {
           durationMs: duration,
           outcome: iterationFailed
             ? 'failure'
-            : stalledThisIteration
-              ? 'stalled'
-              : 'success',
+            : hasBlockedHandoff
+              ? 'blocked'
+              : stalledThisIteration
+                ? 'stalled'
+                : 'success',
           committed: commitResult.committed === true,
           hasCompletion,
           hasTask,
+          hasBlockedHandoff,
           completedTasksCount: completedTasks.length,
           filesChangedCount: Array.isArray(result.filesChanged) ? result.filesChanged.length : 0,
           stallStreak,
@@ -508,6 +868,44 @@ async function run(opts) {
           break;
         }
 
+        // Blocked-handoff exits the loop *immediately* (no minIterations
+        // floor). The agent has signaled an external decision is required;
+        // we want the operator unblocked as fast as possible. We persist the
+        // agent's note before breaking so it survives even a hard-kill on
+        // the parent process (e.g. the operator hits Ctrl-C right after).
+        if (hasBlockedHandoff) {
+          let handoffPath = '';
+          try {
+            handoffPath = _writeHandoff(ralphDir, {
+              iteration: iterationCount,
+              task: currentTask,
+              note: blockerNote,
+              completionPromise,
+              taskPromise,
+            });
+          } catch (writeErr) {
+            // Don't let a HANDOFF.md write failure mask the original signal —
+            // we still want to exit cleanly with `blocked_handoff`. Surface
+            // the write error to stderr so it's diagnosable.
+            process.stderr.write(
+              `[mini-ralph] warning: failed to write HANDOFF.md: ${writeErr.message}\n`
+            );
+          }
+          reporter.note(
+            handoffPath
+              ? `agent emitted ${blockedHandoffPromise}; blocker note saved to ${handoffPath}.`
+              : `agent emitted ${blockedHandoffPromise}; halting (HANDOFF.md write failed; see stderr).`,
+            'warn'
+          );
+          if (options.verbose) {
+            process.stderr.write(
+              `[mini-ralph] ${blockedHandoffPromise} detected at iteration ${iterationCount}; halting.\n`
+            );
+          }
+          exitReason = 'blocked_handoff';
+          break;
+        }
+
         if (stallThreshold > 0 && stallStreak >= stallThreshold) {
           reporter.note(
             `stall detector: ${stallStreak} consecutive no-op iteration(s); halting.`,
@@ -587,6 +985,145 @@ function _containsPromise(text, promiseName) {
     .some((line) => line.trim() === expectedTag);
 }
 
+function _normalizePendingDirtyPaths(pending) {
+  if (!pending || typeof pending !== 'object') return null;
+  const files = _mergePathLists(pending.files || pending.paths || []);
+  if (files.length === 0) return null;
+
+  return {
+    iteration: typeof pending.iteration === 'number' ? pending.iteration : null,
+    reason: pending.reason || 'blocked_handoff',
+    task: pending.task || '',
+    taskNumber: pending.taskNumber || '',
+    taskDescription: pending.taskDescription || '',
+    files,
+    recordedAt: pending.recordedAt || new Date().toISOString(),
+  };
+}
+
+function _recordPendingDirtyPaths(existing, update) {
+  const normalized = _normalizePendingDirtyPaths({
+    iteration: update && typeof update.iteration === 'number' ? update.iteration : null,
+    reason: update && update.reason ? update.reason : 'blocked_handoff',
+    task: update && update.task ? update.task : '',
+    taskNumber: update && update.taskNumber ? update.taskNumber : '',
+    taskDescription: update && update.taskDescription ? update.taskDescription : '',
+    files: _mergePathLists(
+      existing && existing.files ? existing.files : [],
+      update && update.files ? update.files : []
+    ),
+    recordedAt: update && update.recordedAt ? update.recordedAt : new Date().toISOString(),
+  });
+
+  return normalized;
+}
+
+function _remainingPendingDirtyPathsAfterCommit(pending, anomaly) {
+  const normalized = _normalizePendingDirtyPaths(pending);
+  if (!normalized) return null;
+
+  const ignoredPaths = anomaly && Array.isArray(anomaly.ignoredPaths)
+    ? anomaly.ignoredPaths.map(_repoRelativePath).filter(Boolean)
+    : [];
+  if (ignoredPaths.length === 0) return null;
+
+  const ignoredSet = new Set(ignoredPaths);
+  const files = normalized.files.filter((file) => ignoredSet.has(file));
+  if (files.length === 0) return null;
+  return Object.assign({}, normalized, { files });
+}
+
+function _refreshPendingDirtyPaths(pending) {
+  const normalized = _normalizePendingDirtyPaths(pending);
+  if (!normalized) return null;
+
+  const dirtyPaths = _currentDirtyPathSet();
+  if (!dirtyPaths) return normalized;
+  const files = normalized.files.filter((file) => dirtyPaths.has(file));
+  if (files.length === 0) return null;
+
+  return Object.assign({}, normalized, { files });
+}
+
+function _samePendingTask(pending, currentTaskMeta, currentTask) {
+  if (!pending) return true;
+  const currentNumber = currentTaskMeta && currentTaskMeta.number ? currentTaskMeta.number : '';
+  const currentDescription = currentTaskMeta && currentTaskMeta.description ? currentTaskMeta.description : '';
+  const currentFull = currentTask || '';
+
+  if (pending.taskNumber && currentNumber) {
+    return pending.taskNumber === currentNumber;
+  }
+
+  if (pending.taskDescription && currentDescription) {
+    return pending.taskDescription === currentDescription;
+  }
+
+  return Boolean(pending.task && currentFull && pending.task === currentFull);
+}
+
+function _formatPendingDirtyPathsBlock(pending, currentTaskMeta, currentTask) {
+  const currentStamp = currentTaskMeta && currentTaskMeta.number
+    ? `${currentTaskMeta.number} ${currentTaskMeta.description || ''}`.trim()
+    : (currentTask || 'the current task');
+  const pendingStamp = pending.taskNumber
+    ? `${pending.taskNumber} ${pending.taskDescription || ''}`.trim()
+    : (pending.task || 'a prior blocked handoff');
+  const files = (pending.files || []).slice(0, 8);
+  const extra = (pending.files || []).length - files.length;
+  const fileLines = files.map((file) => `  - ${file}`).join('\n');
+  const suffix = extra > 0 ? `\n  - (+${extra} more)` : '';
+
+  return [
+    `pending dirty paths from ${pending.reason || 'blocked_handoff'} iteration ${pending.iteration || 'unknown'} remain unresolved.`,
+    `Prior task: ${pendingStamp}`,
+    `Current task: ${currentStamp}`,
+    'Resolve the prior patch before Ralph can safely continue: commit it with the same task, revert it, or move it to a separate change.',
+    'Pending paths:',
+    `${fileLines}${suffix}`,
+  ].join('\n');
+}
+
+function _currentDirtyPathSet() {
+  try {
+    const output = childProcess.execFileSync('git', ['status', '--porcelain'], {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const paths = new Set();
+    for (const line of output.split('\n')) {
+      for (const file of _parseGitStatusPaths(line)) {
+        if (file) paths.add(file);
+      }
+    }
+    return paths;
+  } catch (_) {
+    return null;
+  }
+}
+
+function _parseGitStatusPaths(line) {
+  if (!line || typeof line !== 'string') return [];
+  const rawPath = line.slice(3).trim();
+  if (!rawPath) return [];
+  if (rawPath.includes(' -> ')) {
+    return rawPath.split(' -> ').map(_stripGitStatusQuotes).filter(Boolean);
+  }
+  return [_stripGitStatusQuotes(rawPath)].filter(Boolean);
+}
+
+function _stripGitStatusQuotes(value) {
+  if (!value) return '';
+  const trimmed = value.trim();
+  if (!(trimmed.startsWith('"') && trimmed.endsWith('"'))) {
+    return trimmed;
+  }
+  return trimmed
+    .slice(1, -1)
+    .replace(/\\"/g, '"')
+    .replace(/\\\\/g, '\\');
+}
+
 /**
  * Validate required options and throw descriptive errors.
  *
@@ -835,6 +1372,19 @@ function _filterGitignored(paths, cwd) {
   }
 }
 
+function _mergePathLists(...lists) {
+  const merged = new Set();
+  for (const list of lists) {
+    for (const file of list || []) {
+      const relativeFile = _repoRelativePath(file);
+      if (relativeFile) {
+        merged.add(relativeFile);
+      }
+    }
+  }
+  return Array.from(merged);
+}
+
 /**
  * Build the explicit per-iteration git staging allowlist.
  *
@@ -976,16 +1526,19 @@ function _failureFingerprint(entry, errorEntries) {
     stderrHead = _firstNonEmptyLine(match && match.stderr, 120);
   }
   // A "no promise emitted" iteration is also a distinguishable failure mode
-  // even when exitCode===0 and there's no stderr (e.g. the agent explicitly
-  // refuses to continue). Encoding it in the fingerprint lets the dedup
-  // collapse repeated hand-off iterations into a single actionable line
-  // instead of N identical bullets.
-  const noPromise = !entry.completionDetected && !entry.taskDetected;
+  // even when exitCode===0 and there's no stderr (e.g. the agent refuses to
+  // continue without using the control protocol). Encoding it separately keeps
+  // no-progress stalls distinct from explicit BLOCKED_HANDOFF stops.
+  const noPromise =
+    !entry.completionDetected &&
+    !entry.taskDetected &&
+    !entry.blockedHandoffDetected;
   return JSON.stringify({
     failureStage: entry.failureStage || '',
     exitCode: entry.exitCode,
     stderrHead,
     noPromise,
+    blockedHandoff: Boolean(entry.blockedHandoffDetected),
     commitAnomalyType: entry.commitAnomalyType || '',
   });
 }
@@ -998,6 +1551,7 @@ function _isEmptyFingerprint(fingerprint) {
       obj.exitCode === 0 &&
       !obj.stderrHead &&
       !obj.noPromise &&
+      !obj.blockedHandoff &&
       !obj.commitAnomalyType
     );
   } catch {
@@ -1005,14 +1559,23 @@ function _isEmptyFingerprint(fingerprint) {
   }
 }
 
-function _buildIterationFeedback(recentHistory, errorEntries) {
-  if (!Array.isArray(recentHistory) || recentHistory.length === 0) {
+function _buildIterationFeedback(recentHistory, errorEntries, blockerArtifacts) {
+  const hasArtifacts = Array.isArray(blockerArtifacts) && blockerArtifacts.length > 0;
+  if ((!Array.isArray(recentHistory) || recentHistory.length === 0) && !hasArtifacts) {
     return '';
   }
+  if (!Array.isArray(recentHistory)) recentHistory = [];
 
   const problemLines = [];
   // Track fingerprint -> first iteration number for dedup
   const fingerprintSeen = new Map();
+  // Track which task each *problematic* iteration was working when it failed
+  // / produced no progress. The same `taskNumber|taskDescription` repeating
+  // across the recent window is the strongest livelock signal we have — the
+  // agent is hitting the same wall with no new information. Persist the run
+  // length so we can emit a HARD prefix above the per-iteration list when
+  // the streak crosses the noise floor (3+ consecutive on the same task).
+  const recentTasks = [];
 
   for (const entry of recentHistory) {
     const issues = [];
@@ -1029,11 +1592,28 @@ function _buildIterationFeedback(recentHistory, errorEntries) {
       issues.push(`commit anomaly: ${entry.commitAnomaly}`);
     }
 
-    if (!entry.completionDetected && !entry.taskDetected) {
+    if (entry.blockedHandoffDetected) {
+      issues.push('agent emitted BLOCKED_HANDOFF and requested operator handoff');
+    } else if (!entry.completionDetected && !entry.taskDetected) {
       issues.push('no loop promise emitted');
     }
 
     if (issues.length > 0) {
+      // Build the task-identity stamp (used both for the per-line prefix and
+      // for streak detection). Empty when the runner had no task context for
+      // the iteration (non-tasks-mode, or pre-resume entries written by an
+      // older runner version).
+      const rawTaskId = entry.taskNumber
+        ? `${entry.taskNumber}|${entry.taskDescription || ''}`
+        : (entry.taskDescription || '');
+      const taskStamp = entry.taskNumber
+        ? `Task ${entry.taskNumber}` +
+          (entry.taskDescription ? ` (${entry.taskDescription})` : '')
+        : (entry.taskDescription
+          ? `Task ${entry.taskDescription}`
+          : '');
+      if (rawTaskId) recentTasks.push(rawTaskId);
+
       // Compute fingerprint for dedup
       const fp = _failureFingerprint(entry, errorEntries);
       const isRealFailure = !_isEmptyFingerprint(fp);
@@ -1047,13 +1627,19 @@ function _buildIterationFeedback(recentHistory, errorEntries) {
 
       if (isRealFailure && fingerprintSeen.has(fp) && !isIgnoreFilterAnomaly) {
         const firstIteration = fingerprintSeen.get(fp);
+        const stampSuffix = taskStamp ? ` [${taskStamp}]` : '';
         problemLines.push(
-          `- Iteration ${entry.iteration}: same failure as iteration ${firstIteration} (see above).`
+          `- Iteration ${entry.iteration}${stampSuffix}: same failure as iteration ${firstIteration} (see above).`
         );
       } else {
         if (isRealFailure && !isIgnoreFilterAnomaly) fingerprintSeen.set(fp, entry.iteration);
 
-        let line = `- Iteration ${entry.iteration}: ${issues.join('; ')}.`;
+        const stampPrefix = taskStamp ? ` [${taskStamp}]` : '';
+        let line = `- Iteration ${entry.iteration}${stampPrefix}: ${issues.join('; ')}.`;
+
+        if (entry.blockedHandoffDetected && entry.blockedHandoffNote) {
+          line += ` Blocker note: ${entry.blockedHandoffNote}`;
+        }
 
         // For paths_ignored_filtered / all_paths_ignored, append the first two
         // ignored paths inline (with a (+N more) suffix) so the agent can see
@@ -1116,16 +1702,472 @@ function _buildIterationFeedback(recentHistory, errorEntries) {
     }
   }
 
-  if (problemLines.length === 0) {
+  if (problemLines.length === 0 && !hasArtifacts) {
+    return '';
+  }
+
+  // Detect the longest *trailing* run of the same task identity in the
+  // problematic-iteration window. Trailing because the only thing that
+  // matters is "is the most recent stretch still the same task?" — a stale
+  // streak from earlier in the window is irrelevant once the task changed.
+  let sameTaskStreak = 0;
+  let stuckTaskId = '';
+  if (recentTasks.length > 0) {
+    const last = recentTasks[recentTasks.length - 1];
+    if (last) {
+      stuckTaskId = last;
+      for (let i = recentTasks.length - 1; i >= 0; i--) {
+        if (recentTasks[i] === last) {
+          sameTaskStreak++;
+        } else {
+          break;
+        }
+      }
+    }
+  }
+
+  const sections = [];
+  // The 3-iteration threshold matches the default `stallThreshold` so the
+  // hard-prefix and the eventual stall halt are aligned: the agent sees the
+  // warning one iteration before the stall detector fires, giving it a final
+  // chance to hand off cleanly via BLOCKED_HANDOFF rather than livelock.
+  if (sameTaskStreak >= 3 && stuckTaskId) {
+    const display = stuckTaskId.includes('|')
+      ? stuckTaskId.replace('|', ' — ')
+      : stuckTaskId;
+    sections.push(
+      [
+        '⚠ STUCK ON SAME TASK',
+        `You have failed to make progress on the same task ${sameTaskStreak} iterations in a row: ${display}.`,
+        'Stop retrying the same approach. Re-read the task spec, then either:',
+        '  1. Pick a materially different approach (different files, different invariant).',
+        '  2. If the task spec authorizes it (e.g. a "Stop and hand off if:" clause fired), emit <promise>BLOCKED_HANDOFF</promise> with a structured Blocker Note and stop. The runner will save it to .ralph/HANDOFF.md.',
+        '',
+      ].join('\n')
+    );
+  }
+
+  if (problemLines.length > 0) {
+    sections.push(
+      [
+        'Use these signals to avoid repeating the same failed approach:',
+        ...problemLines,
+      ].join('\n')
+    );
+  }
+
+  if (hasArtifacts) {
+    const artifactBlocks = blockerArtifacts.map((art) => {
+      const header = `### ${art.path}${art.truncated ? '  (truncated)' : ''}`;
+      // Code-fence the body so MDX-y artifacts (` ` `, `<promise>`) don't
+      // collide with the surrounding prompt markdown.
+      return [
+        header,
+        '```',
+        art.content,
+        '```',
+      ].join('\n');
+    });
+
+    sections.push(
+      [
+        'Prior-iteration blocker artifacts (read these BEFORE re-deriving the same diagnosis):',
+        ...artifactBlocks,
+      ].join('\n\n')
+    );
+  }
+
+  return sections.join('\n');
+}
+
+function _buildBaselineGateFeedback(ralphDir, tasksFile, currentTaskMeta, recentHistory) {
+  return _formatBaselineGateFeedback(
+    _analyzeBaselineGateConflict(ralphDir, tasksFile, currentTaskMeta, recentHistory)
+  );
+}
+
+function _analyzeBaselineGateConflict(ralphDir, tasksFile, currentTaskMeta, recentHistory) {
+  if (!ralphDir || !tasksFile || !currentTaskMeta || !currentTaskMeta.description) {
+    return null;
+  }
+
+  const taskBlock = _extractCurrentTaskBlock(tasksFile, currentTaskMeta);
+  if (!taskBlock) return null;
+
+  const strictGates = _detectStrictCleanGates(taskBlock);
+  if (strictGates.length === 0) return null;
+
+  const recordedBaselines = _detectRecordedBaselineGates(ralphDir);
+  const missingBaselines = _detectMissingBaselineGates(
+    strictGates,
+    recordedBaselines,
+    taskBlock,
+    tasksFile
+  );
+
+  if (missingBaselines.length > 0) {
+    return {
+      mode: 'missing_baseline',
+      conflicts: [],
+      missingBaselines,
+      allowedFiles: [],
+      budgetUsed: false,
+    };
+  }
+
+  const failingBaselines = recordedBaselines.filter((gate) => gate.exitCode !== 0);
+  if (failingBaselines.length === 0) return null;
+
+  const baselineByGate = new Map(failingBaselines.map((gate) => [gate.name, gate]));
+  const conflicts = strictGates
+    .map((gate) => ({ gate, baseline: baselineByGate.get(gate.name) }))
+    .filter((item) => item.baseline);
+
+  if (conflicts.length === 0) return null;
+
+  const cleanup = _detectAuthorizedBaselineCleanup(taskBlock);
+  if (cleanup.allowedFiles.length > 0) {
+    return {
+      mode: 'authorized_cleanup',
+      conflicts,
+      allowedFiles: cleanup.allowedFiles,
+      budgetUsed: _baselineGateRepairBudgetUsed(recentHistory, currentTaskMeta, cleanup.allowedFiles),
+    };
+  }
+
+  if (_taskExplicitlyHandlesBaselineFailures(taskBlock)) {
+    return {
+      mode: 'baseline_classification',
+      conflicts,
+      allowedFiles: [],
+      budgetUsed: false,
+    };
+  }
+
+  return {
+    mode: 'missing_policy',
+    conflicts,
+    allowedFiles: [],
+    budgetUsed: false,
+  };
+}
+
+function _formatBaselineGateFeedback(conflict) {
+  const conflicts = Array.isArray(conflict && conflict.conflicts) ? conflict.conflicts : [];
+  const missingBaselines = Array.isArray(conflict && conflict.missingBaselines)
+    ? conflict.missingBaselines
+    : [];
+
+  if (!conflict || (conflicts.length === 0 && missingBaselines.length === 0)) {
     return '';
   }
 
+  const conflictLines = conflicts.map(({ gate, baseline }) =>
+    `- ${gate.command}: baseline ${baseline.file} exits ${baseline.exitCode}.`
+  );
+  const missingLines = missingBaselines.map((gate) =>
+    `- ${gate.command}: no matching baseline artifact found under .ralph/baselines.`
+  );
+
+  if (conflict.mode === 'missing_baseline') {
+    return [
+      'The current task uses a strict clean quality gate and the task plan indicates a pre-flight baseline should exist, but the matching baseline artifact is missing.',
+      'Do not classify failures as pre-existing or spend an implementation iteration trying to satisfy an impossible task contract.',
+      'emit BLOCKED_HANDOFF and ask the operator to rerun or restore the pre-flight baseline artifact, or update the task spec to authorize a different gate policy.',
+      '',
+      ...missingLines,
+    ].join('\n');
+  }
+
+  if (conflict.mode === 'authorized_cleanup') {
+    if (conflict.budgetUsed) {
+      return [
+        'The current task explicitly authorized cleanup for baseline gate failures, but its one repair attempt has already been used.',
+        'Do not keep iterating on cleanup or broaden the edit scope.',
+        'If the gate is still failing, emit BLOCKED_HANDOFF with the remaining failing identifiers and ask for either a broader cleanup task or a task-spec change.',
+        '',
+        `Authorized cleanup files: ${conflict.allowedFiles.join(', ')}`,
+        ...conflictLines,
+      ].join('\n');
+    }
+
+    return [
+      'The current task explicitly authorizes cleanup for baseline gate failures in named files.',
+      'You have exactly one repair attempt for this task. Limit edits to compiler/lint-only fixes in the authorized files; do not change behavior or edit other files for this cleanup.',
+      'If this attempt does not clear the gate, emit BLOCKED_HANDOFF instead of continuing to retry.',
+      '',
+      `Authorized cleanup files: ${conflict.allowedFiles.join(', ')}`,
+      ...conflictLines,
+    ].join('\n');
+  }
+
+  if (conflict.mode === 'baseline_classification') {
+    return [
+      'The current task has strict quality-gate checks, and matching pre-flight baselines are already failing.',
+      'The task text appears to authorize baseline classification, so do not repair unrelated baseline failures unless the task explicitly names those files.',
+      'Complete the task only if the current run has no new failures beyond the named baseline failures.',
+      '',
+      ...conflictLines,
+    ].join('\n');
+  }
+
   return [
-    'Use these signals to avoid repeating the same failed approach:',
-    ...problemLines,
+    'The current task requires a clean gate that already has a failing pre-flight baseline, but the task text does not say whether baseline-matching failures may be classified.',
+    'Do not spend iterations repairing unrelated files outside the current task scope.',
+    'If the only remaining gate failures match the baseline, emit BLOCKED_HANDOFF with a task-spec correction request: either allow baseline classification for this gate, or explicitly authorize the named out-of-scope repair.',
+    '',
+    ...conflictLines,
   ].join('\n');
 }
 
+function _extractCurrentTaskBlock(tasksFile, currentTaskMeta) {
+  const fs = require('fs');
+  if (!tasksFile || !fs.existsSync(tasksFile)) return '';
+
+  const lines = fs.readFileSync(tasksFile, 'utf8').split(/\r?\n/);
+  const taskHeader = /^-\s+\[[ x/]\]\s+(.+)$/;
+  const targetNumber = currentTaskMeta.number || '';
+  const targetDescription = (currentTaskMeta.description || '').trim();
+  let start = -1;
+
+  for (let i = 0; i < lines.length; i++) {
+    const match = lines[i].match(taskHeader);
+    if (!match) continue;
+
+    const fullDescription = match[1].trim();
+    const numMatch = fullDescription.match(/^(\d+\.\d+)\s+(.+)$/);
+    const number = numMatch ? numMatch[1] : '';
+    const description = (numMatch ? numMatch[2] : fullDescription).trim();
+
+    if (
+      (targetNumber && number === targetNumber) ||
+      (!targetNumber && description === targetDescription) ||
+      (targetNumber && description === targetDescription)
+    ) {
+      start = i;
+      break;
+    }
+  }
+
+  if (start === -1) return '';
+
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (taskHeader.test(lines[i])) {
+      end = i;
+      break;
+    }
+  }
+
+  return lines.slice(start, end).join('\n');
+}
+
+function _detectStrictCleanGates(taskBlock) {
+  if (!taskBlock) return [];
+
+  const gates = [
+    {
+      name: 'typecheck',
+      command: 'pnpm typecheck',
+      pattern: /`?pnpm\s+typecheck`?[^\n]*(?:exits?|returns?)\s+0/i,
+    },
+    {
+      name: 'lint',
+      command: 'pnpm lint',
+      pattern: /`?pnpm\s+lint`?[^\n]*(?:exits?|returns?)\s+0/i,
+    },
+    {
+      name: 'test',
+      command: 'pnpm test',
+      pattern: /`?pnpm\s+test`?[^\n]*(?:exits?|returns?)\s+0/i,
+    },
+  ];
+
+  return gates.filter((gate) => gate.pattern.test(taskBlock));
+}
+
+function _detectFailingBaselineGates(ralphDir) {
+  return _detectRecordedBaselineGates(ralphDir).filter((gate) => gate.exitCode !== 0);
+}
+
+function _detectRecordedBaselineGates(ralphDir) {
+  const fs = require('fs');
+  const fsPath = require('path');
+  const baselinesDir = fsPath.join(ralphDir, 'baselines');
+  if (!fs.existsSync(baselinesDir) || !fs.statSync(baselinesDir).isDirectory()) {
+    return [];
+  }
+
+  const gates = [];
+  for (const name of fs.readdirSync(baselinesDir)) {
+    if (!/\.txt$/i.test(name)) continue;
+
+    const gateName = _gateNameFromBaselineFile(name);
+    if (!gateName) continue;
+
+    const file = fsPath.join(baselinesDir, name);
+    const tail = _readFileTail(file, 16384);
+    const exitMatch = tail.match(/(?:^|\n)EXIT=(\d+)(?:\n|$)/);
+    if (!exitMatch) continue;
+
+    const exitCode = Number(exitMatch[1]);
+    if (!Number.isInteger(exitCode)) continue;
+
+    gates.push({ name: gateName, file: fsPath.join('baselines', name), exitCode });
+  }
+
+  const priority = { typecheck: 1, lint: 2, test: 3 };
+  return gates.sort((a, b) =>
+    (priority[a.name] || 99) - (priority[b.name] || 99) ||
+    a.file.localeCompare(b.file)
+  );
+}
+
+function _detectMissingBaselineGates(strictGates, recordedBaselines, taskBlock, tasksFile) {
+  if (!Array.isArray(strictGates) || strictGates.length === 0) return [];
+
+  const expectsBaseline =
+    _taskExplicitlyHandlesBaselineFailures(taskBlock) ||
+    _completedPreflightBaselineExists(tasksFile);
+
+  if (!expectsBaseline) return [];
+
+  const recordedNames = new Set((recordedBaselines || []).map((gate) => gate.name));
+  return strictGates.filter((gate) => !recordedNames.has(gate.name));
+}
+
+function _completedPreflightBaselineExists(tasksFile) {
+  const fs = require('fs');
+  if (!tasksFile || !fs.existsSync(tasksFile)) return false;
+
+  const lines = fs.readFileSync(tasksFile, 'utf8').split(/\r?\n/);
+  return lines.some((line) =>
+    /^-\s+\[x\]\s+.*\bpre-?flight\b.*\bbaselines?\b/i.test(line)
+  );
+}
+
+function _gateNameFromBaselineFile(fileName) {
+  const normalized = fileName.toLowerCase();
+  if (/(^|[-_.])typecheck([-_.]|\.|$)/.test(normalized)) return 'typecheck';
+  if (/(^|[-_.])lint([-_.]|\.|$)/.test(normalized)) return 'lint';
+  if (/(^|[-_.])test([-_.]|\.|$)/.test(normalized)) return 'test';
+  return '';
+}
+
+function _readFileTail(file, maxBytes) {
+  const fs = require('fs');
+  let fd = null;
+  try {
+    const stat = fs.statSync(file);
+    const length = Math.min(stat.size, maxBytes);
+    const offset = Math.max(0, stat.size - length);
+    const buffer = Buffer.alloc(length);
+    fd = fs.openSync(file, 'r');
+    fs.readSync(fd, buffer, 0, length, offset);
+    return buffer.toString('utf8');
+  } catch {
+    return '';
+  } finally {
+    if (fd !== null) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        // Ignore close failures while building best-effort feedback.
+      }
+    }
+  }
+}
+
+function _taskExplicitlyHandlesBaselineFailures(taskBlock) {
+  return /\bbaseline\b/i.test(taskBlock) &&
+    /\b(match|matches|matching|classif(?:y|ied|ication)|pre-existing|preexisting|no new failures?)\b/i.test(taskBlock);
+}
+
+function _detectAuthorizedBaselineCleanup(taskBlock) {
+  if (!taskBlock || !/\b(authori[sz]ed cleanup|after fixing|fixing the named baseline failures?)\b/i.test(taskBlock)) {
+    return { allowedFiles: [] };
+  }
+
+  const allowedFiles = [];
+  const seen = new Set();
+  const backtickPattern = /`([^`]+)`/g;
+  let match;
+
+  while ((match = backtickPattern.exec(taskBlock)) !== null) {
+    const candidate = match[1].trim();
+    if (!_looksLikeCleanupPath(candidate)) continue;
+
+    const normalized = candidate.replace(/\\/g, '/');
+    if (seen.has(normalized)) continue;
+
+    seen.add(normalized);
+    allowedFiles.push(normalized);
+  }
+
+  return { allowedFiles };
+}
+
+function _looksLikeCleanupPath(value) {
+  if (!value || /\s/.test(value)) return false;
+  if (/^(pnpm|npm|yarn|node|gtimeout|timeout|rg|git)(\s|$)/i.test(value)) return false;
+  if (/^--?/.test(value)) return false;
+  if (/[*{}]/.test(value)) return false;
+  return value.includes('/') || /\.[A-Za-z0-9]+$/.test(value);
+}
+
+function _baselineGateRepairBudgetUsed(recentHistory, currentTaskMeta, allowedFiles) {
+  if (!Array.isArray(recentHistory) || recentHistory.length === 0) return false;
+
+  return recentHistory.some((entry) => {
+    if (!_historyEntryMatchesTask(entry, currentTaskMeta)) return false;
+    if (entry.baselineGateRepairAttempted === true) return true;
+
+    return _baselineGateRepairAttempted(
+      { mode: 'authorized_cleanup', allowedFiles },
+      entry.filesChanged || []
+    );
+  });
+}
+
+function _baselineGateRepairAttempted(conflict, filesChanged) {
+  if (
+    !conflict ||
+    conflict.mode !== 'authorized_cleanup' ||
+    !Array.isArray(conflict.allowedFiles) ||
+    conflict.allowedFiles.length === 0 ||
+    !Array.isArray(filesChanged) ||
+    filesChanged.length === 0
+  ) {
+    return false;
+  }
+
+  return _pathsIntersect(conflict.allowedFiles, filesChanged);
+}
+
+function _historyEntryMatchesTask(entry, currentTaskMeta) {
+  if (!entry || !currentTaskMeta) return false;
+
+  const currentNumber = currentTaskMeta.number || '';
+  const currentDescription = currentTaskMeta.description || '';
+
+  if (currentNumber && entry.taskNumber === currentNumber) return true;
+  if (!currentNumber && currentDescription && entry.taskDescription === currentDescription) return true;
+
+  return false;
+}
+
+function _pathsIntersect(left, right) {
+  const normalizedLeft = new Set((left || []).map(_normalizeComparablePath));
+  return (right || []).some((pathValue) => normalizedLeft.has(_normalizeComparablePath(pathValue)));
+}
+
+function _normalizeComparablePath(pathValue) {
+  return String(pathValue || '')
+    .replace(/\\/g, '/')
+    .replace(/^\.\//, '')
+    .replace(/\/+$/, '');
+}
+
 function _extractErrorForIteration(errorEntries, iteration) {
   if (!Array.isArray(errorEntries) || errorEntries.length === 0) return null;
 
@@ -1337,12 +2379,30 @@ module.exports = {
   _validateOptions,
   _autoCommit,
   _buildAutoCommitAllowlist,
+  _mergePathLists,
+  _normalizePendingDirtyPaths,
+  _recordPendingDirtyPaths,
+  _remainingPendingDirtyPathsAfterCommit,
+  _refreshPendingDirtyPaths,
+  _samePendingTask,
+  _currentDirtyPathSet,
   _filterGitignored,
   _resolveStartIteration,
   _completedTaskDelta,
   _formatAutoCommitMessage,
   _truncateSubjectSummary,
   _buildIterationFeedback,
+  _buildBaselineGateFeedback,
+  _analyzeBaselineGateConflict,
+  _formatBaselineGateFeedback,
+  _extractCurrentTaskBlock,
+  _detectStrictCleanGates,
+  _detectFailingBaselineGates,
+  _detectRecordedBaselineGates,
+  _detectMissingBaselineGates,
+  _detectAuthorizedBaselineCleanup,
+  _baselineGateRepairBudgetUsed,
+  _baselineGateRepairAttempted,
   _extractErrorForIteration,
   _getCurrentTaskDescription,
   _getCurrentTaskMeta,
@@ -1358,4 +2418,7 @@ module.exports = {
   _failureFingerprint,
   _firstNonEmptyLine,
   _iterationIsStalled,
+  _extractBlockerNote,
+  _writeHandoff,
+  _detectBlockerArtifacts,
 };