spec-and-loop 3.3.2 → 3.3.4

package/lib/mini-ralph/runner.js

@@ -22,6 +22,53 @@ const invoker = require('./invoker');
 const errors = require('./errors');
 const progress = require('./progress');
 const lessons = require('./lessons');
+const supervisor = require('./supervisor');
+const handoff = require('./runner-handoff');
+const baselineGate = require('./runner-baseline-gate');
+const autoCommit = require('./runner-autocommit');
+const pendingDirty = require('./runner-pending-dirty');
+
+const _extractBlockerNote = handoff._extractBlockerNote;
+const _detectBlockerArtifacts = handoff._detectBlockerArtifacts;
+const _writeHandoff = handoff._writeHandoff;
+const _formatSupervisorHandoffSections = handoff._formatSupervisorHandoffSections;
+const _formatSupervisorList = handoff._formatSupervisorList;
+const _appendFatalIterationFailure = handoff._appendFatalIterationFailure;
+const _summarizeBlockerNote = handoff._summarizeBlockerNote;
+
+const _buildBaselineGateFeedback = baselineGate._buildBaselineGateFeedback;
+const _analyzeBaselineGateConflict = baselineGate._analyzeBaselineGateConflict;
+const _formatBaselineGateFeedback = baselineGate._formatBaselineGateFeedback;
+const _extractCurrentTaskBlock = baselineGate._extractCurrentTaskBlock;
+const _detectStrictCleanGates = baselineGate._detectStrictCleanGates;
+const _detectFailingBaselineGates = baselineGate._detectFailingBaselineGates;
+const _detectRecordedBaselineGates = baselineGate._detectRecordedBaselineGates;
+const _detectMissingBaselineGates = baselineGate._detectMissingBaselineGates;
+const _detectAuthorizedBaselineCleanup = baselineGate._detectAuthorizedBaselineCleanup;
+const _baselineGateRepairBudgetUsed = baselineGate._baselineGateRepairBudgetUsed;
+const _baselineGateRepairAttempted = baselineGate._baselineGateRepairAttempted;
+
+const _autoCommit = autoCommit._autoCommit;
+const _formatAutoCommitIgnoreBlock = autoCommit._formatAutoCommitIgnoreBlock;
+const _filterGitignored = autoCommit._filterGitignored;
+const _mergePathLists = autoCommit._mergePathLists;
+const _buildAutoCommitAllowlist = autoCommit._buildAutoCommitAllowlist;
+const _completedTaskDelta = autoCommit._completedTaskDelta;
+const _formatAutoCommitMessage = autoCommit._formatAutoCommitMessage;
+const _truncateSubjectSummary = autoCommit._truncateSubjectSummary;
+const _taskIdentity = autoCommit._taskIdentity;
+const _repoRelativePath = autoCommit._repoRelativePath;
+const _detectProtectedCommitArtifacts = autoCommit._detectProtectedCommitArtifacts;
+const _gitErrorMessage = autoCommit._gitErrorMessage;
+const _coerceGitErrorStream = autoCommit._coerceGitErrorStream;
+
+const _normalizePendingDirtyPaths = pendingDirty._normalizePendingDirtyPaths;
+const _recordPendingDirtyPaths = pendingDirty._recordPendingDirtyPaths;
+const _remainingPendingDirtyPathsAfterCommit = pendingDirty._remainingPendingDirtyPathsAfterCommit;
+const _refreshPendingDirtyPaths = pendingDirty._refreshPendingDirtyPaths;
+const _samePendingTask = pendingDirty._samePendingTask;
+const _formatPendingDirtyPathsBlock = pendingDirty._formatPendingDirtyPathsBlock;
+const _currentDirtyPathSet = pendingDirty._currentDirtyPathSet;
 
 const DEFAULTS = {
   minIterations: 1,
@@ -50,8 +97,92 @@ const DEFAULTS = {
   // toward the streak because their signal is already surfaced via the
   // `Recent Loop Signals` feedback block.
   stallThreshold: 3,
+  // Opt-in continuation after a BLOCKED_HANDOFF only when the handoff note has
+  // explicit evidence for a safe, bounded resolution class.
+  autoResolveHandoffs: true,
+  autoResolveHandoffMaxPerRun: 6,
+  selfHeal: true,
+  selfHealMaxTries: 3,
+  selfHealDownstream: true,
+  selfHealHints: true,
+  selfHealLogAccess: true,
+  selfHealVerbose: false,
+  ruleCacheEnabled: true,
+  validationTimeoutMs: 30000,
 };
 
+function _envFlag(value) {
+  if (value === undefined) return null;
+  return !/^(0|false|no|off)$/i.test(String(value || '').trim());
+}
+
+function _envPositiveInteger(value) {
+  if (value === undefined) return null;
+  const parsed = Number.parseInt(String(value).trim(), 10);
+  if (!Number.isInteger(parsed) || parsed <= 0) return null;
+  return parsed;
+}
+
+function _resolveSupervisorConfig(options) {
+  const env = process.env;
+  const readBoolean = (cliValue, envName, fallback) => {
+    if (typeof cliValue === 'boolean') return cliValue;
+    const envValue = _envFlag(env[envName]);
+    if (envValue !== null) return envValue;
+    return fallback;
+  };
+  const readPositiveInteger = (cliValue, envName, fallback) => {
+    if (Number.isInteger(cliValue) && cliValue > 0) return cliValue;
+    const envValue = _envPositiveInteger(env[envName]);
+    if (envValue !== null) return envValue;
+    return fallback;
+  };
+
+  let selfHealVerbose;
+  if (typeof options.selfHealVerbose === 'boolean') {
+    selfHealVerbose = options.selfHealVerbose;
+  } else if (options.verbose === true) {
+    selfHealVerbose = true;
+  } else {
+    selfHealVerbose = readBoolean(undefined, 'RALPH_SELF_HEAL_VERBOSE', DEFAULTS.selfHealVerbose);
+  }
+
+  return {
+    selfHeal: readBoolean(options.selfHeal, 'RALPH_SELF_HEAL', DEFAULTS.selfHeal),
+    selfHealMaxTries: readPositiveInteger(
+      options.selfHealMaxTries,
+      'RALPH_SELF_HEAL_MAX_TRIES',
+      DEFAULTS.selfHealMaxTries,
+    ),
+    selfHealDownstream: readBoolean(
+      options.selfHealDownstream,
+      'RALPH_SELF_HEAL_DOWNSTREAM',
+      DEFAULTS.selfHealDownstream,
+    ),
+    selfHealHints: readBoolean(
+      options.selfHealHints,
+      'RALPH_SELF_HEAL_HINTS',
+      DEFAULTS.selfHealHints,
+    ),
+    selfHealLogAccess: readBoolean(
+      options.selfHealLogAccess,
+      'RALPH_SELF_HEAL_LOG_ACCESS',
+      DEFAULTS.selfHealLogAccess,
+    ),
+    selfHealVerbose,
+    ruleCacheEnabled: readBoolean(
+      undefined,
+      'RALPH_SELF_HEAL_RULE_CACHE',
+      DEFAULTS.ruleCacheEnabled,
+    ),
+    validationTimeoutMs: readPositiveInteger(
+      undefined,
+      'RALPH_SELF_HEAL_VALIDATION_TIMEOUT_MS',
+      DEFAULTS.validationTimeoutMs,
+    ),
+  };
+}
+
 /**
  * Determine whether an iteration made any forward progress.
  *
@@ -80,6 +211,156 @@ function _iterationIsStalled(iterationSignals) {
   return true;
 }
 
+function _resolveAutoResolveHandoffConfig(options, existingState) {
+  const enabled = options.autoResolveHandoffs === true;
+  const maxPerRun =
+    Number.isInteger(options.autoResolveHandoffMaxPerRun) &&
+    options.autoResolveHandoffMaxPerRun > 0
+      ? options.autoResolveHandoffMaxPerRun
+      : DEFAULTS.autoResolveHandoffMaxPerRun;
+  const previous =
+    existingState &&
+    existingState.autoResolveHandoffs &&
+    typeof existingState.autoResolveHandoffs === 'object'
+      ? existingState.autoResolveHandoffs
+      : {};
+  const previousAttempts =
+    previous.attempts && typeof previous.attempts === 'object'
+      ? previous.attempts
+      : {};
+  const previousTotal = Number.isInteger(previous.totalAttempts)
+    ? previous.totalAttempts
+    : 0;
+
+  return {
+    enabled,
+    maxPerRun,
+    state: {
+      enabled,
+      maxPerRun,
+      totalAttempts: previousTotal,
+      attempts: Object.assign({}, previousAttempts),
+      lastDecision: previous.lastDecision || null,
+    },
+  };
+}
+
+function _handoffHasFocusedVerifierEvidence(note) {
+  if (!note) return false;
+  const text = String(note);
+  const mentionsFocusedVerifier =
+    /\bfocused\b[\s\S]{0,500}\b(verifier|command|test|spec|vitest)\b/i.test(text) ||
+    /\b(verifier|command|test|spec|vitest)\b[\s\S]{0,500}\bfocused\b/i.test(text);
+  const saysFocusedPasses =
+    /\b(passes?|passed|exits?\s+0|exit(?:ed)?\s+0|green)\b/i.test(text);
+  const saysBroadFails =
+    /\b(broad|full|required|suite|repo-wide)\b[\s\S]{0,500}\b(fails?|failed|red|non[-\s]?zero)\b/i.test(text) ||
+    /\b(fails?|failed|red|non[-\s]?zero)\b[\s\S]{0,500}\b(broad|full|required|suite|repo-wide)\b/i.test(text);
+  const saysFailuresAreUnrelated =
+    /\b(unrelated|pre[-\s]?existing|out[-\s]?of[-\s]?scope|known failures?|not introduced|baseline)\b/i.test(text);
+
+  return mentionsFocusedVerifier && saysFocusedPasses && saysBroadFails && saysFailuresAreUnrelated;
+}
+
+function _classifyAutoResolvableHandoff(blockerNote, baselineGateConflict) {
+  if (_handoffHasFocusedVerifierEvidence(blockerNote)) {
+    return {
+      className: 'verifier_narrowing',
+      summary: 'focused verifier passes while the broad verifier fails on unrelated/pre-existing failures',
+      allowedFiles: [],
+    };
+  }
+
+  if (
+    baselineGateConflict &&
+    baselineGateConflict.mode === 'authorized_cleanup' &&
+    baselineGateConflict.budgetUsed !== true &&
+    Array.isArray(baselineGateConflict.allowedFiles) &&
+    baselineGateConflict.allowedFiles.length > 0
+  ) {
+    return {
+      className: 'authorized_cleanup',
+      summary: 'task text explicitly authorizes one cleanup attempt for named files',
+      allowedFiles: baselineGateConflict.allowedFiles.slice(),
+    };
+  }
+
+  return null;
+}
+
+function _autoResolveHandoffBudgetKey(currentTaskMeta, className) {
+  const taskId =
+    currentTaskMeta && currentTaskMeta.number
+      ? currentTaskMeta.number
+      : currentTaskMeta && currentTaskMeta.description
+        ? currentTaskMeta.description
+        : 'unknown-task';
+  return `${taskId}:${className || 'unknown'}`;
+}
+
+function _decideAutoResolveHandoff(config, blockerNote, currentTaskMeta, baselineGateConflict) {
+  const disabledDecision = { allowed: false, reason: 'disabled', className: '', budgetKey: '' };
+  if (!config || config.enabled !== true) return disabledDecision;
+
+  const classification = _classifyAutoResolvableHandoff(blockerNote, baselineGateConflict);
+  if (!classification) {
+    return {
+      allowed: false,
+      reason: 'ambiguous_or_unsupported_handoff',
+      className: '',
+      budgetKey: '',
+    };
+  }
+
+  const budgetKey = _autoResolveHandoffBudgetKey(currentTaskMeta, classification.className);
+  const budgetDecision = supervisor._decideBoundedBudget({
+    totalAttempts: config.state && config.state.totalAttempts,
+    maxTotalAttempts: Number.isInteger(config.maxPerRun)
+      ? config.maxPerRun
+      : DEFAULTS.autoResolveHandoffMaxPerRun,
+    attempts: config.state && config.state.attempts,
+    budgetKey,
+  });
+
+  if (!budgetDecision.allowed) {
+    return Object.assign({}, classification, budgetDecision, { budgetKey });
+  }
+
+  return Object.assign({}, classification, {
+    allowed: budgetDecision.allowed,
+    reason: budgetDecision.reason,
+    budgetKey,
+  });
+}
+
+function _consumeAutoResolveHandoffBudget(config, decision, iteration) {
+  if (!config || !config.state || !decision || decision.allowed !== true || !decision.budgetKey) {
+    return null;
+  }
+
+  const nextState = supervisor._consumeBoundedBudget({
+    state: config.state,
+    budgetKey: decision.budgetKey,
+    entry: {
+      className: decision.className,
+      iteration,
+      attemptedAt: new Date().toISOString(),
+    },
+  });
+
+  config.state = Object.assign({}, nextState, {
+    lastDecision: {
+      className: decision.className,
+      reason: decision.reason,
+      budgetKey: decision.budgetKey,
+      iteration,
+      allowedFiles: decision.allowedFiles || [],
+    },
+  });
+
+  return config.state;
+}
+
 function _isFailedIteration(result) {
   if (!result || typeof result !== 'object') return false;
   if (result.signal !== null && result.signal !== undefined && result.signal !== '') {
@@ -133,285 +414,59 @@ function _errorText(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)
+ * Wrapper around `supervisor._recoverSupervisorTmpFiles` that streams a stderr
+ * notice for each recovery action and is invoked at runner startup so a
+ * crashed prior loop's `tasks.md.supervisor-tmp` / `.supervisor-orig` residue
+ * is reconciled before the next iteration runs. This wrapper intentionally
+ * lives on the runner side (not in supervisor.js) because the stderr
+ * narration is a runner-loop concern; the underlying atomic-rollback semantics
+ * are unit-tested in `mini-ralph-supervisor.test.js`.
  */
-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;
-    }
+function _recoverSupervisorStartupResidue(options = {}) {
+  const tasksFile = options.tasksFile ? path.resolve(options.tasksFile) : '';
+  const changeDir = options.changeDir
+    ? path.resolve(options.changeDir)
+    : (tasksFile ? path.dirname(tasksFile) : '');
+
+  if (!changeDir) {
+    return { recovered: false, actions: [] };
   }
 
-  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);
+  const recovery = supervisor._recoverSupervisorTmpFiles({
+    tasksFile: tasksFile || path.join(changeDir, 'tasks.md'),
+  });
+
+  if (recovery.recovered && Array.isArray(recovery.actions)) {
+    for (const action of recovery.actions) {
+      process.stderr.write(`[mini-ralph] supervisor recovery: ${action}\n`);
     }
-    return window.join('\n').trim();
   }
 
