spec-and-loop 3.3.3 → 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,
@@ -54,8 +101,88 @@ const DEFAULTS = {
   // 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.
  *
@@ -186,33 +313,22 @@ function _decideAutoResolveHandoff(config, blockerNote, currentTaskMeta, baselin
   }
 
   const budgetKey = _autoResolveHandoffBudgetKey(currentTaskMeta, classification.className);
-  const totalAttempts = Number.isInteger(config.state && config.state.totalAttempts)
-    ? config.state.totalAttempts
-    : 0;
-  const maxPerRun = Number.isInteger(config.maxPerRun)
-    ? config.maxPerRun
-    : DEFAULTS.autoResolveHandoffMaxPerRun;
-  const attempts = config.state && config.state.attempts ? config.state.attempts : {};
+  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 (totalAttempts >= maxPerRun) {
-    return Object.assign({}, classification, {
-      allowed: false,
-      reason: 'global_budget_exhausted',
-      budgetKey,
-    });
-  }
-
-  if (attempts[budgetKey]) {
-    return Object.assign({}, classification, {
-      allowed: false,
-      reason: 'task_class_budget_exhausted',
-      budgetKey,
-    });
+  if (!budgetDecision.allowed) {
+    return Object.assign({}, classification, budgetDecision, { budgetKey });
   }
 
   return Object.assign({}, classification, {
-    allowed: true,
-    reason: 'authorized',
+    allowed: budgetDecision.allowed,
+    reason: budgetDecision.reason,
     budgetKey,
   });
 }
@@ -222,20 +338,17 @@ function _consumeAutoResolveHandoffBudget(config, decision, iteration) {
     return null;
   }
 
-  const attempts = Object.assign({}, config.state.attempts || {});
-  attempts[decision.budgetKey] = {
-    className: decision.className,
-    iteration,
-    attemptedAt: new Date().toISOString(),
-  };
-
-  const totalAttempts = (Number.isInteger(config.state.totalAttempts)
-    ? config.state.totalAttempts
-    : 0) + 1;
+  const nextState = supervisor._consumeBoundedBudget({
+    state: config.state,
+    budgetKey: decision.budgetKey,
+    entry: {
+      className: decision.className,
+      iteration,
+      attemptedAt: new Date().toISOString(),
+    },
+  });
 
-  config.state = Object.assign({}, config.state, {
-    totalAttempts,
-    attempts,
+  config.state = Object.assign({}, nextState, {
     lastDecision: {
       className: decision.className,
       reason: decision.reason,
@@ -301,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 '';
 }
 
 /**
@@ -591,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, {
@@ -617,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).
@@ -736,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;
@@ -880,6 +780,9 @@ async function run(opts) {
         const blockerNote = hasBlockedHandoff
           ? _extractBlockerNote(outputText, blockedHandoffPromise)
           : '';
+        const autoResolveHandoffClassification = hasBlockedHandoff
+          ? _classifyAutoResolvableHandoff(blockerNote, baselineGateConflict)
+          : null;
         const autoResolveHandoffDecision = hasBlockedHandoff
           ? _decideAutoResolveHandoff(
               autoResolveHandoffs,
@@ -888,6 +791,38 @@ async function run(opts) {
               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,
@@ -902,6 +837,11 @@ async function run(opts) {
           ? 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 };
 
@@ -989,6 +929,24 @@ async function run(opts) {
                 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 : '',
@@ -1020,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
@@ -1082,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,
             });
@@ -1111,6 +1100,15 @@ async function run(opts) {
             }
             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`
@@ -1199,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.
  *
@@ -1364,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.
@@ -2005,8 +1514,14 @@ function _buildAutoResolveHandoffFeedback(recentHistory) {
   if (!entry) return '';
 
   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 spent its bounded attempt for ${className}.`,
+    `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.',
   ];
 
@@ -2030,394 +1545,6 @@ function _buildAutoResolveHandoffFeedback(recentHistory) {
   return lines.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;
-    }
-  }
-
-  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;
 
@@ -2514,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.
  *
@@ -2624,6 +1682,7 @@ function _resolveStartIteration(existingState, options) {
 
 module.exports = {
   run,
+  _recoverSupervisorStartupResidue,
   _finalizeRunState,
   _containsPromise,
   _validateOptions,
@@ -2644,6 +1703,7 @@ module.exports = {
   _buildIterationFeedback,
   _buildAutoResolveHandoffFeedback,
   _resolveAutoResolveHandoffConfig,
+  _resolveSupervisorConfig,
   _handoffHasFocusedVerifierEvidence,
   _classifyAutoResolvableHandoff,
   _decideAutoResolveHandoff,