spec-and-loop 3.0.3 → 3.3.0

package/lib/mini-ralph/runner.js

@@ -28,6 +28,14 @@ const DEFAULTS = {
   maxIterations: 50,
   completionPromise: 'COMPLETE',
   taskPromise: 'READY_FOR_NEXT_TASK',
+  // Emitted by the agent when a task's `Stop and hand off if:` clause fires
+  // (i.e. external decision required: revert protected drift, file an
+  // out-of-scope refactor, escalate to a human reviewer, etc). The runner
+  // recognizes this as a *clean* exit distinct from `stalled` — it preserves
+  // the agent's diagnosis under `<ralphDir>/HANDOFF.md` and surfaces
+  // `exitReason='blocked_handoff'` so operators can tell "this task is
+  // genuinely blocked on me" apart from "the loop livelocked."
+  blockedHandoffPromise: 'BLOCKED_HANDOFF',
   tasksMode: false,
   noCommit: false,
   verbose: false,
@@ -48,11 +56,16 @@ const DEFAULTS = {
  * Determine whether an iteration made any forward progress.
  *
  * An iteration is considered productive if any of the following are true:
- *   - OpenCode emitted the task or completion promise
+ *   - OpenCode emitted the task, completion, or blocked-handoff promise
  *   - One or more tasks transitioned to "completed" during the iteration
  *   - At least one repo-tracked file was observed to have changed
  *   - The iteration failed outright (its signal is handled separately)
  *
+ * Note: a blocked-handoff iteration is intentionally excluded from "stalled"
+ * because the agent followed protocol — it surfaced a structured exit, the
+ * runner caught it, and the loop will break this iteration. We never want
+ * to penalize the agent (or the operator) for the canonical hand-off path.
+ *
  * @param {object} iterationSignals
  * @returns {boolean}
  */
@@ -61,6 +74,7 @@ function _iterationIsStalled(iterationSignals) {
   if (iterationSignals.iterationFailed) return false;
   if (iterationSignals.hasCompletion) return false;
   if (iterationSignals.hasTask) return false;
+  if (iterationSignals.hasBlockedHandoff) return false;
   if (iterationSignals.completedTasksCount > 0) return false;
   if (iterationSignals.filesChangedCount > 0) return false;
   return true;
@@ -118,6 +132,243 @@ function _errorText(err) {
   return String(err);
 }
 
+/**
+ * Extract the agent's blocker note from iteration output. The convention is:
+ * the line containing `<promise>BLOCKED_HANDOFF</promise>` MAY be preceded by
+ * a free-text rationale block (any number of lines up to a sentinel header
+ * `## Blocker` / `## Blocker Note` / `Blocker:`), and MAY include `## Why:` /
+ * `## Done-When-Will-Be:` / `## Suggested Next Step:` sections. We capture
+ * everything from the first sentinel header up to the promise tag, with a
+ * fallback to the last 40 non-blank lines preceding the tag if no sentinel
+ * is present, so the operator gets *something* useful even when the agent
+ * skips the structured format.
+ *
+ * @param {string} outputText  full iteration stdout
+ * @param {string} promiseName configured BLOCKED_HANDOFF promise name
+ * @returns {string} the extracted note (empty string if the tag is absent)
+ */
+function _extractBlockerNote(outputText, promiseName) {
+  if (!outputText || !promiseName) return '';
+  const tag = `<promise>${promiseName}</promise>`;
+  const lines = outputText.split(/\r?\n/);
+  let tagIdx = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim() === tag) {
+      tagIdx = i;
+      break;
+    }
+  }
+  if (tagIdx === -1) return '';
+
+  // Look backwards for a sentinel header.
+  const sentinel = /^\s*(##\s*Blocker(\s+Note)?|Blocker:)/i;
+  let startIdx = tagIdx;
+  for (let i = tagIdx - 1; i >= 0; i--) {
+    if (sentinel.test(lines[i])) {
+      startIdx = i;
+      break;
+    }
+  }
+
+  if (startIdx === tagIdx) {
+    // No sentinel — fall back to the last 40 non-blank lines before the tag.
+    const window = [];
+    for (let i = tagIdx - 1; i >= 0 && window.length < 40; i--) {
+      const l = lines[i];
+      if (l.trim()) window.unshift(l);
+    }
+    return window.join('\n').trim();
+  }
+
+  return lines.slice(startIdx, tagIdx).join('\n').trim();
+}
+
+/**
+ * Scan well-known locations for blocker / diagnostic artifacts the agent
+ * may have written during the most recent iteration, and return their
+ * content (truncated) so we can tee it into the next iteration's prompt.
+ *
+ * The motivation is the failure mode we observed in the wild: the agent
+ * writes `<change-baseline>/shared-chrome-invariant-report.txt` with a clear
+ * `STATUS=BLOCKED  REASON=...` diagnosis, then on the next iteration starts
+ * from a blank slate, re-derives the same diagnosis, and burns another full
+ * LLM cycle. By auto-detecting and surfacing the artifact, the agent gets
+ * its own prior diagnosis as input on the next turn, freeing it to either
+ * (a) act on it, or (b) emit BLOCKED_HANDOFF with a richer note.
+ *
+ * Probe paths (relative to ralphDir's parent — i.e. the change root):
+ *   - <ralphDir>/HANDOFF.md
+ *   - <ralphDir>/BLOCKED.md
+ *   - <ralphDir>/blocker.md  /  blocker-note.md
+ *   - <repoRoot>/.ralph/baselines/<change>/*report*.{txt,md}
+ *   - any file under <ralphDir> matching /(blocker|handoff|invariant-report)\.[a-z]+$/i
+ *
+ * We cap the returned text at 1500 chars per artifact and 3 artifacts total
+ * so the feedback block stays bounded. Freshness is required by default to
+ * avoid carrying stale diagnostics forever; when a prior run explicitly ended
+ * with BLOCKED_HANDOFF, the canonical handoff files may be included even when
+ * stale because they are the persisted operator-facing diagnosis.
+ *
+ * @param {string} ralphDir
+ * @param {object} [options] { repoRoot, maxArtifacts = 3, maxCharsEach = 1500, includeStaleHandoff = false }
+ * @returns {Array<{ path: string, content: string, truncated: boolean }>}
+ */
+function _detectBlockerArtifacts(ralphDir, options) {
+  const fs = require('fs');
+  const fsPath = require('path');
+  const opts = Object.assign(
+    {
+      repoRoot: process.cwd(),
+      maxArtifacts: 3,
+      maxCharsEach: 1500,
+      includeStaleHandoff: false,
+    },
+    options || {}
+  );
+
+  if (!ralphDir || !fs.existsSync(ralphDir)) return [];
+
+  const matches = new Map(); // path -> mtimeMs (dedup by absolute path)
+  const isHandoffArtifact = (name) =>
+    /^(handoff|blocked|blocker(-note)?)\.(md|txt)$/i.test(name);
+  const isInteresting = (name) =>
+    isHandoffArtifact(name) ||
+    /(invariant|blocker|handoff).*report\.(md|txt)$/i.test(name) ||
+    /report\.(md|txt)$/i.test(name);
+
+  const consider = (p) => {
+    try {
+      const st = fs.statSync(p);
+      if (!st.isFile()) return;
+      // Files larger than 1MB are almost certainly not human-curated blocker
+      // notes; skip them so we don't load logs or screenshots into the prompt.
+      if (st.size > 1024 * 1024) return;
+      // Only surface artifacts touched within the last ~10 minutes — older
+      // files are almost always stale leftovers from prior runs, and the
+      // failure mode we care about (repeated diagnosis with no progress)
+      // produces fresh writes every iteration.
+      const stale = Date.now() - st.mtimeMs > 10 * 60 * 1000;
+      if (stale && !(opts.includeStaleHandoff && isHandoffArtifact(fsPath.basename(p)))) {
+        return;
+      }
+      matches.set(fsPath.resolve(p), st.mtimeMs);
+    } catch (_) {
+      // ENOENT / permission errors: ignore — this is a best-effort probe.
+    }
+  };
+
+  // 1) Direct ralphDir scan, one level deep. .ralph/ is small, so a flat
+  //    listing is cheap and bounded.
+  try {
+    const entries = fs.readdirSync(ralphDir, { withFileTypes: true });
+    for (const ent of entries) {
+      if (ent.isFile() && isInteresting(ent.name)) {
+        consider(fsPath.join(ralphDir, ent.name));
+      }
+    }
+  } catch (_) { /* ignore */ }
+
+  // 2) Convention-based baseline location used by spec-and-loop changes:
+  //    <repoRoot>/.ralph/baselines/<change>/*report*.{txt,md}
+  //    The change name is the parent directory of ralphDir's parent in the
+  //    OpenSpec layout (e.g. .../changes/<name>/.ralph), so we derive it.
+  try {
+    const changeDir = fsPath.dirname(ralphDir);
+    const changeName = fsPath.basename(changeDir);
+    const baselinesDir = fsPath.join(opts.repoRoot, '.ralph', 'baselines', changeName);
+    if (fs.existsSync(baselinesDir)) {
+      const entries = fs.readdirSync(baselinesDir, { withFileTypes: true });
+      for (const ent of entries) {
+        if (ent.isFile() && isInteresting(ent.name)) {
+          consider(fsPath.join(baselinesDir, ent.name));
+        }
+      }
+    }
+  } catch (_) { /* ignore */ }
+
+  if (matches.size === 0) return [];
+
+  // Sort by mtime descending so the freshest artifact wins when we cap.
+  const sorted = Array.from(matches.entries())
+    .sort((a, b) => b[1] - a[1])
+    .map(([p]) => p);
+
+  const out = [];
+  for (const p of sorted.slice(0, opts.maxArtifacts)) {
+    try {
+      const raw = fs.readFileSync(p, 'utf8');
+      const truncated = raw.length > opts.maxCharsEach;
+      const content = truncated ? raw.slice(0, opts.maxCharsEach) : raw;
+      out.push({
+        path: fsPath.relative(opts.repoRoot, p) || p,
+        content: content.trim(),
+        truncated,
+      });
+    } catch (_) {
+      // Ignore unreadable artifacts.
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Write the agent's blocker note to <ralphDir>/HANDOFF.md with iteration
+ * metadata so an operator can reproduce the context. Appends rather than
+ * overwrites: a single change can hit several BLOCKED_HANDOFFs over time
+ * (operator unblocks, loop resumes, hits a different blocker), and we want
+ * the full audit trail in one file.
+ *
+ * @param {string} ralphDir
+ * @param {object} entry { iteration, task, note, completionPromise, taskPromise }
+ * @returns {string} the absolute path to HANDOFF.md
+ */
+function _writeHandoff(ralphDir, entry) {
+  const fs = require('fs');
+  const fsPath = require('path');
+  if (!fs.existsSync(ralphDir)) {
+    fs.mkdirSync(ralphDir, { recursive: true });
+  }
+  const handoffPath = fsPath.join(ralphDir, 'HANDOFF.md');
+  const ts = new Date().toISOString();
+  const taskLine = entry.task && entry.task !== 'N/A'
+    ? entry.task
+    : '(no task in progress)';
+  const noteBlock = entry.note && entry.note.trim()
+    ? entry.note.trim()
+    : '(agent emitted BLOCKED_HANDOFF without a structured blocker note;\n' +
+      'check the iteration stdout log for the rationale)';
+
+  const section = [
+    '',
+    `## Iteration ${entry.iteration} — ${ts}`,
+    '',
+    `**Task:** ${taskLine}`,
+    '',
+    '**Agent blocker note:**',
+    '',
+    noteBlock,
+    '',
+    '**Operator next step:** investigate the blocker, take one of the actions',
+    'the task spec authorizes (revert / isolate / justify / escalate), then',
+    'rerun `ralph-run` to resume.',
+    '',
+    '---',
+    '',
+  ].join('\n');
+
+  let existing = '';
+  if (fs.existsSync(handoffPath)) {
+    existing = fs.readFileSync(handoffPath, 'utf8');
+  } else {
+    existing = '# Ralph Handoff Log\n\nThis file is appended whenever the loop\n' +
+      'exits with `BLOCKED_HANDOFF`. Each section is one blocker the\n' +
+      'agent surfaced — review newest first.\n';
+  }
+  fs.writeFileSync(handoffPath, existing + section, 'utf8');
+  return handoffPath;
+}
+
 function _appendFatalIterationFailure(ralphDir, entry) {
   errors.append(ralphDir, {
     iteration: entry.iteration,
@@ -155,6 +406,14 @@ function _appendFatalIterationFailure(ralphDir, entry) {
   });
 }
 
+function _summarizeBlockerNote(note, limit = 500) {
+  if (!note || typeof note !== 'string') return '';
+  const oneLine = note.replace(/\s+/g, ' ').trim();
+  if (!oneLine) return '';
+  if (oneLine.length <= limit) return oneLine;
+  return `${oneLine.slice(0, Math.max(0, limit - 1)).replace(/\s+$/, '')}…`;
+}
+
 /**
  * Run the iteration loop.
  *
@@ -175,6 +434,7 @@ async function run(opts) {
   const minIterations = options.minIterations;
   const completionPromise = options.completionPromise;
   const taskPromise = options.taskPromise;
+  const blockedHandoffPromise = options.blockedHandoffPromise;
   const stallThreshold =
     typeof options.stallThreshold === 'number' && options.stallThreshold >= 0
       ? Math.floor(options.stallThreshold)
@@ -200,6 +460,8 @@ async function run(opts) {
     // otherwise start fresh at 1.
     const existingState = state.read(ralphDir);
     const resumeIteration = _resolveStartIteration(existingState, options);
+    const priorRunWasBlockedHandoff =
+      existingState && existingState.exitReason === 'blocked_handoff';
 
     if (options.verbose && resumeIteration > 1) {
       process.stderr.write(
@@ -234,6 +496,7 @@ async function run(opts) {
       maxIterations,
       completionPromise,
       taskPromise,
+      blockedHandoffPromise,
       tasksMode: options.tasksMode,
       tasksFile: options.tasksFile || null,
       promptFile: options.promptFile || null,
@@ -294,8 +557,19 @@ async function run(opts) {
           // dedup collapses identical entries into a single "same failure as
           // iteration N" line, so the 3-entry window is sufficient to surface
           // recurring patterns without bloating the prompt.
+          const recentHistory = history.recent(ralphDir, 3);
           const errorEntries = errors.readEntries(ralphDir, 3);
-          const iterationFeedback = _buildIterationFeedback(history.recent(ralphDir, 3), errorEntries);
+          const blockerArtifacts = _detectBlockerArtifacts(ralphDir, {
+            repoRoot: process.cwd(),
+            includeStaleHandoff:
+              priorRunWasBlockedHandoff ||
+              recentHistory.some((entry) => entry && entry.blockedHandoffDetected),
+          });
+          const iterationFeedback = _buildIterationFeedback(
+            recentHistory,
+            errorEntries,
+            blockerArtifacts,
+          );
 
           // Inject any pending context
           const pendingContext = context.consume(ralphDir);
@@ -392,6 +666,14 @@ async function run(opts) {
         const iterationSucceeded = _wasSuccessfulIteration(result);
         const hasCompletion = iterationSucceeded && _containsPromise(outputText, completionPromise);
         const hasTask = iterationSucceeded && _containsPromise(outputText, taskPromise);
+        // Blocked-handoff is also a successful-iteration signal (the agent
+        // followed protocol and explicitly emitted a structured exit). We
+        // treat it as a third top-level outcome alongside completion/task.
+        const hasBlockedHandoff = iterationSucceeded
+          && _containsPromise(outputText, blockedHandoffPromise);
+        const blockerNote = hasBlockedHandoff
+          ? _extractBlockerNote(outputText, blockedHandoffPromise)
+          : '';
         const tasksAfter = options.tasksMode && options.tasksFile
           ? tasks.parseTasks(options.tasksFile)
           : [];
@@ -435,6 +717,10 @@ async function run(opts) {
           duration,
           completionDetected: hasCompletion,
           taskDetected: hasTask,
+          blockedHandoffDetected: hasBlockedHandoff,
+          ...(blockerNote ? { blockedHandoffNote: _summarizeBlockerNote(blockerNote) } : {}),
+          taskNumber: currentTaskMeta.number,
+          taskDescription: currentTaskMeta.description,
           toolUsage: result.toolUsage || [],
           filesChanged: result.filesChanged || [],
           exitCode: result.exitCode,
@@ -472,6 +758,7 @@ async function run(opts) {
           iterationFailed,
           hasCompletion,
           hasTask,
+          hasBlockedHandoff,
           completedTasksCount: completedTasks.length,
           filesChangedCount: Array.isArray(result.filesChanged) ? result.filesChanged.length : 0,
         });
@@ -487,12 +774,15 @@ async function run(opts) {
           durationMs: duration,
           outcome: iterationFailed
             ? 'failure'
-            : stalledThisIteration
-              ? 'stalled'
-              : 'success',
+            : hasBlockedHandoff
+              ? 'blocked'
+              : stalledThisIteration
+                ? 'stalled'
+                : 'success',
           committed: commitResult.committed === true,
           hasCompletion,
           hasTask,
+          hasBlockedHandoff,
           completedTasksCount: completedTasks.length,
           filesChangedCount: Array.isArray(result.filesChanged) ? result.filesChanged.length : 0,
           stallStreak,
@@ -508,6 +798,44 @@ async function run(opts) {
           break;
         }
 
+        // Blocked-handoff exits the loop *immediately* (no minIterations
+        // floor). The agent has signaled an external decision is required;
+        // we want the operator unblocked as fast as possible. We persist the
+        // agent's note before breaking so it survives even a hard-kill on
+        // the parent process (e.g. the operator hits Ctrl-C right after).
+        if (hasBlockedHandoff) {
+          let handoffPath = '';
+          try {
+            handoffPath = _writeHandoff(ralphDir, {
+              iteration: iterationCount,
+              task: currentTask,
+              note: blockerNote,
+              completionPromise,
+              taskPromise,
+            });
+          } catch (writeErr) {
+            // Don't let a HANDOFF.md write failure mask the original signal —
+            // we still want to exit cleanly with `blocked_handoff`. Surface
+            // the write error to stderr so it's diagnosable.
+            process.stderr.write(
+              `[mini-ralph] warning: failed to write HANDOFF.md: ${writeErr.message}\n`
+            );
+          }
+          reporter.note(
+            handoffPath
+              ? `agent emitted ${blockedHandoffPromise}; blocker note saved to ${handoffPath}.`
+              : `agent emitted ${blockedHandoffPromise}; halting (HANDOFF.md write failed; see stderr).`,
+            'warn'
+          );
+          if (options.verbose) {
+            process.stderr.write(
+              `[mini-ralph] ${blockedHandoffPromise} detected at iteration ${iterationCount}; halting.\n`
+            );
+          }
+          exitReason = 'blocked_handoff';
+          break;
+        }
+
         if (stallThreshold > 0 && stallStreak >= stallThreshold) {
           reporter.note(
             `stall detector: ${stallStreak} consecutive no-op iteration(s); halting.`,
@@ -976,16 +1304,19 @@ function _failureFingerprint(entry, errorEntries) {
     stderrHead = _firstNonEmptyLine(match && match.stderr, 120);
   }
   // A "no promise emitted" iteration is also a distinguishable failure mode
-  // even when exitCode===0 and there's no stderr (e.g. the agent explicitly
-  // refuses to continue). Encoding it in the fingerprint lets the dedup
-  // collapse repeated hand-off iterations into a single actionable line
-  // instead of N identical bullets.
-  const noPromise = !entry.completionDetected && !entry.taskDetected;
+  // even when exitCode===0 and there's no stderr (e.g. the agent refuses to
+  // continue without using the control protocol). Encoding it separately keeps
+  // no-progress stalls distinct from explicit BLOCKED_HANDOFF stops.
+  const noPromise =
+    !entry.completionDetected &&
+    !entry.taskDetected &&
+    !entry.blockedHandoffDetected;
   return JSON.stringify({
     failureStage: entry.failureStage || '',
     exitCode: entry.exitCode,
     stderrHead,
     noPromise,
+    blockedHandoff: Boolean(entry.blockedHandoffDetected),
     commitAnomalyType: entry.commitAnomalyType || '',
   });
 }
@@ -998,6 +1329,7 @@ function _isEmptyFingerprint(fingerprint) {
       obj.exitCode === 0 &&
       !obj.stderrHead &&
       !obj.noPromise &&
+      !obj.blockedHandoff &&
       !obj.commitAnomalyType
     );
   } catch {
@@ -1005,14 +1337,23 @@ function _isEmptyFingerprint(fingerprint) {
   }
 }
 
-function _buildIterationFeedback(recentHistory, errorEntries) {
-  if (!Array.isArray(recentHistory) || recentHistory.length === 0) {
+function _buildIterationFeedback(recentHistory, errorEntries, blockerArtifacts) {
+  const hasArtifacts = Array.isArray(blockerArtifacts) && blockerArtifacts.length > 0;
+  if ((!Array.isArray(recentHistory) || recentHistory.length === 0) && !hasArtifacts) {
     return '';
   }
+  if (!Array.isArray(recentHistory)) recentHistory = [];
 
   const problemLines = [];
   // Track fingerprint -> first iteration number for dedup
   const fingerprintSeen = new Map();
+  // Track which task each *problematic* iteration was working when it failed
+  // / produced no progress. The same `taskNumber|taskDescription` repeating
+  // across the recent window is the strongest livelock signal we have — the
+  // agent is hitting the same wall with no new information. Persist the run
+  // length so we can emit a HARD prefix above the per-iteration list when
+  // the streak crosses the noise floor (3+ consecutive on the same task).
+  const recentTasks = [];
 
   for (const entry of recentHistory) {
     const issues = [];
@@ -1029,11 +1370,28 @@ function _buildIterationFeedback(recentHistory, errorEntries) {
       issues.push(`commit anomaly: ${entry.commitAnomaly}`);
     }
 
-    if (!entry.completionDetected && !entry.taskDetected) {
+    if (entry.blockedHandoffDetected) {
+      issues.push('agent emitted BLOCKED_HANDOFF and requested operator handoff');
+    } else if (!entry.completionDetected && !entry.taskDetected) {
       issues.push('no loop promise emitted');
     }
 
     if (issues.length > 0) {
+      // Build the task-identity stamp (used both for the per-line prefix and
+      // for streak detection). Empty when the runner had no task context for
+      // the iteration (non-tasks-mode, or pre-resume entries written by an
+      // older runner version).
+      const rawTaskId = entry.taskNumber
+        ? `${entry.taskNumber}|${entry.taskDescription || ''}`
+        : (entry.taskDescription || '');
+      const taskStamp = entry.taskNumber
+        ? `Task ${entry.taskNumber}` +
+          (entry.taskDescription ? ` (${entry.taskDescription})` : '')
+        : (entry.taskDescription
+          ? `Task ${entry.taskDescription}`
+          : '');
+      if (rawTaskId) recentTasks.push(rawTaskId);
+
       // Compute fingerprint for dedup
       const fp = _failureFingerprint(entry, errorEntries);
       const isRealFailure = !_isEmptyFingerprint(fp);
@@ -1047,13 +1405,19 @@ function _buildIterationFeedback(recentHistory, errorEntries) {
 
       if (isRealFailure && fingerprintSeen.has(fp) && !isIgnoreFilterAnomaly) {
         const firstIteration = fingerprintSeen.get(fp);
+        const stampSuffix = taskStamp ? ` [${taskStamp}]` : '';
         problemLines.push(
-          `- Iteration ${entry.iteration}: same failure as iteration ${firstIteration} (see above).`
+          `- Iteration ${entry.iteration}${stampSuffix}: same failure as iteration ${firstIteration} (see above).`
         );
       } else {
         if (isRealFailure && !isIgnoreFilterAnomaly) fingerprintSeen.set(fp, entry.iteration);
 
-        let line = `- Iteration ${entry.iteration}: ${issues.join('; ')}.`;
+        const stampPrefix = taskStamp ? ` [${taskStamp}]` : '';
+        let line = `- Iteration ${entry.iteration}${stampPrefix}: ${issues.join('; ')}.`;
+
+        if (entry.blockedHandoffDetected && entry.blockedHandoffNote) {
+          line += ` Blocker note: ${entry.blockedHandoffNote}`;
+        }
 
         // For paths_ignored_filtered / all_paths_ignored, append the first two
         // ignored paths inline (with a (+N more) suffix) so the agent can see
@@ -1116,14 +1480,82 @@ function _buildIterationFeedback(recentHistory, errorEntries) {
     }
   }
 
-  if (problemLines.length === 0) {
+  if (problemLines.length === 0 && !hasArtifacts) {
     return '';
   }
 
-  return [
-    'Use these signals to avoid repeating the same failed approach:',
-    ...problemLines,
-  ].join('\n');
+  // Detect the longest *trailing* run of the same task identity in the
+  // problematic-iteration window. Trailing because the only thing that
+  // matters is "is the most recent stretch still the same task?" — a stale
+  // streak from earlier in the window is irrelevant once the task changed.
+  let sameTaskStreak = 0;
+  let stuckTaskId = '';
+  if (recentTasks.length > 0) {
+    const last = recentTasks[recentTasks.length - 1];
+    if (last) {
+      stuckTaskId = last;
+      for (let i = recentTasks.length - 1; i >= 0; i--) {
+        if (recentTasks[i] === last) {
+          sameTaskStreak++;
+        } else {
+          break;
+        }
+      }
+    }
+  }
+
+  const sections = [];
+  // The 3-iteration threshold matches the default `stallThreshold` so the
+  // hard-prefix and the eventual stall halt are aligned: the agent sees the
+  // warning one iteration before the stall detector fires, giving it a final
+  // chance to hand off cleanly via BLOCKED_HANDOFF rather than livelock.
+  if (sameTaskStreak >= 3 && stuckTaskId) {
+    const display = stuckTaskId.includes('|')
+      ? stuckTaskId.replace('|', ' — ')
+      : stuckTaskId;
+    sections.push(
+      [
+        '⚠ STUCK ON SAME TASK',
+        `You have failed to make progress on the same task ${sameTaskStreak} iterations in a row: ${display}.`,
+        'Stop retrying the same approach. Re-read the task spec, then either:',
+        '  1. Pick a materially different approach (different files, different invariant).',
+        '  2. If the task spec authorizes it (e.g. a "Stop and hand off if:" clause fired), emit <promise>BLOCKED_HANDOFF</promise> with a structured Blocker Note and stop. The runner will save it to .ralph/HANDOFF.md.',
+        '',
+      ].join('\n')
+    );
+  }
+
+  if (problemLines.length > 0) {
+    sections.push(
+      [
+        'Use these signals to avoid repeating the same failed approach:',
+        ...problemLines,
+      ].join('\n')
+    );
+  }
+
+  if (hasArtifacts) {
+    const artifactBlocks = blockerArtifacts.map((art) => {
+      const header = `### ${art.path}${art.truncated ? '  (truncated)' : ''}`;
+      // Code-fence the body so MDX-y artifacts (` ` `, `<promise>`) don't
+      // collide with the surrounding prompt markdown.
+      return [
+        header,
+        '```',
+        art.content,
+        '```',
+      ].join('\n');
+    });
+
+    sections.push(
+      [
+        'Prior-iteration blocker artifacts (read these BEFORE re-deriving the same diagnosis):',
+        ...artifactBlocks,
+      ].join('\n\n')
+    );
+  }
+
+  return sections.join('\n');
 }
 
 function _extractErrorForIteration(errorEntries, iteration) {
@@ -1358,4 +1790,7 @@ module.exports = {
   _failureFingerprint,
   _firstNonEmptyLine,
   _iterationIsStalled,
+  _extractBlockerNote,
+  _writeHandoff,
+  _detectBlockerArtifacts,
 };

package/lib/mini-ralph/tasks.js

@@ -141,39 +141,6 @@ function countTasks(tasksFile) {
   };
 }
 
-/**
- * Build a compact task-context block for the current tasks file.
- * Mirrors the shell-side task context format so prompts can render a fresh
- * snapshot on every iteration without regenerating the whole PRD.
- *
- * @param {string} tasksFile
- * @returns {string}
- */
-function taskContext(tasksFile) {
-  const all = parseTasks(tasksFile);
-  if (all.length === 0) return '';
-
-  const current =
-    all.find((task) => task.status === 'in_progress') ||
-    all.find((task) => task.status === 'incomplete') ||
-    null;
-  const completedCount = all.filter((task) => task.status === 'completed').length;
-  const total = all.length;
-
-  const sections = [];
-
-  if (current) {
-    sections.push('## Current Task');
-    sections.push(`- ${current.fullDescription || current.description}`);
-    sections.push('');
-  }
-
-  sections.push('## Progress');
-  sections.push(`- ${completedCount} of ${total} tasks complete`);
-
-  return sections.join('\n');
-}
-
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
@@ -199,6 +166,5 @@ module.exports = {
   currentTask,
   hashFile,
   countTasks,
-  taskContext,
   tasksLinkPath,
 };