-  return lines.slice(startIdx, tagIdx).join('\n').trim();
+  return recovery;
 }
 
-/**
- * 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.
-    }
-  };
+function _resolveChangeDirFromTasksFile(tasksFile) {
+  if (!tasksFile) return '';
+  return path.dirname(path.resolve(tasksFile));
+}
 
-  // 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 */ }
+function _resolveOpenspecRootFromTasksFile(tasksFile) {
+  if (!tasksFile) return '';
 
-  // 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));
-        }
-      }
+  let current = path.dirname(path.resolve(tasksFile));
+  while (current) {
+    if (path.basename(current) === 'openspec') {
+      return current;
     }
-  } 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.
+    const parent = path.dirname(current);
+    if (parent === current) {
+      break;
     }
+    current = parent;
   }
 
-  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,
-    task: entry.task,
-    exitCode: entry.exitCode,
-    signal: entry.signal || '',
-    failureStage: entry.failureStage || '',
-    stderr: entry.stderr || '',
-    stdout: entry.stdout || '',
-  });
-
-  history.append(ralphDir, {
-    iteration: entry.iteration,
-    duration: entry.duration,
-    completionDetected: false,
-    taskDetected: false,
-    toolUsage: [],
-    filesChanged: [],
-    exitCode: entry.exitCode,
-    signal: entry.signal || '',
-    failureStage: entry.failureStage || '',
-    completedTasks: [],
-    commitAttempted: false,
-    commitCreated: false,
-    commitAnomaly: '',
-    commitAnomalyType: '',
-    protectedArtifacts: [],
-    promptBytes: entry.promptBytes || 0,
-    promptChars: entry.promptChars || 0,
-    promptTokens: entry.promptTokens || 0,
-    responseBytes: entry.responseBytes || 0,
-    responseChars: entry.responseChars || 0,
-    responseTokens: entry.responseTokens || 0,
-    truncated: entry.truncated || false,
-  });
-}
-
-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+$/, '')}…`;
+  return '';
 }
 
 /**
@@ -423,6 +478,13 @@ function _summarizeBlockerNote(note, limit = 500) {
 async function run(opts) {
   const options = Object.assign({}, DEFAULTS, opts);
   _validateOptions(options);
+  const supervisorConfig = _resolveSupervisorConfig(options);
+  const changeDir = options.changeDir || _resolveChangeDirFromTasksFile(options.tasksFile);
+  const openspecRoot = _resolveOpenspecRootFromTasksFile(options.tasksFile);
+
+  if (options.tasksFile) {
+    _recoverSupervisorStartupResidue({ tasksFile: options.tasksFile });
+  }
 
   const ralphDir = options.ralphDir;
   const runLock = state.acquireRunLock(ralphDir, {
@@ -449,6 +511,7 @@ async function run(opts) {
   let iterationCount = 0;
   let completed = false;
   let exitReason = 'max_iterations';
+  let pendingSupervisorHints = [];
   // Consecutive iterations that succeeded but produced no progress signal.
   // Reset whenever any progress is detected (or when the iteration failed, so
   // transient infra errors don't trip the stall detector).
@@ -462,6 +525,7 @@ async function run(opts) {
     const resumeIteration = _resolveStartIteration(existingState, options);
     const priorRunWasBlockedHandoff =
       existingState && existingState.exitReason === 'blocked_handoff';
+    const autoResolveHandoffs = _resolveAutoResolveHandoffConfig(options, existingState);
 
     if (options.verbose && resumeIteration > 1) {
       process.stderr.write(
@@ -512,6 +576,7 @@ async function run(opts) {
       stoppedAt: null,
       exitReason: null,
       pendingDirtyPaths,
+      autoResolveHandoffs: autoResolveHandoffs.state,
     });
     stateInitialized = true;
 
@@ -566,7 +631,12 @@ async function run(opts) {
           // Build the prompt for this iteration
           let renderedPrompt;
           try {
-            renderedPrompt = await prompt.render(options, iterationCount);
+            renderedPrompt = await prompt.render(Object.assign({}, options, {
+              changeDir,
+              selfHealHints: supervisorConfig.selfHealHints,
+              supervisorHints: pendingSupervisorHints,
+            }), iterationCount);
+            pendingSupervisorHints = [];
           } catch (err) {
             err.failureStage = err.failureStage || 'prompt_render';
             throw err;
@@ -597,6 +667,7 @@ async function run(opts) {
             fullHistory,
           );
           const baselineGateFeedback = _formatBaselineGateFeedback(baselineGateConflict);
+          const autoResolveHandoffFeedback = _buildAutoResolveHandoffFeedback(recentHistory);
 
           // Inject any pending context
           const pendingContext = context.consume(ralphDir);
@@ -612,6 +683,10 @@ async function run(opts) {
             promptSections.push(`## Recent Loop Signals\n\n${iterationFeedback}`);
           }
 
+          if (autoResolveHandoffFeedback) {
+            promptSections.push(`## Auto-Resolve Handoff\n\n${autoResolveHandoffFeedback}`);
+          }
+
           if (lessonsSection) {
             promptSections.push(lessonsSection);
           }
@@ -705,10 +780,68 @@ async function run(opts) {
         const blockerNote = hasBlockedHandoff
           ? _extractBlockerNote(outputText, blockedHandoffPromise)
           : '';
+        const autoResolveHandoffClassification = hasBlockedHandoff
+          ? _classifyAutoResolvableHandoff(blockerNote, baselineGateConflict)
+          : null;
+        const autoResolveHandoffDecision = hasBlockedHandoff
+          ? _decideAutoResolveHandoff(
+              autoResolveHandoffs,
+              blockerNote,
+              currentTaskMeta,
+              baselineGateConflict,
+            )
+          : null;
+        let supervisorResult = null;
+        if (
+          hasBlockedHandoff &&
+          !autoResolveHandoffClassification &&
+          supervisorConfig.selfHeal === true &&
+          options.tasksFile
+        ) {
+          const previousTasksFileEnv = process.env.RALPH_TASKS_FILE;
+          try {
+            process.env.RALPH_TASKS_FILE = options.tasksFile;
+            supervisorResult = await supervisor.runSupervisor({
+              blockerNote,
+              ralphDir,
+              changeDir,
+              openspecRoot,
+              tasksFile: options.tasksFile,
+              config: supervisorConfig,
+              iteration: iterationCount,
+              model: options.model,
+            });
+          } catch (error) {
+            process.stderr.write(
+              `[mini-ralph] warning: supervisor invocation failed: ${error.message}\n`
+            );
+          } finally {
+            if (previousTasksFileEnv === undefined) {
+              delete process.env.RALPH_TASKS_FILE;
+            } else {
+              process.env.RALPH_TASKS_FILE = previousTasksFileEnv;
+            }
+          }
+        }
+        if (autoResolveHandoffDecision && autoResolveHandoffDecision.allowed) {
+          const nextAutoResolveState = _consumeAutoResolveHandoffBudget(
+            autoResolveHandoffs,
+            autoResolveHandoffDecision,
+            iterationCount,
+          );
+          if (nextAutoResolveState) {
+            state.update(ralphDir, { autoResolveHandoffs: nextAutoResolveState });
+          }
+        }
         const tasksAfter = options.tasksMode && options.tasksFile
           ? tasks.parseTasks(options.tasksFile)
           : [];
         const completedTasks = _completedTaskDelta(tasksBefore, tasksAfter);
+        const supervisorState = supervisorResult ? state.read(ralphDir) : null;
+        const supervisorTryIndex = supervisorState && supervisorState.supervisor &&
+          Number.isInteger(supervisorState.supervisor.totalAttemptsForCurrentBlocker)
+          ? supervisorState.supervisor.totalAttemptsForCurrentBlocker
+          : undefined;
 
         let commitResult = { attempted: false, committed: false, anomaly: null };
 
@@ -787,6 +920,33 @@ async function run(opts) {
           signal: result.signal || '',
           failureStage: result.failureStage || '',
           completedTasks: completedTasks.map((task) => task.fullDescription || task.description),
+          ...(autoResolveHandoffDecision
+            ? {
+                autoResolveHandoffAttempted: autoResolveHandoffDecision.allowed === true,
+                autoResolveHandoffClass: autoResolveHandoffDecision.className || '',
+                autoResolveHandoffReason: autoResolveHandoffDecision.reason || '',
+                autoResolveHandoffBudgetKey: autoResolveHandoffDecision.budgetKey || '',
+                autoResolveHandoffAllowedFiles: autoResolveHandoffDecision.allowedFiles || [],
+              }
+            : {}),
+          ...(supervisorResult
+            ? {
+                supervisorInvoked: true,
+                ...(supervisorTryIndex !== undefined ? { supervisorTryIndex } : {}),
+                supervisorOutcome: supervisorResult.outcome || '',
+                supervisorPatchedTasks: supervisorResult.patchedTasks || [],
+                supervisorBlockerHash: supervisorResult.blockerHash || '',
+                supervisorSoftWarnings: supervisorResult.softWarnings || [],
+                supervisorHints: supervisorResult.hints || [],
+                supervisorHintsDropped: supervisorResult.hintsDropped || [],
+                supervisorReadLogs: Object.prototype.hasOwnProperty.call(supervisorResult, 'readLogs')
+                  ? supervisorResult.readLogs
+                  : null,
+                supervisorReadLogsBytes: Object.prototype.hasOwnProperty.call(supervisorResult, 'readLogsBytes')
+                  ? supervisorResult.readLogsBytes
+                  : null,
+              }
+            : {}),
           commitAttempted: commitResult.attempted,
           commitCreated: commitResult.committed,
           commitAnomaly: commitResult.anomaly ? commitResult.anomaly.message : '',
@@ -818,6 +978,25 @@ async function run(opts) {
           ...(result.lastStdoutBytes !== undefined ? { lastStdoutBytes: result.lastStdoutBytes } : {}),
           ...(result.lastStderrBytes !== undefined ? { lastStderrBytes: result.lastStderrBytes } : {}),
         });
+        if (supervisorResult && supervisorResult.outcome === 'patch_applied') {
+          for (const taskNumber of supervisorResult.patchedTasks || []) {
+            history.append(ralphDir, {
+              type: 'supervisorEdit',
+              iteration: iterationCount,
+              blockerHash: supervisorResult.blockerHash || '',
+              tryIndex: supervisorTryIndex === undefined ? null : supervisorTryIndex,
+              taskNumber,
+              rationaleSummary: supervisorResult.summary || '',
+              validatorOk: true,
+              softWarnings: supervisorResult.softWarnings || [],
+            });
+          }
+        }
+        if (supervisorResult && supervisorResult.outcome === 'patch_applied') {
+          pendingSupervisorHints = Array.isArray(supervisorResult.hints)
+            ? supervisorResult.hints.slice()
+            : [];
+        }
 
         // Stall detection is computed *before* the progress event so the
         // reporter can show the live streak alongside the badge. We still
@@ -880,6 +1059,18 @@ async function run(opts) {
               iteration: iterationCount,
               task: currentTask,
               note: blockerNote,
+              supervisor: supervisorResult
+                ? {
+                    iteration: iterationCount,
+                    tryIndex: supervisorTryIndex,
+                    blockerHash: supervisorResult.blockerHash || '',
+                    patchedTasks: supervisorResult.patchedTasks || [],
+                    softWarnings: supervisorResult.softWarnings || [],
+                    summary: supervisorResult.summary || '',
+                    attempts: supervisorResult.attempts || [],
+                    attemptsExhausted: supervisorResult.attemptsExhausted === true,
+                  }
+                : null,
               completionPromise,
               taskPromise,
             });
@@ -894,9 +1085,30 @@ async function run(opts) {
           reporter.note(
             handoffPath
               ? `agent emitted ${blockedHandoffPromise}; blocker note saved to ${handoffPath}.`
-              : `agent emitted ${blockedHandoffPromise}; halting (HANDOFF.md write failed; see stderr).`,
+              : `agent emitted ${blockedHandoffPromise}; HANDOFF.md write failed (see stderr).`,
             'warn'
           );
+          if (autoResolveHandoffDecision && autoResolveHandoffDecision.allowed) {
+            reporter.note(
+              `auto-resolve handoffs: continuing once for ${autoResolveHandoffDecision.className} (${autoResolveHandoffDecision.budgetKey}).`,
+              'warn'
+            );
+            if (options.verbose) {
+              process.stderr.write(
+                `[mini-ralph] auto-resolve handoff consumed budget key ${autoResolveHandoffDecision.budgetKey}; continuing.\n`
+              );
+            }
+            continue;
+          }
+          if (supervisorResult && supervisorResult.outcome === 'patch_applied') {
+            reporter.note('supervisor applied a tasks.md patch; continuing.', 'warn');
+            if (options.verbose) {
+              process.stderr.write(
+                `[mini-ralph] supervisor applied a tasks.md patch at iteration ${iterationCount}; continuing.\n`
+              );
+            }
+            continue;
+          }
           if (options.verbose) {
             process.stderr.write(
               `[mini-ralph] ${blockedHandoffPromise} detected at iteration ${iterationCount}; halting.\n`
@@ -985,145 +1197,6 @@ 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.
  *
@@ -1150,356 +1223,6 @@ function _validateOptions(options) {
   }
 }
 
-/**
- * Format the loud direct stderr block for auto-commit ignore-filter events.
- * Emitted via process.stderr.write (bypassing reporter dedup/buffering) on
- * every iteration where paths_ignored_filtered or all_paths_ignored fires.
- * (task 5.1 — surface-autocommit-ignore-warning-and-watchdog)
- *
- * @param {number} iteration
- * @param {{ type: string, ignoredPaths: string[] }} anomaly
- * @returns {string}
- */
-function _formatAutoCommitIgnoreBlock(iteration, anomaly) {
-  const SEP = '================================================================================\n';
-  const pathLines = (anomaly.ignoredPaths || []).map(p => `  - ${p}`).join('\n');
-  return (
-    SEP +
-    `⚠ AUTO-COMMIT IGNORE FILTER FIRED  (iteration ${iteration}, type: ${anomaly.type})\n` +
-    `Paths filtered because .gitignore matches:\n` +
-    pathLines + '\n' +
-    `Consequence: these paths are NOT in the latest commit.\n` +
-    `Remediation (pick one):\n` +
-    `  1. git add -f <path>   # one-time unblock, if you want it tracked\n` +
-    `  2. edit .gitignore     # narrow or remove the matching rule\n` +
-    `  3. pass --no-auto-commit on the ralph-run invocation\n` +
-    SEP
-  );
-}
-
-/**
- * Auto-commit changed files after a successful iteration.
- * Silently skips if git is unavailable, there is nothing to commit, or the
- * iteration did not complete any tasks.
- *
- * @param {number} iteration
- * @param {object} opts
- * @param {Array<object>} [opts.completedTasks]
- * @param {Array<string>} [opts.filesToStage]
- * @param {boolean} [opts.verbose]
- */
-function _autoCommit(iteration, opts = {}) {
-  const { completedTasks = [], filesToStage = [], tasksFile = null, verbose = false, reporter = null } = opts;
-  const message = _formatAutoCommitMessage(iteration, completedTasks);
-
-  if (!message) {
-    if (verbose) {
-      process.stderr.write('[mini-ralph] auto-commit skipped: no completed tasks detected\n');
-    }
-    return { attempted: false, committed: false, anomaly: null };
-  }
-
-  if (!Array.isArray(filesToStage) || filesToStage.length === 0) {
-    if (verbose) {
-      process.stderr.write('[mini-ralph] auto-commit skipped: no iteration files to stage\n');
-    }
-    return { attempted: false, committed: false, anomaly: null };
-  }
-
-  const protectedArtifacts = _detectProtectedCommitArtifacts(filesToStage, tasksFile);
-  if (protectedArtifacts.length > 0) {
-    const anomaly = {
-      type: 'protected_artifacts',
-      message:
-        'Auto-commit blocked: loop-managed commits cannot include protected OpenSpec artifacts: ' +
-        protectedArtifacts.join(', '),
-      protectedArtifacts,
-    };
-
-    process.stderr.write(`[mini-ralph] warning: ${anomaly.message}\n`);
-    return { attempted: true, committed: false, anomaly };
-  }
-
-  const { kept: keptPaths, dropped: droppedPaths } = _filterGitignored(filesToStage, process.cwd());
-
-  if (droppedPaths.length > 0) {
-    const pathWord = droppedPaths.length === 1 ? 'path' : 'paths';
-    const allIgnored = keptPaths.length === 0;
-    const warnLines = allIgnored
-      ? [
-          `auto-commit iter ${iteration} skipped: all ${droppedPaths.length} ${pathWord} are gitignored`,
-          ...droppedPaths.map(p => `  - ${p}`),
-          '  hint: `git add -f <path>` once, or adjust .gitignore',
-        ].join('\n')
-      : [
-          `auto-commit iter ${iteration}: filtered ${droppedPaths.length} gitignored ${pathWord}, committing ${keptPaths.length} ${keptPaths.length === 1 ? 'other' : 'others'}`,
-          ...droppedPaths.map(p => `  - ${p}`),
-        ].join('\n');
-    if (reporter) {
-      reporter.note(warnLines, 'error');
-    } else {
-      const fallbackMsg = allIgnored
-        ? `Auto-commit skipped: all paths are gitignored: ${droppedPaths.join(', ')}`
-        : `Auto-commit filtered gitignored paths: ${droppedPaths.join(', ')}`;
-      process.stderr.write(`[mini-ralph] warning: ${fallbackMsg}\n`);
-    }
-    if (allIgnored) {
-      const anomaly = {
-        type: 'all_paths_ignored',
-        message: `Auto-commit skipped: all paths are gitignored: ${droppedPaths.join(', ')}`,
-        ignoredPaths: droppedPaths,
-      };
-      // task 5.1: emit loud direct stderr block, bypassing reporter dedup/buffering
-      process.stderr.write(_formatAutoCommitIgnoreBlock(iteration, anomaly));
-      return {
-        attempted: true,
-        committed: false,
-        anomaly,
-      };
-    }
-  }
-
-  const stagePaths = droppedPaths.length > 0 ? keptPaths : filesToStage;
-
-  try {
-    // Use `git add -A -- <paths>` (not plain `git add -- <paths>`) so deletions
-    // and renames are staged alongside modifications/additions. Tasks that call
-    // `git rm` via a shell tool leave the path absent from the working tree but
-    // still present in `git status --porcelain`, which means the plain form
-    // would error with `fatal: pathspec did not match`. Scoping to the per-path
-    // allowlist preserves the protected-artifact guarantee.
-    childProcess.execFileSync('git', ['add', '-A', '--', ...stagePaths], {
-      stdio: verbose ? 'inherit' : ['pipe', 'pipe', 'pipe'],
-      encoding: 'utf8',
-    });
-
-    const stagedFiles = childProcess.execFileSync('git', ['diff', '--cached', '--name-only'], {
-      stdio: ['pipe', 'pipe', 'pipe'],
-      encoding: 'utf8',
-    });
-
-    if (!stagedFiles.trim()) {
-      const anomaly = {
-        type: 'nothing_staged',
-        message: 'Auto-commit failed: nothing was staged after git add',
-      };
-
-      process.stderr.write(`[mini-ralph] warning: ${anomaly.message}\n`);
-      if (verbose) {
-        process.stderr.write('[mini-ralph] auto-commit skipped: nothing staged\n');
-      }
-      return { attempted: true, committed: false, anomaly };
-    }
-
-    childProcess.execFileSync('git', ['commit', '-m', message], {
-      stdio: verbose ? 'inherit' : ['pipe', 'pipe', 'pipe'],
-      encoding: 'utf8',
-    });
-
-    if (verbose) {
-      process.stderr.write(`[mini-ralph] auto-committed: ${message}\n`);
-    }
-    if (droppedPaths.length > 0) {
-      const anomaly = {
-        type: 'paths_ignored_filtered',
-        message: 'Auto-commit succeeded but filtered gitignored paths: ' + droppedPaths.join(', '),
-        ignoredPaths: droppedPaths,
-      };
-      // task 5.1: emit loud direct stderr block, bypassing reporter dedup/buffering
-      process.stderr.write(_formatAutoCommitIgnoreBlock(iteration, anomaly));
-      return {
-        attempted: true,
-        committed: true,
-        anomaly,
-      };
-    }
-    return { attempted: true, committed: true, anomaly: null };
-  } catch (err) {
-    const anomaly = {
-      type: 'commit_failed',
-      message: `Auto-commit failed: ${_gitErrorMessage(err)}`,
-    };
-
-    process.stderr.write(`[mini-ralph] warning: ${anomaly.message}\n`);
-    return { attempted: true, committed: false, anomaly };
-  }
-}
-
-/**
- * Filter gitignored paths out of a list using `git check-ignore --stdin`.
- *
- * Exit-code semantics of `git check-ignore`:
- *   0  – at least one path is ignored; stdout lists the ignored paths.
- *   1  – no paths are ignored (Node's execFileSync throws; we catch status===1).
- *   other / ENOENT / any thrown error – fallback: treat all paths as kept.
- *
- * @param {string[]} paths - Repo-relative paths to test.
- * @param {string}   cwd   - Working directory for the git command.
- * @returns {{ kept: string[], dropped: string[] }}
- */
-function _filterGitignored(paths, cwd) {
-  if (!Array.isArray(paths) || paths.length === 0) {
-    return { kept: [], dropped: [] };
-  }
-
-  try {
-    const stdout = childProcess.execFileSync(
-      'git',
-      ['check-ignore', '--stdin'],
-      {
-        input: paths.join('\n'),
-        cwd: cwd || process.cwd(),
-        stdio: ['pipe', 'pipe', 'pipe'],
-        encoding: 'utf8',
-      }
-    );
-
-    // Exit code 0: stdout lists ignored paths (one per line).
-    const dropped = stdout
-      .split('\n')
-      .map((l) => l.trim())
-      .filter(Boolean);
-    const droppedSet = new Set(dropped);
-    const kept = paths.filter((p) => !droppedSet.has(p));
-    return { kept, dropped };
-  } catch (err) {
-    // exit status 1 means "no paths ignored" — treat as success with no drops.
-    if (err && err.status === 1) {
-      return { kept: paths.slice(), dropped: [] };
-    }
-    // Any other error (ENOENT, unexpected exit code, etc.) — fallback, never crash.
-    return { kept: paths.slice(), dropped: [] };
-  }
-}
-
-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.
- *
- * @param {Array<string>} filesChanged
- * @param {Array<object>} completedTasks
- * @param {string|null|undefined} tasksFile
- * @returns {Array<string>}
- */
-function _buildAutoCommitAllowlist(filesChanged, completedTasks, tasksFile) {
-  const allowlist = new Set();
-
-  for (const file of filesChanged || []) {
-    const relativeFile = _repoRelativePath(file);
-    if (relativeFile) {
-      allowlist.add(relativeFile);
-    }
-  }
-
-  if (Array.isArray(completedTasks) && completedTasks.length > 0 && tasksFile) {
-    const relativeTasksFile = _repoRelativePath(tasksFile);
-    if (relativeTasksFile) {
-      allowlist.add(relativeTasksFile);
-    }
-  }
-
-  return Array.from(allowlist);
-}
-
-/**
- * Return tasks that became completed during the current iteration.
- *
- * @param {Array<object>} beforeTasks
- * @param {Array<object>} afterTasks
- * @returns {Array<object>}
- */
-function _completedTaskDelta(beforeTasks, afterTasks) {
-  const beforeCompleted = new Set(
-    (beforeTasks || [])
-      .filter((task) => task.status === 'completed')
-      .map(_taskIdentity)
-  );
-
-  return (afterTasks || []).filter(
-    (task) => task.status === 'completed' && !beforeCompleted.has(_taskIdentity(task))
-  );
-}
-
-/**
- * Build a task-aware commit message for an iteration.
- *
- * The subject line (first line) is kept short — conventional git tooling
- * assumes ~50–72 characters — so `git log --oneline` stays readable even when
- * the underlying task description is a multi-sentence normative blob. The
- * full, untruncated task descriptions are preserved in the commit body.
- *
- * @param {number} iteration
- * @param {Array<object>} completedTasks
- * @returns {string}
- */
-function _formatAutoCommitMessage(iteration, completedTasks) {
-  if (!Array.isArray(completedTasks) || completedTasks.length === 0) {
-    return '';
-  }
-
-  const rawSummary = completedTasks.length === 1
-    ? completedTasks[0].description
-    : `complete ${completedTasks.length} tasks`;
-
-  const prefix = `Ralph iteration ${iteration}: `;
-  const subjectBudget = Math.max(20, SUBJECT_MAX_LENGTH - prefix.length);
-  const summary = _truncateSubjectSummary(rawSummary, subjectBudget);
-
-  const taskLines = completedTasks.map(
-    (task) => `- [x] ${task.fullDescription || task.description}`
-  );
-
-  return `${prefix}${summary}\n\nTasks completed:\n${taskLines.join('\n')}`;
-}
-
-const SUBJECT_MAX_LENGTH = 72;
-
-/**
- * Reduce a task description to a short, single-line commit subject.
- *
- * Strategy:
- *   1. Collapse whitespace onto a single line.
- *   2. Prefer the first sentence (up to `.`, `!`, `?`) when it is not itself
- *      longer than the allowed budget.
- *   3. Otherwise hard-truncate at a word boundary and append an ellipsis.
- *
- * @param {string} text
- * @param {number} budget
- * @returns {string}
- */
-function _truncateSubjectSummary(text, budget) {
-  const oneLine = String(text == null ? '' : text).replace(/\s+/g, ' ').trim();
-  if (oneLine.length === 0) return '';
-  if (oneLine.length <= budget) return oneLine;
-
-  const sentenceMatch = oneLine.match(/^(.+?[.!?])(\s|$)/);
-  if (sentenceMatch) {
-    const candidate = sentenceMatch[1].trim();
-    if (candidate.length > 0 && candidate.length <= budget) {
-      return candidate;
-    }
-  }
-
-  const ellipsis = '…';
-  const hardBudget = Math.max(1, budget - ellipsis.length);
-  const sliced = oneLine.slice(0, hardBudget);
-  const lastSpace = sliced.lastIndexOf(' ');
-  const cut = lastSpace > Math.floor(hardBudget / 2) ? sliced.slice(0, lastSpace) : sliced;
-  return `${cut.replace(/[\s,;:.!?-]+$/, '')}${ellipsis}`;
-}
-
 /**
  * Summarize recent problem signals so the next iteration can avoid repeating
  * the same failed approach.
@@ -1780,392 +1503,46 @@ function _buildIterationFeedback(recentHistory, errorEntries, blockerArtifacts)
   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 [
-    '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;
-    }
-  }
+function _buildAutoResolveHandoffFeedback(recentHistory) {
+  if (!Array.isArray(recentHistory) || recentHistory.length === 0) return '';
 
-  return lines.slice(start, end).join('\n');
-}
+  const entry = recentHistory
+    .slice()
+    .reverse()
+    .find((item) => item && item.autoResolveHandoffAttempted === true);
 
-function _detectStrictCleanGates(taskBlock) {
-  if (!taskBlock) return [];
+  if (!entry) 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,
-    },
+  const className = entry.autoResolveHandoffClass || 'unknown';
+  const spentBudget = supervisor._decideBoundedBudget({
+    totalAttempts: 0,
+    maxTotalAttempts: DEFAULTS.autoResolveHandoffMaxPerRun,
+    attempts: { spent: { className } },
+    budgetKey: 'spent',
+  });
+  const lines = [
+    `The previous iteration emitted BLOCKED_HANDOFF, but auto-resolution is enabled and ${spentBudget.allowed ? 'reserved' : 'spent'} its bounded attempt for ${className}.`,
+    'You have exactly one continuation attempt for this task/blocker class. Do not broaden task scope, do not repair unrelated snapshots or UI behavior, and do not keep retrying if the evidence does not hold.',
   ];
 
-  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 || []
+  if (className === 'verifier_narrowing') {
+    lines.push(
+      'Allowed action: if the handoff explicitly names a focused verifier that passes and a broad verifier that fails only on unrelated/pre-existing failures, update only the current task verifier from the broad command to that focused command, run the focused command once, and complete the task only if it passes. If the focused command is absent, ambiguous, or fails, emit BLOCKED_HANDOFF instead of retrying.'
+    );
+  } else if (className === 'authorized_cleanup') {
+    const files = Array.isArray(entry.autoResolveHandoffAllowedFiles)
+      ? entry.autoResolveHandoffAllowedFiles.filter(Boolean)
+      : [];
+    lines.push(
+      `Allowed action: make one cleanup attempt only in the task-authorized file list${files.length > 0 ? ` (${files.join(', ')})` : ''}. If the gate still fails, emit BLOCKED_HANDOFF instead of continuing.`
+    );
+  } else {
+    lines.push(
+      'Allowed action: continue only if the blocker evidence remains explicit and within the runner-approved safe class; otherwise emit BLOCKED_HANDOFF.'
     );
-  });
-}
-
-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(/\/+$/, '');
+  return lines.join('\n');
 }
 
 function _extractErrorForIteration(errorEntries, iteration) {
@@ -2264,75 +1641,6 @@ function _cleanupCompletedErrors(ralphDir, verbose) {
   }
 }
 
-function _taskIdentity(task) {
-  return task.number
-    ? `${task.number}|${task.fullDescription || task.description}`
-    : (task.fullDescription || task.description);
-}
-
-function _repoRelativePath(filePath) {
-  if (!filePath || typeof filePath !== 'string') return '';
-  const normalized = path.normalize(filePath);
-  if (!normalized || normalized === '.') return '';
-  const relative = path.isAbsolute(normalized)
-    ? path.relative(process.cwd(), normalized)
-    : normalized;
-
-  if (!relative || relative.startsWith('..')) {
-    return '';
-  }
-
-  return relative.split(path.sep).join('/');
-}
-
-function _detectProtectedCommitArtifacts(filesToStage, tasksFile) {
-  if (!Array.isArray(filesToStage) || filesToStage.length === 0 || !tasksFile) {
-    return [];
-  }
-
-  const relativeTasksFile = _repoRelativePath(tasksFile);
-  if (!relativeTasksFile) {
-    return [];
-  }
-
-  const changeRoot = path.posix.dirname(relativeTasksFile);
-  const protectedArtifacts = [];
-
-  for (const file of filesToStage) {
-    const normalized = _repoRelativePath(file);
-    if (!normalized) continue;
-
-    const isProposal = normalized === `${changeRoot}/proposal.md`;
-    const isDesign = normalized === `${changeRoot}/design.md`;
-    const isSpec = normalized.startsWith(`${changeRoot}/specs/`) && normalized.endsWith('/spec.md');
-
-    if (isProposal || isDesign || isSpec) {
-      protectedArtifacts.push(normalized);
-    }
-  }
-
-  return protectedArtifacts;
-}
-
-function _gitErrorMessage(err) {
-  if (!err) return 'unknown git error';
-
-  const stderr = _coerceGitErrorStream(err.stderr);
-  const stdout = _coerceGitErrorStream(err.stdout);
-
-  if (stderr) return stderr;
-  if (stdout) return stdout;
-  if (err.message) return err.message;
-  return 'unknown git error';
-}
-
-function _coerceGitErrorStream(stream) {
-  if (!stream) return '';
-  if (Buffer.isBuffer(stream)) return stream.toString('utf8').trim();
-  if (typeof stream === 'string') return stream.trim();
-  return '';
-}
-
 /**
  * Determine the starting iteration for a new run.
  *
@@ -2374,6 +1682,7 @@ function _resolveStartIteration(existingState, options) {
 
 module.exports = {
   run,
+  _recoverSupervisorStartupResidue,
   _finalizeRunState,
   _containsPromise,
   _validateOptions,
@@ -2392,6 +1701,13 @@ module.exports = {
   _formatAutoCommitMessage,
   _truncateSubjectSummary,
   _buildIterationFeedback,
+  _buildAutoResolveHandoffFeedback,
+  _resolveAutoResolveHandoffConfig,
+  _resolveSupervisorConfig,
+  _handoffHasFocusedVerifierEvidence,
+  _classifyAutoResolvableHandoff,
+  _decideAutoResolveHandoff,
+  _consumeAutoResolveHandoffBudget,
   _buildBaselineGateFeedback,
   _analyzeBaselineGateConflict,
   _formatBaselineGateFeedback,