pi-loop-mode 2.5.0

package/extensions/index.ts

@@ -0,0 +1,1442 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { createHash } from "node:crypto";
+import { appendFileSync, readFileSync } from "node:fs";
+
+const STATE_ENTRY_TYPE = "loop-state";
+const MESSAGE_TYPE = "loop";
+const MAX_STORED_TEXT = 280;
+const BASE_BACKOFF_SECONDS = 5;
+const MAX_BACKOFF_SECONDS = 300;
+const NO_PROGRESS_WINDOW = 8;
+const AUTO_RESUME_DELAY_MS = 3_000;
+/** Near-duplicate threshold for consecutive assistant responses (Jaccard on word trigrams). */
+const SIMILARITY_THRESHOLD = 0.8;
+/** Same fingerprint seen this many times in the recent window counts as stuck. */
+const REPEAT_WINDOW_COUNT = 3;
+/** Turns without any tool call before a stuck intervention fires. */
+const MAX_TOOLLESS_TURNS = 3;
+/** Consecutive stuck interventions before the hard-reset escalation kicks in. */
+const HARD_RESET_AFTER = 3;
+/** A sentence repeated this often inside ONE response = degenerate generation. */
+const DEGENERATE_REPEATS = 4;
+/** During streaming, abort once the repeated-sentence count reaches this. */
+const DEGENERATE_STREAM_REPEATS = 6;
+/** Re-run the degeneration check every N new streamed characters. */
+const DEGENERATE_CHECK_INTERVAL = 500;
+/** Consecutive stuck interventions before a rescue-model turn is triggered (if configured). */
+const RESCUE_AFTER = 3;
+/** Consecutive stuck interventions before the context is compacted to break fixation. */
+const COMPACT_AFTER = 5;
+/** Iterations that anti-repetition sampling penalties stay active after a stuck intervention. */
+const PENALTY_TURNS = 3;
+/** JSONL log with one entry per loop iteration/event (cwd). */
+const LOG_FILE = ".pi-loop-log.jsonl";
+
+type TurnKind =
+  | "start"
+  | "continue"
+  | "stuck"
+  | "recover"
+  | "improve"
+  | "unblock"
+  | "audit"
+  | "resume"
+  | "regression"
+  | "check_failed"
+  | "rescue";
+
+interface ToolSnapshot {
+  tool: string;
+  fingerprint: string;
+  snippet: string;
+  isError: boolean;
+  time: number;
+}
+
+interface LoopState {
+  active: boolean;
+  description: string;
+  completionCriteria: string;
+  startTime: number;
+  iterationCount: number;
+  /** 0 = unlimited (default). */
+  maxIterations: number;
+  /** If true, LOOP_DONE stops the loop. Default: endless improvement mode. */
+  untilDone: boolean;
+  /** Delay between normal iterations, in seconds. */
+  delaySeconds: number;
+  /** Objective goal function: shell command, exit 0 = criteria met, optional "SCORE: n" output. */
+  checkCommand: string;
+  checkTimeoutSeconds: number;
+  lastCheckPassed?: boolean;
+  lastCheckScore?: number;
+  bestCheckScore?: number;
+  bestScoreIteration: number;
+  checkFailStreak: number;
+  lastCheckOutput: string;
+  /** Spec file written by /loop prepare; referenced in loop prompts. */
+  goalFile: string;
+  /** Model spec ("provider/id" or id) the loop should run with; "" = current model. */
+  loopModel: string;
+  /** Stronger model called in for a single turn after repeated stuck interventions; "" = disabled. */
+  rescueModel: string;
+  /** True while a rescue-model turn is in flight. */
+  rescueActive: boolean;
+  /** Iterations during which anti-repetition sampling penalties are applied. */
+  penaltyTurnsRemaining: number;
+  /** Iteration of the last automatic compaction (stuck escalation). */
+  lastCompactIteration: number;
+  /** Timestamp of successful /loop prepare (GOAL_READY marker); 0 = not prepared. */
+  preparedAt: number;
+  lastAssistantFingerprints: string[];
+  lastAssistantSnippets: string[];
+  /** Longer recent assistant texts used for near-duplicate similarity detection. */
+  lastAssistantTexts: string[];
+  recentToolResults: ToolSnapshot[];
+  /** Consecutive turns in which the assistant made zero tool calls (narration only). */
+  turnsWithoutTools: number;
+  /** Tool calls observed since the current turn started; reset every agent_end. */
+  toolCallsThisTurn: number;
+  consecutiveStuckCount: number;
+  interventionCount: number;
+  consecutiveErrorCount: number;
+  totalErrorCount: number;
+  doneSignalCount: number;
+  blockedSignalCount: number;
+  lastStateChangeIteration: number;
+  status: "running" | "stuck" | "retrying" | "paused" | "completed" | "stopped" | "preparing";
+  lastNotice: string;
+}
+
+function defaultState(): LoopState {
+  return {
+    active: false,
+    description: "",
+    completionCriteria: "",
+    startTime: 0,
+    iterationCount: 0,
+    maxIterations: 0,
+    untilDone: false,
+    delaySeconds: 0,
+    checkCommand: "",
+    checkTimeoutSeconds: 120,
+    bestScoreIteration: 0,
+    checkFailStreak: 0,
+    lastCheckOutput: "",
+    goalFile: "GOAL.md",
+    loopModel: "",
+    rescueModel: "",
+    rescueActive: false,
+    penaltyTurnsRemaining: 0,
+    lastCompactIteration: 0,
+    preparedAt: 0,
+    lastAssistantFingerprints: [],
+    lastAssistantSnippets: [],
+    lastAssistantTexts: [],
+    recentToolResults: [],
+    turnsWithoutTools: 0,
+    toolCallsThisTurn: 0,
+    consecutiveStuckCount: 0,
+    interventionCount: 0,
+    consecutiveErrorCount: 0,
+    totalErrorCount: 0,
+    doneSignalCount: 0,
+    blockedSignalCount: 0,
+    lastStateChangeIteration: 0,
+    status: "stopped",
+    lastNotice: "",
+  };
+}
+
+let state: LoopState = defaultState();
+let pendingTimer: ReturnType<typeof setTimeout> | undefined;
+/** Set when we abort a streaming response due to degenerate repetition; consumed in agent_end. */
+let degenerateAbortPending = false;
+/** Stream position of the last degeneration check (throttle). */
+let lastDegenerateCheckLength = 0;
+
+function clearPendingTimer(): void {
+  if (pendingTimer) {
+    clearTimeout(pendingTimer);
+    pendingTimer = undefined;
+  }
+}
+
+function normalizeText(text: string): string {
+  return text
+    .replace(/\x1b\[[0-9;]*m/g, "")
+    .replace(/\s+/g, " ")
+    .trim()
+    .toLowerCase();
+}
+
+function fingerprint(text: string): string {
+  return createHash("sha256").update(normalizeText(text).slice(0, 4_000)).digest("hex").slice(0, 16);
+}
+
+/** Normalizes text for similarity: lowercased, whitespace collapsed, digits masked (iteration counters, file numbers …). */
+function stripVolatile(text: string): string {
+  return normalizeText(text).replace(/\d+/g, "#");
+}
+
+function wordShingles(text: string, n = 3): Set<string> {
+  const words = stripVolatile(text).split(" ").filter(Boolean);
+  const set = new Set<string>();
+  if (words.length < n) {
+    if (words.length > 0) set.add(words.join(" "));
+    return set;
+  }
+  for (let i = 0; i <= words.length - n; i++) set.add(words.slice(i, i + n).join(" "));
+  return set;
+}
+
+/** Jaccard similarity of word trigrams; 1 = identical, 0 = disjoint. */
+function textSimilarity(a: string, b: string): number {
+  const setA = wordShingles(a);
+  const setB = wordShingles(b);
+  if (setA.size === 0 || setB.size === 0) return 0;
+  let intersection = 0;
+  for (const shingle of setA) if (setB.has(shingle)) intersection++;
+  return intersection / (setA.size + setB.size - intersection);
+}
+
+interface DegenerateInfo {
+  repeats: number;
+  sentence: string;
+}
+
+/** Detects one sentence dominating a response ("Let me continue with improvements. …" × 40). */
+function degenerateRepetition(text: string, minRepeats: number): DegenerateInfo | undefined {
+  const normalized = stripVolatile(text);
+  if (normalized.length < 150) return undefined;
+  const parts = normalized
+    .split(/(?<=[.!?])\s+|\n+/)
+    .map((part) => part.trim())
+    .filter((part) => part.length >= 15);
+  if (parts.length < minRepeats) return undefined;
+  const counts = new Map<string, number>();
+  for (const part of parts) counts.set(part, (counts.get(part) ?? 0) + 1);
+  let sentence = "";
+  let repeats = 0;
+  for (const [part, count] of counts) {
+    if (count > repeats) {
+      sentence = part;
+      repeats = count;
+    }
+  }
+  if (repeats >= minRepeats && repeats / parts.length >= 0.5) return { repeats, sentence };
+  return undefined;
+}
+
+/** Truncates a degenerate response after the first repetition so the garbage never reinforces itself in context. */
+function sanitizeDegenerateText(text: string): string | undefined {
+  const info = degenerateRepetition(text, DEGENERATE_REPEATS);
+  if (!info) return undefined;
+  // Cut roughly after the first ~2 occurrences of the repeated content.
+  const keepLength = Math.max(200, Math.min(text.length, Math.ceil((text.length / info.repeats) * 2)));
+  return (
+    `${text.slice(0, keepLength).trimEnd()}\n\n` +
+    `[loop: degenerate repetition truncated — the same sentence repeated ${info.repeats}×. Do not continue this pattern.]`
+  );
+}
+
+/** Replaces the text content of a message, preserving non-text parts (e.g. thinking). */
+function replaceMessageText(message: { content?: unknown }, newText: string): unknown {
+  const content = message.content;
+  if (typeof content === "string") return { ...message, content: newText };
+  if (Array.isArray(content)) {
+    let replaced = false;
+    const parts = content
+      .map((part) => {
+        if (part && typeof part === "object" && (part as { type?: string }).type === "text") {
+          if (replaced) return undefined;
+          replaced = true;
+          return { ...(part as object), text: newText };
+        }
+        return part;
+      })
+      .filter((part) => part !== undefined);
+    if (!replaced) parts.push({ type: "text", text: newText });
+    return { ...message, content: parts };
+  }
+  return { ...message, content: newText };
+}
+
+/** Openings of recent responses; injected as banned phrases during hard-reset escalation. */
+function bannedOpenings(): string {
+  const openings = new Set<string>();
+  for (const snip of state.lastAssistantSnippets.slice(-3)) {
+    const words = snip.split(/\s+/).slice(0, 6).join(" ");
+    if (words) openings.add(`"${words}…"`);
+  }
+  return [...openings].join(", ") || "-";
+}
+
+function snippet(text: string, limit = MAX_STORED_TEXT): string {
+  const normalized = text.replace(/\s+/g, " ").trim();
+  return normalized.length <= limit ? normalized : `${normalized.slice(0, limit)}…`;
+}
+
+function contentToText(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((part) => {
+        if (typeof part === "string") return part;
+        if (part && typeof part === "object" && "text" in part && typeof (part as { text?: unknown }).text === "string") {
+          return (part as { text: string }).text;
+        }
+        return "";
+      })
+      .filter(Boolean)
+      .join("\n");
+  }
+  if (content && typeof content === "object" && "text" in content && typeof (content as { text?: unknown }).text === "string") {
+    return (content as { text: string }).text;
+  }
+  return "";
+}
+
+function messageToText(message: unknown): string {
+  if (!message || typeof message !== "object") return "";
+  return contentToText((message as { content?: unknown }).content);
+}
+
+function pushLimited<T>(items: T[], item: T, max: number): void {
+  items.push(item);
+  while (items.length > max) items.shift();
+}
+
+function hasStateChange(toolName: string, text: string, isError: boolean): boolean {
+  if (isError) return false;
+  if (["write", "edit"].includes(toolName)) return true;
+  return /\b(written|edited|changed|updated|created|deleted|renamed|committed|fixed|successfully|passed|installed)\b/i.test(text);
+}
+
+function recordToolResult(toolName: string, text: string, isError: boolean): void {
+  pushLimited(
+    state.recentToolResults,
+    {
+      tool: toolName,
+      fingerprint: fingerprint(text),
+      snippet: snippet(text),
+      isError,
+      time: Date.now(),
+    },
+    10,
+  );
+
+  if (hasStateChange(toolName, text, isError)) {
+    state.lastStateChangeIteration = state.iterationCount + 1;
+  }
+}
+
+function restoreState(ctx: ExtensionContext): void {
+  const entries = ctx.sessionManager.getEntries();
+  const restored = [...entries]
+    .reverse()
+    .find((entry) => entry.type === "custom" && (entry as { customType?: string }).customType === STATE_ENTRY_TYPE) as
+    | { data?: Partial<LoopState> }
+    | undefined;
+
+  state = { ...defaultState(), ...(restored?.data ?? {}) };
+}
+
+function persistState(pi: ExtensionAPI): void {
+  pi.appendEntry(STATE_ENTRY_TYPE, {
+    ...state,
+    lastAssistantFingerprints: state.lastAssistantFingerprints.slice(-8),
+    lastAssistantSnippets: state.lastAssistantSnippets.slice(-5),
+    lastAssistantTexts: state.lastAssistantTexts.slice(-3),
+    recentToolResults: state.recentToolResults.slice(-10),
+  });
+}
+
+interface StartArgs {
+  description: string;
+  criteria: string;
+  maxIterations: number;
+  untilDone: boolean;
+  delaySeconds: number;
+  checkCommand: string;
+  checkTimeoutSeconds: number;
+  model: string;
+  rescueModel: string;
+  goalFile: string;
+}
+
+function extractCheckCommand(text: string): { rest: string; checkCommand: string } {
+  const match = text.match(/--check(?:=|\s+)(?:"([^"]*)"|'([^']*)'|(\S+))/);
+  if (!match || match.index === undefined) return { rest: text, checkCommand: "" };
+  const checkCommand = (match[1] ?? match[2] ?? match[3] ?? "").trim();
+  const rest = `${text.slice(0, match.index)} ${text.slice(match.index + match[0].length)}`.trim();
+  return { rest, checkCommand };
+}
+
+function parseStartArgs(args: string): StartArgs {
+  const { rest, checkCommand } = extractCheckCommand(args.trim());
+  const tokens = rest.split(/\s+/);
+  let maxIterations = 0;
+  let untilDone = false;
+  let delaySeconds = 0;
+  let checkTimeoutSeconds = 120;
+  let model = "";
+  let rescueModel = "";
+  let goalFile = "";
+  const kept: string[] = [];
+
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (token === "--max" && tokens[i + 1]) {
+      maxIterations = Math.max(0, Number.parseInt(tokens[++i], 10) || 0);
+    } else if (token.startsWith("--max=")) {
+      maxIterations = Math.max(0, Number.parseInt(token.slice("--max=".length), 10) || 0);
+    } else if (token === "--delay" && tokens[i + 1]) {
+      delaySeconds = Math.max(0, Number.parseInt(tokens[++i], 10) || 0);
+    } else if (token.startsWith("--delay=")) {
+      delaySeconds = Math.max(0, Number.parseInt(token.slice("--delay=".length), 10) || 0);
+    } else if (token === "--rescue-model" && tokens[i + 1]) {
+      rescueModel = tokens[++i];
+    } else if (token.startsWith("--rescue-model=")) {
+      rescueModel = token.slice("--rescue-model=".length);
+    } else if (token === "--model" && tokens[i + 1]) {
+      model = tokens[++i];
+    } else if (token.startsWith("--model=")) {
+      model = token.slice("--model=".length);
+    } else if ((token === "--file" || token === "--goal-file") && tokens[i + 1]) {
+      goalFile = tokens[++i];
+    } else if (token.startsWith("--file=")) {
+      goalFile = token.slice("--file=".length);
+    } else if (token === "--check-timeout" && tokens[i + 1]) {
+      checkTimeoutSeconds = Math.max(1, Number.parseInt(tokens[++i], 10) || 120);
+    } else if (token.startsWith("--check-timeout=")) {
+      checkTimeoutSeconds = Math.max(1, Number.parseInt(token.slice("--check-timeout=".length), 10) || 120);
+    } else if (token === "--until-done") {
+      untilDone = true;
+    } else {
+      kept.push(token);
+    }
+  }
+
+  const text = kept.join(" ").trim();
+  const match = text.match(/^(.*?)(?:\bDone when\b\s*:?\s*)(.*)$/i);
+  const description = (match?.[1] ?? text).trim().replace(/[.\s]+$/, "");
+  const criteria = (match?.[2] ?? "").trim();
+  return { description, criteria, maxIterations, untilDone, delaySeconds, checkCommand, checkTimeoutSeconds, model, rescueModel, goalFile };
+}
+
+function resolveModel(ctx: ExtensionContext, spec: string) {
+  const slash = spec.indexOf("/");
+  if (slash > 0) {
+    const found = ctx.modelRegistry.find(spec.slice(0, slash), spec.slice(slash + 1));
+    if (found) return found;
+  }
+  const all = ctx.modelRegistry.getAll();
+  const lower = spec.toLowerCase();
+  return (
+    all.find((m) => m.id.toLowerCase() === lower) ??
+    all.find((m) => `${m.provider}/${m.id}`.toLowerCase() === lower) ??
+    all.find((m) => m.id.toLowerCase().includes(lower)) ??
+    all.find((m) => `${m.provider}/${m.id}`.toLowerCase().includes(lower))
+  );
+}
+
+async function switchModel(pi: ExtensionAPI, ctx: ExtensionContext, spec: string): Promise<boolean> {
+  const model = resolveModel(ctx, spec);
+  if (!model) {
+    ctx.ui.notify(`Loop: model not found: ${spec} (try provider/id, e.g. anthropic/claude-sonnet-4-5)`, "error");
+    return false;
+  }
+  const ok = await pi.setModel(model);
+  if (!ok) {
+    ctx.ui.notify(`Loop: no API key configured for ${model.provider}/${model.id}`, "error");
+    return false;
+  }
+  ctx.ui.notify(`Loop: model set to ${model.provider}/${model.id}`, "info");
+  return true;
+}
+
+/** Slightly varied continue prompts: identical repeated prompts encourage identical repeated answers. */
+const CONTINUE_DIRECTIVES = [
+  "Continue loop mode.",
+  "Continue: execute the next concrete progress batch.",
+  "Keep going — pick the next step from your plan and do it now.",
+  "Proceed with the next focused unit of work on the goal.",
+  "Advance the goal with one concrete, verifiable change.",
+];
+
+const STUCK_STRATEGIES = [
+  "Step back: list 3 genuinely different approaches in one line each, then execute the most promising one immediately.",
+  "Switch to a different subtask of the goal that you have not touched in the last few iterations.",
+  "Create or update PROGRESS.md with: current state, what was tried, what failed, next 3 steps. Then execute step 1.",
+  "Run the build and/or test suite, pick exactly one failure or warning, and fix only that.",
+  "Review recent changes (git diff / git log), verify correctness, and fix any issue you find.",
+];
+
+function iterationLabel(): string {
+  const next = state.iterationCount + 1;
+  return state.maxIterations > 0 ? `${next}/${state.maxIterations}` : `${next}/∞`;
+}
+
+function kindDirective(kind: TurnKind): string {
+  switch (kind) {
+    case "start":
+      return state.preparedAt > 0
+        ? `Start loop mode. First read ${state.goalFile} to load the full specification, then do the first concrete progress batch.`
+        : "Start loop mode. Begin with a short plan (max 5 bullets) if useful, then do the first concrete progress batch.";
+    case "stuck": {
+      const strategy = STUCK_STRATEGIES[state.interventionCount % STUCK_STRATEGIES.length];
+      const escalation =
+        state.consecutiveStuckCount >= HARD_RESET_AFTER
+          ? ` HARD RESET (stuck intervention #${state.consecutiveStuckCount} in a row): forget your previous phrasing entirely. Banned openings: ${bannedOpenings()}. Your FIRST action this turn must be a tool call (read/bash/edit/write) that produces new information or a concrete file change — zero preamble text before it.`
+          : "";
+      return `Stuck intervention (${state.lastNotice}). You are repeating yourself. Do NOT repeat the previous answer, command, or question.${escalation} ${strategy}`;
+    }
+    case "recover":
+      return "The previous turn failed with a model/provider error and was retried automatically. Briefly re-establish your bearings (check files/tests as needed), then continue with the next concrete progress batch. Do not restart from scratch.";
+    case "improve":
+      return (
+        "You reported LOOP_DONE, but this loop runs in endless improvement mode. Work backlog-driven: open IMPROVEMENTS.md (create it if missing) — a checklist of concrete improvement items, each with affected file paths and a one-line acceptance criterion. " +
+        "If fewer than 3 open items remain, first inspect the codebase with tools and add new specific items. Vague items without file paths (e.g. \"add support for other platforms\") are forbidden. " +
+        "Then take the TOP open item, implement it now, and mark it done."
+      );
+    case "unblock":
+      return "You reported LOOP_BLOCKED, but no operator is available. Make the most reasonable assumption, record it in ASSUMPTIONS.md (create if missing), and continue working toward the goal. Never wait for a human.";
+    case "audit":
+      return `No concrete file/system changes were detected in the last ${NO_PROGRESS_WINDOW} iterations. Stop analyzing and produce a tangible artifact this turn: a file change, a passing test, a fixed bug, or a committed improvement.`;
+    case "resume":
+      return "The loop was resumed. Briefly check the current project state (files, tests, PROGRESS.md if present), then continue with the next concrete progress batch.";
+    case "regression":
+      return `Goal check regression: the score dropped to ${state.lastCheckScore} (best so far ${state.bestCheckScore} at iteration ${state.bestScoreIteration}). A recent change made things worse. Inspect recent changes (git diff / git log), find and fix the regression before doing anything else. Check output: ${state.lastCheckOutput}`;
+    case "check_failed":
+      return `You reported LOOP_DONE, but the goal check command still fails (streak ${state.checkFailStreak}). Completion is decided by the check, not by your claim. Fix exactly what the check reports. Check output: ${state.lastCheckOutput}`;
+    case "rescue":
+      return (
+        `RESCUE TURN: you are a stronger model called in because the loop model was stuck ${state.consecutiveStuckCount}x in a row (${state.lastNotice}). ` +
+        `Do now: 1) inspect the project state (git status/diff, PROGRESS.md, ${state.goalFile} if present); 2) fix or finish ONE concrete thing; ` +
+        `3) rewrite PROGRESS.md: current state, what keeps failing, the next 3 unambiguous steps with exact file paths; ` +
+        `4) update the IMPROVEMENTS.md backlog with concrete items (file paths + acceptance criterion). ` +
+        `End with one line "NEXT: <exact instruction for the next turn>". After this turn the loop returns to the regular model.`
+      );
+    default:
+      return CONTINUE_DIRECTIVES[Math.floor(Math.random() * CONTINUE_DIRECTIVES.length)];
+  }
+}
+
+function loopInstructions(kind: TurnKind): string {
+  const doneRule = state.untilDone
+    ? state.checkCommand
+      ? "- Completion is decided by the goal check command (exit code 0), not by your claim. Work until the check passes; you may still say \"LOOP_DONE:\" once it does."
+      : '- If the completion criteria are fully met, start your final message with "LOOP_DONE:".'
+    : '- Endless mode: if the core goal appears complete, say "LOOP_DONE: <one-line summary>" — the loop will then continue with improvement work (features, tests, bug fixes, refactoring, docs). Never stop on your own.';
+
+  const checkLine = state.checkCommand
+    ? `Goal check: \`${state.checkCommand}\` → ${
+        state.lastCheckPassed === undefined
+          ? "not run yet"
+          : state.lastCheckPassed
+            ? "PASSING"
+            : `FAILING (streak ${state.checkFailStreak})`
+      }${state.lastCheckScore !== undefined ? ` · score ${state.lastCheckScore} (best ${state.bestCheckScore} @ iteration ${state.bestScoreIteration})` : ""}\n`
+    : "";
+
+  return (
+    `${kindDirective(kind)}\n\n` +
+    `Goal: ${state.description}\n` +
+    `Completion criteria: ${state.completionCriteria || "continuous improvement until the operator stops the loop"}\n` +
+    (state.preparedAt > 0 ? `Specification: ${state.goalFile} — read it whenever you lose track of the plan.\n` : "") +
+    `Iteration: ${iterationLabel()}\n` +
+    `${checkLine}\n` +
+    `Rules:\n` +
+    `- Do exactly one concrete progress batch, then stop this turn.\n` +
+    `- Prefer tools and file changes over long explanations.\n` +
+    `- Never respond with narration only: every turn must include at least one tool call. Do not claim something "already exists" — verify it with a tool and then produce the next concrete change.\n` +
+    `- Hard output budget: max 1,200 characters; no large code blocks, logs, full diffs, or repeated context.\n` +
+    `${doneRule}\n` +
+    `- Never wait for a human. If information is missing, make the most reasonable assumption, document it in ASSUMPTIONS.md, and continue. Use "LOOP_BLOCKED:" only for truly impossible external barriers (e.g., missing credentials) — the loop will still continue with assumptions.\n` +
+    `- Otherwise briefly say what changed and let the loop continue.`
+  );
+}
+
+function sendLoopTurn(pi: ExtensionAPI, kind: TurnKind, ctx?: ExtensionContext): void {
+  const idle = ctx?.isIdle() ?? false;
+  const options = idle
+    ? { triggerTurn: true as const }
+    : { triggerTurn: true as const, deliverAs: "followUp" as const };
+
+  pi.sendMessage(
+    {
+      customType: MESSAGE_TYPE,
+      content: loopInstructions(kind),
+      display: true,
+      details: { kind, iteration: state.iterationCount + 1 },
+    },
+    options,
+  );
+}
+
+function scheduleLoopTurn(pi: ExtensionAPI, kind: TurnKind, delayMs: number, ctx?: ExtensionContext): void {
+  clearPendingTimer();
+  if (delayMs <= 0) {
+    sendLoopTurn(pi, kind, ctx);
+    return;
+  }
+  pendingTimer = setTimeout(() => {
+    pendingTimer = undefined;
+    if (!state.active) return;
+    // No ctx available in the timer; followUp + triggerTurn is safe both idle and busy.
+    sendLoopTurn(pi, kind);
+  }, delayMs);
+}
+
+function backoffSeconds(): number {
+  const exponent = Math.min(Math.max(state.consecutiveErrorCount - 1, 0), 6);
+  return Math.min(MAX_BACKOFF_SECONDS, BASE_BACKOFF_SECONDS * 2 ** exponent);
+}
+
+/** Appends one JSONL entry per loop event; used by /loop stats. Never throws. */
+function logIteration(event: string, extra: Record<string, unknown> = {}): void {
+  try {
+    const entry = {
+      ts: new Date().toISOString(),
+      iteration: state.iterationCount,
+      event,
+      model: state.rescueActive ? state.rescueModel : state.loopModel || undefined,
+      score: state.lastCheckScore,
+      checkPassed: state.lastCheckPassed,
+      stuckStreak: state.consecutiveStuckCount,
+      notice: state.lastNotice || undefined,
+      ...extra,
+    };
+    appendFileSync(LOG_FILE, `${JSON.stringify(entry)}\n`);
+  } catch {
+    // Logging must never break the loop.
+  }
+}
+
+function statsText(): string {
+  let raw: string;
+  try {
+    raw = readFileSync(LOG_FILE, "utf8");
+  } catch {
+    return `No loop log found (${LOG_FILE}).`;
+  }
+  interface Entry {
+    ts: string;
+    event: string;
+    score?: number;
+  }
+  const all = raw
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => {
+      try {
+        return JSON.parse(line) as Entry;
+      } catch {
+        return undefined;
+      }
+    })
+    .filter((entry): entry is Entry => Boolean(entry));
+  if (all.length === 0) return `Loop log is empty (${LOG_FILE}).`;
+  const current = state.startTime > 0 ? all.filter((entry) => Date.parse(entry.ts) >= state.startTime) : [];
+  const scope = current.length > 0 ? current : all;
+  const label = current.length > 0 ? "current run" : "all runs";
+  const counts = new Map<string, number>();
+  for (const entry of scope) counts.set(entry.event, (counts.get(entry.event) ?? 0) + 1);
+  const eventSummary = [...counts.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .map(([key, value]) => `${key} ${value}`)
+    .join(", ");
+  const scores = scope.map((entry) => entry.score).filter((score): score is number => typeof score === "number");
+  const spanMs = Date.parse(scope[scope.length - 1].ts) - Date.parse(scope[0].ts);
+  const perHour = spanMs > 60_000 ? ((counts.get("continue") ?? 0) / (spanMs / 3_600_000)).toFixed(1) : "-";
+  const interventions =
+    (counts.get("stuck") ?? 0) +
+    (counts.get("audit") ?? 0) +
+    (counts.get("regression") ?? 0) +
+    (counts.get("rescue_start") ?? 0) +
+    (counts.get("compact") ?? 0);
+  return [
+    `Loop stats (${label}, ${scope.length} entries, ${LOG_FILE}):`,
+    `Events: ${eventSummary}`,
+    `Interventions: ${interventions} (rescue ${counts.get("rescue_start") ?? 0}, compact ${counts.get("compact") ?? 0})`,
+    `Productive iterations/h: ${perHour}`,
+    scores.length > 0 ? `Score: first ${scores[0]}, best ${Math.max(...scores)}, last ${scores[scores.length - 1]}` : "Score: -",
+  ].join("\n");
+}
+
+interface CheckOutcome {
+  passed: boolean;
+  score?: number;
+  output: string;
+  execFailed: boolean;
+}
+
+async function runGoalCheck(pi: ExtensionAPI): Promise<CheckOutcome> {
+  try {
+    const result = await pi.exec("bash", ["-lc", state.checkCommand], { timeout: state.checkTimeoutSeconds * 1000 });
+    const output = `${result.stdout ?? ""}\n${result.stderr ?? ""}`.trim();
+    const scoreMatches = [...output.matchAll(/SCORE:\s*(-?\d+(?:\.\d+)?)/gi)];
+    const score = scoreMatches.length > 0 ? Number.parseFloat(scoreMatches[scoreMatches.length - 1][1]) : undefined;
+    return { passed: result.code === 0, score, output: snippet(output, 400), execFailed: false };
+  } catch (error) {
+    return { passed: false, score: undefined, output: snippet(String(error), 200), execFailed: true };
+  }
+}
+
+/** Updates check state; returns true when the score regressed vs. the previous run. */
+function applyCheckOutcome(outcome: CheckOutcome): boolean {
+  const previousScore = state.lastCheckScore;
+  state.lastCheckPassed = outcome.passed;
+  state.lastCheckOutput = outcome.output;
+  state.checkFailStreak = outcome.passed ? 0 : state.checkFailStreak + 1;
+  if (outcome.score !== undefined) {
+    state.lastCheckScore = outcome.score;
+    if (state.bestCheckScore === undefined || outcome.score > state.bestCheckScore) {
+      state.bestCheckScore = outcome.score;
+      state.bestScoreIteration = state.iterationCount;
+      // A better score is measurable progress; feeds the no-progress audit.
+      state.lastStateChangeIteration = state.iterationCount;
+    }
+  }
+  return outcome.score !== undefined && previousScore !== undefined && outcome.score < previousScore;
+}
+
+function detectStuck(lastAssistantText: string): string | undefined {
+  const prints = state.lastAssistantFingerprints;
+
+  // Degenerate generation: one sentence repeated many times within a single response.
+  const degenerate = degenerateRepetition(lastAssistantText, DEGENERATE_REPEATS);
+  if (degenerate) {
+    return `response degenerated: same sentence repeated ${degenerate.repeats}× ("${snippet(degenerate.sentence, 60)}")`;
+  }
+
+  // Narration-only loops: several turns without a single tool call.
+  if (state.turnsWithoutTools >= MAX_TOOLLESS_TURNS) {
+    return `no tool usage for ${state.turnsWithoutTools} turns (narration only)`;
+  }
+
+  const lastTwo = prints.slice(-2);
+  if (lastTwo.length === 2 && lastTwo[0] === lastTwo[1] && normalizeText(lastAssistantText).length > 80) {
+    return "assistant repeated the same response";
+  }
+
+  const lastThree = prints.slice(-3);
+  if (lastThree.length === 3 && lastThree.every((p) => p === lastThree[0]) && normalizeText(lastAssistantText).length > 0) {
+    return "assistant repeated the same response three times";
+  }
+
+  // Near-duplicate responses: exact fingerprints miss slight rephrasings ("…continue with improvements on X/Y").
+  const texts = state.lastAssistantTexts;
+  const previousText = texts.length >= 2 ? texts[texts.length - 2] : undefined;
+  if (previousText && normalizeText(lastAssistantText).length > 60) {
+    const similarity = textSimilarity(lastAssistantText, previousText);
+    if (similarity >= SIMILARITY_THRESHOLD) {
+      return `assistant response ~${Math.round(similarity * 100)}% similar to previous`;
+    }
+  }
+
+  // Alternating repetition (A-B-A-B…): same fingerprint several times in the recent window.
+  const currentPrint = prints[prints.length - 1];
+  if (currentPrint && prints.filter((p) => p === currentPrint).length >= REPEAT_WINDOW_COUNT) {
+    return `same response repeated ${REPEAT_WINDOW_COUNT}+ times in recent turns`;
+  }
+
+  const recentTools = state.recentToolResults.slice(-3);
+  if (
+    recentTools.length === 3 &&
+    recentTools.every((result) => result.tool === recentTools[0].tool && result.fingerprint === recentTools[0].fingerprint)
+  ) {
+    return recentTools.every((result) => result.isError)
+      ? `same ${recentTools[0].tool} error repeated`
+      : `same ${recentTools[0].tool} result repeated`;
+  }
+
+  const asksQuestion = /\?\s*$/.test(lastAssistantText.trim());
+  const lastSnippets = state.lastAssistantSnippets.slice(-2);
+  if (asksQuestion && lastSnippets.length === 2 && lastSnippets[0] === lastSnippets[1]) {
+    return "same question repeated";
+  }
+
+  return undefined;
+}
+
+function formatElapsed(): string {
+  if (state.startTime <= 0) return "0m";
+  let seconds = Math.round((Date.now() - state.startTime) / 1000);
+  const days = Math.floor(seconds / 86_400);
+  seconds -= days * 86_400;
+  const hours = Math.floor(seconds / 3_600);
+  seconds -= hours * 3_600;
+  const minutes = Math.floor(seconds / 60);
+  const parts: string[] = [];
+  if (days) parts.push(`${days}d`);
+  if (hours) parts.push(`${hours}h`);
+  parts.push(`${minutes}m`);
+  return parts.join(" ");
+}
+
+function statusBarText(): string {
+  const iterations = state.maxIterations > 0 ? `${state.iterationCount}/${state.maxIterations}` : `${state.iterationCount}/∞`;
+  const check =
+    state.lastCheckScore !== undefined
+      ? ` · score ${state.lastCheckScore}`
+      : state.lastCheckPassed !== undefined
+        ? ` · check ${state.lastCheckPassed ? "✓" : "✗"}`
+        : "";
+  return `Loop ${iterations} · ${formatElapsed()} · err ${state.totalErrorCount}${check}: ${snippet(state.description, 40)}`;
+}
+
+function statusText(ctx: ExtensionContext): string {
+  return [
+    `Active: ${state.active}`,
+    `Status: ${state.status}`,
+    `Goal: ${state.description || "-"}`,
+    `Criteria: ${state.completionCriteria || "- (endless improvement)"}`,
+    `Mode: ${state.untilDone ? "until-done" : "endless"}`,
+    `Iterations: ${state.iterationCount}${state.maxIterations > 0 ? `/${state.maxIterations}` : "/∞"}`,
+    `Delay: ${state.delaySeconds}s`,
+    `Check: ${state.checkCommand ? `${state.checkCommand} (timeout ${state.checkTimeoutSeconds}s)` : "-"}`,
+    `Check status: ${
+      state.lastCheckPassed === undefined ? "-" : state.lastCheckPassed ? "passing" : `failing (streak ${state.checkFailStreak})`
+    }${state.lastCheckScore !== undefined ? `, score ${state.lastCheckScore} (best ${state.bestCheckScore} @ iter ${state.bestScoreIteration})` : ""}`,
+    `Goal file: ${state.goalFile}${state.preparedAt > 0 ? " (prepared)" : " (not prepared)"}`,
+    `Loop model: ${state.loopModel || "- (current model)"}`,
+    `Rescue model: ${state.rescueModel || "-"}${state.rescueActive ? " (rescue turn in flight)" : ""}`,
+    `Elapsed: ${formatElapsed()}`,
+    `Errors: ${state.totalErrorCount} total, ${state.consecutiveErrorCount} consecutive`,
+    `Interventions: ${state.interventionCount} (stuck streak: ${state.consecutiveStuckCount})`,
+    `Done signals: ${state.doneSignalCount}, blocked signals: ${state.blockedSignalCount}`,
+    `Last notice: ${state.lastNotice || "-"}`,
+    `Session entries: ${ctx.sessionManager.getEntries().length}`,
+  ].join("\n");
+}
+
+function applyGoalConfig(parsed: StartArgs): void {
+  // Re-issuing the same goal (e.g. to tweak flags after /loop prepare) keeps the prepared spec.
+  const preservedPreparedAt = state.description === parsed.description ? state.preparedAt : 0;
+  state = {
+    ...defaultState(),
+    description: parsed.description,
+    completionCriteria: parsed.criteria,
+    maxIterations: parsed.maxIterations,
+    untilDone: parsed.untilDone,
+    delaySeconds: parsed.delaySeconds,
+    checkCommand: parsed.checkCommand,
+    checkTimeoutSeconds: parsed.checkTimeoutSeconds,
+    goalFile: parsed.goalFile || "GOAL.md",
+    loopModel: parsed.model,
+    rescueModel: parsed.rescueModel,
+    preparedAt: preservedPreparedAt,
+    status: "stopped",
+  };
+}
+
+function goalSummaryText(): string {
+  return [
+    `Goal: ${state.description || "-"}`,
+    `Criteria: ${state.completionCriteria || "- (endless improvement)"}`,
+    `Mode: ${state.untilDone ? "until-done" : "endless"}`,
+    `Max iterations: ${state.maxIterations > 0 ? state.maxIterations : "∞"}`,
+    `Delay: ${state.delaySeconds}s`,
+    `Check: ${state.checkCommand || "-"}`,
+    `Goal file: ${state.goalFile}`,
+    `Prepared: ${state.preparedAt > 0 ? new Date(state.preparedAt).toISOString() : "no (optional: /loop prepare [--model M])"}`,
+    `Loop model: ${state.loopModel || "- (current model)"}`,
+    `Rescue model: ${state.rescueModel || "-"}`,
+  ].join("\n");
+}
+
+function prepareInstructions(): string {
+  return (
+    `Prepare the loop goal specification. Do NOT start implementing the goal itself in this turn.\n\n` +
+    `Goal: ${state.description}\n` +
+    `Completion criteria: ${state.completionCriteria || "continuous improvement until the operator stops the loop"}\n\n` +
+    `Tasks for this turn:\n` +
+    `1. Inspect the current project state (files, README, tests) if one exists.\n` +
+    `2. Write ${state.goalFile} containing: refined objective, scope & non-goals, measurable completion criteria, a milestone roadmap of small steps, quality standards (tests, docs, git commits), and explicit assumptions.\n` +
+    `3. If the goal is objectively checkable, create a goal-check script (e.g. check.sh: exit 0 = criteria met, print "SCORE: <n>", higher = better) and reference it in ${state.goalFile}.\n` +
+    `4. Keep ${state.goalFile} under ~200 lines, concrete and unambiguous — it must guide another (possibly weaker) model through a long unattended run.\n\n` +
+    `End your final message with "GOAL_READY: <one-line summary>" and, if you created a check script, the exact --check command to use.`
+  );
+}
+
+/** Shared stuck handling with escalation ladder: penalties → rescue model → compaction → rotating strategy. */
+async function interveneStuck(pi: ExtensionAPI, ctx: ExtensionContext, reason: string): Promise<void> {
+  state.consecutiveStuckCount++;
+  state.interventionCount++;
+  state.status = "stuck";
+  state.lastNotice = reason;
+  state.turnsWithoutTools = 0;
+  // Fight repetition at the sampling level too (applied via before_provider_request).
+  state.penaltyTurnsRemaining = PENALTY_TURNS;
+
+  // Escalation 1: hand the situation to a stronger rescue model for one turn.
+  if (state.rescueModel && !state.rescueActive && state.consecutiveStuckCount >= RESCUE_AFTER) {
+    if (await switchModel(pi, ctx, state.rescueModel)) {
+      state.rescueActive = true;
+      persistState(pi);
+      logIteration("rescue_start", { reason });
+      ctx.ui.notify(`Loop: stuck ${state.consecutiveStuckCount}x — rescue turn with ${state.rescueModel}.`, "warning");
+      ctx.ui.setStatus("loop", `Loop rescue turn (stuck ${state.consecutiveStuckCount}x)`);
+      scheduleLoopTurn(pi, "rescue", 0, ctx);
+      return;
+    }
+  }
+
+  // Escalating pause between interventions to break tight garbage loops.
+  const delayMs = Math.min(60, 2 ** Math.min(state.consecutiveStuckCount, 6)) * 1000;
+
+  // Escalation 2: stubborn fixation — compact the context so the repeated pattern leaves the window.
+  if (state.consecutiveStuckCount >= COMPACT_AFTER && state.iterationCount - state.lastCompactIteration >= COMPACT_AFTER) {
+    state.lastCompactIteration = state.iterationCount;
+    persistState(pi);
+    logIteration("compact", { reason });
+    ctx.ui.notify(`Loop: stuck ${state.consecutiveStuckCount}x — compacting context to break the pattern.`, "warning");
+    ctx.compact({
+      customInstructions:
+        "Summarize the work so far concisely. Explicitly EXCLUDE repetitive filler sentences and repeated failed attempts; keep the goal, the current project state, and concrete next steps.",
+      onComplete: () => scheduleLoopTurn(pi, "stuck", 0),
+      onError: () => scheduleLoopTurn(pi, "stuck", delayMs),
+    });
+    return;
+  }
+
+  persistState(pi);
+  logIteration("stuck", { reason });
+  ctx.ui.notify(`Loop stuck (${state.consecutiveStuckCount}x): ${reason} — injecting new strategy.`, "warning");
+  ctx.ui.setStatus("loop", `Loop stuck ${state.consecutiveStuckCount}x — redirecting`);
+  if (!ctx.hasPendingMessages()) scheduleLoopTurn(pi, "stuck", delayMs, ctx);
+}
+
+function runLoop(pi: ExtensionAPI, ctx: ExtensionContext): void {
+  clearPendingTimer();
+  state.active = true;
+  state.startTime = Date.now();
+  state.iterationCount = 0;
+  state.consecutiveStuckCount = 0;
+  state.consecutiveErrorCount = 0;
+  state.totalErrorCount = 0;
+  state.interventionCount = 0;
+  state.doneSignalCount = 0;
+  state.blockedSignalCount = 0;
+  state.lastStateChangeIteration = 0;
+  state.lastAssistantFingerprints = [];
+  state.lastAssistantSnippets = [];
+  state.lastAssistantTexts = [];
+  state.recentToolResults = [];
+  state.turnsWithoutTools = 0;
+  state.toolCallsThisTurn = 0;
+  state.rescueActive = false;
+  state.penaltyTurnsRemaining = 0;
+  state.lastCompactIteration = 0;
+  state.status = "running";
+  state.lastNotice = "";
+
+  persistState(pi);
+  const mode = state.untilDone ? "until-done" : "endless (stop with /loop stop)";
+  ctx.ui.notify(`Loop active [${mode}]: ${state.description}`, "info");
+  ctx.ui.setStatus("loop", statusBarText());
+  sendLoopTurn(pi, "start", ctx);
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.registerCommand("loop", {
+    description:
+      "Loop mode: /loop goal <goal> → /loop prepare [--model M] → /loop run [--model M]; or /loop start <goal>; /loop status|stats|resume|stop|end",
+    handler: async (args: string, ctx) => {
+      const trimmed = args.trim();
+      const [subcommand = "status", ...rest] = trimmed.split(/\s+/);
+      const command = subcommand.toLowerCase();
+      const remainder = rest.join(" ").trim();
+
+      if (command === "start") {
+        if (!remainder) {
+          ctx.ui.notify(
+            'Usage: /loop start <goal[. Done when: criteria]> [--max N] [--delay S] [--check "CMD"] [--check-timeout S] [--model M] [--rescue-model M] [--until-done]',
+            "error",
+          );
+          return;
+        }
+        applyGoalConfig(parseStartArgs(remainder));
+        if (state.loopModel && !(await switchModel(pi, ctx, state.loopModel))) return;
+        runLoop(pi, ctx);
+        return;
+      }
+
+      if (command === "goal") {
+        if (!remainder) {
+          ctx.ui.notify(`Loop goal:\n${goalSummaryText()}`, "info");
+          return;
+        }
+        if (state.active) {
+          ctx.ui.notify("Loop is running. Use /loop stop first, then set a new goal.", "error");
+          return;
+        }
+        applyGoalConfig(parseStartArgs(remainder));
+        persistState(pi);
+        ctx.ui.notify(
+          `Goal set (not started):\n${goalSummaryText()}\n\nNext: /loop prepare [--model M] (optional), then /loop run [--model M].`,
+          "info",
+        );
+        return;
+      }
+
+      if (command === "prepare") {
+        if (!state.description) {
+          ctx.ui.notify("No goal set. Use /loop goal <goal> first.", "error");
+          return;
+        }
+        if (state.active) {
+          ctx.ui.notify("Loop is running. Use /loop stop first.", "error");
+          return;
+        }
+        const parsed = parseStartArgs(remainder);
+        if (parsed.goalFile) state.goalFile = parsed.goalFile;
+        if (parsed.model && !(await switchModel(pi, ctx, parsed.model))) return;
+        state.status = "preparing";
+        persistState(pi);
+        ctx.ui.notify(`Preparing goal specification in ${state.goalFile}… Review it when done, then /loop run [--model M].`, "info");
+        pi.sendMessage(
+          { customType: MESSAGE_TYPE, content: prepareInstructions(), display: true, details: { kind: "prepare" } },
+          { triggerTurn: true },
+        );
+        return;
+      }
+
+      if (command === "run") {
+        if (!state.description) {
+          ctx.ui.notify("No goal set. Use /loop goal <goal> first (or /loop start <goal> for one step).", "error");
+          return;
+        }
+        if (state.active) {
+          ctx.ui.notify("Loop is already running. Use /loop status to inspect it.", "error");
+          return;
+        }
+        const parsed = parseStartArgs(remainder);
+        if (parsed.model) state.loopModel = parsed.model;
+        if (parsed.rescueModel) state.rescueModel = parsed.rescueModel;
+        if (state.loopModel && !(await switchModel(pi, ctx, state.loopModel))) return;
+        runLoop(pi, ctx);
+        return;
+      }
+
+      if (command === "resume") {
+        if (!state.description) {
+          ctx.ui.notify("No loop to resume. Use /loop start <goal>.", "error");
+          return;
+        }
+        const parsed = parseStartArgs(remainder);
+        if (remainder.includes("--max")) state.maxIterations = parsed.maxIterations;
+        if (parsed.checkCommand) {
+          state.checkCommand = parsed.checkCommand;
+          state.checkTimeoutSeconds = parsed.checkTimeoutSeconds;
+        }
+        if (parsed.model) {
+          state.loopModel = parsed.model;
+          if (!(await switchModel(pi, ctx, parsed.model))) return;
+        }
+        if (parsed.rescueModel) state.rescueModel = parsed.rescueModel;
+        if (state.maxIterations > 0 && state.iterationCount >= state.maxIterations) {
+          state.maxIterations = 0;
+          ctx.ui.notify("Iteration cap was exhausted; resuming without a cap (endless).", "warning");
+        }
+        state.active = true;
+        state.status = "running";
+        state.consecutiveStuckCount = 0;
+        state.consecutiveErrorCount = 0;
+        state.rescueActive = false;
+        state.lastNotice = "Resumed by operator.";
+        persistState(pi);
+        ctx.ui.notify(`Loop resumed: ${state.description}`, "info");
+        ctx.ui.setStatus("loop", statusBarText());
+        sendLoopTurn(pi, "resume", ctx);
+        return;
+      }
+
+      if (command === "stop") {
+        clearPendingTimer();
+        state.active = false;
+        state.status = "stopped";
+        state.lastNotice = "Stopped by operator; state preserved.";
+        persistState(pi);
+        ctx.ui.notify("Loop stopped. Use /loop resume to continue, /loop start to replace, or /loop end to clear.", "info");
+        ctx.ui.setStatus("loop", "Loop stopped");
+        return;
+      }
+
+      if (command === "end" || command === "clear") {
+        clearPendingTimer();
+        state = defaultState();
+        persistState(pi);
+        ctx.ui.notify("Loop ended and state cleared.", "info");
+        ctx.ui.setStatus("loop", "Loop ended");
+        return;
+      }
+
+      if (command === "status") {
+        ctx.ui.notify(`Loop state:\n${statusText(ctx)}`, "info");
+        return;
+      }
+
+      if (command === "stats") {
+        ctx.ui.notify(statsText(), "info");
+        return;
+      }
+
+      if (command === "help") {
+        ctx.ui.notify(
+          "Workflow: /loop goal <goal> → /loop prepare [--model M] → /loop run [--model M]\n" +
+            '/loop goal <goal[. Done when: criteria]> [--max N] [--delay S] [--check "CMD"] [--check-timeout S] [--file GOAL.md] [--model M] [--rescue-model M] [--until-done] — set goal without starting\n' +
+            "/loop prepare [--model M] [--file F] — have a (strong) model write the goal spec + check script\n" +
+            "/loop run [--model M] — start the loop, optionally with a different model\n" +
+            "/loop start <goal> [flags] — goal + run in one step\n" +
+            '/loop resume [--max N] [--check "CMD"] [--model M] [--rescue-model M] | /loop status | /loop stats | /loop stop | /loop end\n' +
+            "--rescue-model M — stronger model that takes over for one turn after 3 stuck interventions in a row\n" +
+            "Default: endless — runs until /loop stop. --until-done stops when the goal check passes (or LOOP_DONE without check).\n" +
+            'Goal check: shell command, exit 0 = done criteria met, optional "SCORE: n" output for progress/regression tracking.\n' +
+            `Per-iteration JSONL log in ${LOG_FILE} — inspect with /loop stats.`,
+          "info",
+        );
+        return;
+      }
+
+      // Convenience: /loop <goal> starts a loop immediately.
+      applyGoalConfig(parseStartArgs(trimmed));
+      if (state.loopModel && !(await switchModel(pi, ctx, state.loopModel))) return;
+      runLoop(pi, ctx);
+    },
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    clearPendingTimer();
+    restoreState(ctx);
+    if (!state.active) return;
+
+    ctx.ui.setStatus("loop", statusBarText());
+
+    // Unattended operation: auto-resume an active loop after restart/reload.
+    if (["running", "stuck", "retrying"].includes(state.status)) {
+      state.rescueActive = false;
+      if (state.loopModel) {
+        const model = resolveModel(ctx, state.loopModel);
+        if (model) {
+          const ok = await pi.setModel(model);
+          if (!ok) ctx.ui.notify(`Loop: could not restore model ${state.loopModel} (no API key); using current model.`, "warning");
+        } else {
+          ctx.ui.notify(`Loop: stored model ${state.loopModel} not found; using current model.`, "warning");
+        }
+      }
+      ctx.ui.notify(`Loop auto-resuming in ${AUTO_RESUME_DELAY_MS / 1000}s: ${snippet(state.description, 80)} (stop with /loop stop)`, "info");
+      scheduleLoopTurn(pi, "resume", AUTO_RESUME_DELAY_MS);
+    }
+  });
+
+  pi.on("session_shutdown", async () => {
+    clearPendingTimer();
+  });
+
+  pi.on("before_agent_start", async (event) => {
+    if (!state.active) return;
+    const doneHint = state.untilDone
+      ? "use LOOP_DONE: when the completion criteria are fully met"
+      : "endless mode: after LOOP_DONE the loop continues with improvements, never stop on your own";
+    return {
+      systemPrompt:
+        `${event.systemPrompt}\n\n` +
+        `Loop mode is active. Goal: ${state.description}. Completion criteria: ${state.completionCriteria || "continuous improvement"}. ` +
+        `Keep every assistant response under 1,200 characters, do one progress batch per turn, ` +
+        `${doneHint}, never wait for a human (make documented assumptions instead), and never dump full logs/diffs/context.`,
+    };
+  });
+
+  // --- Anti-repetition sampling penalties for a few iterations after a stuck intervention. ---
+  // Prompt-level interventions rarely break degenerate repetition; sampling penalties usually do.
+  pi.on("before_provider_request", async (event, ctx) => {
+    if (!state.active || state.penaltyTurnsRemaining <= 0) return;
+    // Penalties are only reliable on OpenAI-compatible completions APIs (vLLM, Ollama, …).
+    const api = String((ctx.model as { api?: string } | undefined)?.api ?? "");
+    if (api !== "openai-completions") return;
+    const payload = event.payload;
+    if (!payload || typeof payload !== "object") return;
+    const currentTemperature = (payload as { temperature?: number }).temperature;
+    return {
+      ...(payload as object),
+      frequency_penalty: 0.5,
+      presence_penalty: 0.5,
+      temperature: Math.min(1.3, (currentTemperature ?? 0.7) + 0.2),
+    };
+  });
+
+  // --- Sanitize degenerate assistant messages before every LLM call. ---
+  // A response full of one repeated sentence would otherwise reinforce the pattern each turn.
+  pi.on("context", async (event) => {
+    if (!state.active) return;
+    let changed = false;
+    const messages = event.messages.map((message) => {
+      if ((message as { role?: string }).role !== "assistant") return message;
+      const text = messageToText(message);
+      if (text.length < 300) return message;
+      const sanitized = sanitizeDegenerateText(text);
+      if (!sanitized) return message;
+      changed = true;
+      return replaceMessageText(message as { content?: unknown }, sanitized) as typeof message;
+    });
+    return changed ? { messages } : undefined;
+  });
+
+  // --- Mid-stream kill switch: abort runaway repetition instead of letting it fill the context. ---
+  pi.on("message_start", async (event) => {
+    if ((event.message as { role?: string }).role === "assistant") lastDegenerateCheckLength = 0;
+  });
+
+  pi.on("message_update", async (event, ctx) => {
+    if (!state.active || degenerateAbortPending) return;
+    if ((event.message as { role?: string }).role !== "assistant") return;
+    const text = messageToText(event.message);
+    if (text.length - lastDegenerateCheckLength < DEGENERATE_CHECK_INTERVAL) return;
+    lastDegenerateCheckLength = text.length;
+    const info = degenerateRepetition(text, DEGENERATE_STREAM_REPEATS);
+    if (info) {
+      degenerateAbortPending = true;
+      ctx.ui.notify(`Loop: degenerate repetition mid-stream (×${info.repeats}) — aborting turn.`, "warning");
+      ctx.abort();
+    }
+  });
+
+  pi.on("tool_result", async (event) => {
+    if (!state.active) return;
+    const anyEvent = event as unknown as { toolName: string; content?: unknown; result?: { content?: unknown }; isError?: boolean };
+    const text = contentToText(anyEvent.content ?? anyEvent.result?.content);
+    recordToolResult(anyEvent.toolName, text, Boolean(anyEvent.isError));
+    state.toolCallsThisTurn++;
+  });
+
+  pi.on("message_end", async (event) => {
+    if (!state.active || event.message.role !== "assistant") return;
+    const stopReason = (event.message as { stopReason?: string }).stopReason;
+    if (stopReason === "error" || stopReason === "aborted") return;
+    const text = messageToText(event.message);
+    if (!text.trim()) return;
+    // Persist a truncated version of degenerate responses so they never poison the context.
+    const sanitized = sanitizeDegenerateText(text);
+    const tracked = sanitized ?? text;
+    pushLimited(state.lastAssistantFingerprints, fingerprint(tracked), 8);
+    pushLimited(state.lastAssistantSnippets, snippet(tracked), 5);
+    pushLimited(state.lastAssistantTexts, tracked.slice(0, 1_500), 4);
+    if (sanitized) {
+      return { message: replaceMessageText(event.message as { content?: unknown }, sanitized) as typeof event.message };
+    }
+  });
+
+  pi.on("agent_end", async (event, ctx) => {
+    if (!state.active) {
+      // Goal preparation turn: watch for the readiness marker.
+      if (state.status === "preparing") {
+        const prepAssistant = [...event.messages].reverse().find((message) => message.role === "assistant");
+        const prepText = messageToText(prepAssistant);
+        if (/\bGOAL_READY\s*:/i.test(prepText)) {
+          state.preparedAt = Date.now();
+          state.status = "stopped";
+          state.lastNotice = "Goal prepared.";
+          persistState(pi);
+          ctx.ui.notify(`Goal preparation complete. Review ${state.goalFile}, then start with /loop run [--model M].`, "info");
+        }
+      }
+      return;
+    }
+    clearPendingTimer();
+
+    const lastAssistant = [...event.messages].reverse().find((message) => message.role === "assistant") as
+      | { role: string; content?: unknown; stopReason?: string; errorMessage?: string }
+      | undefined;
+    const lastAssistantText = messageToText(lastAssistant);
+    const stopReason = lastAssistant?.stopReason;
+
+    // --- Model/provider errors: retry with exponential backoff, never give up. ---
+    if (!lastAssistant || stopReason === "error") {
+      state.consecutiveErrorCount++;
+      state.totalErrorCount++;
+      state.status = "retrying";
+      const delay = backoffSeconds();
+      const reason = snippet(lastAssistant?.errorMessage ?? lastAssistantText ?? "no assistant message", 140);
+      state.lastNotice = `Model/provider error (${reason}); retry #${state.consecutiveErrorCount} in ${delay}s.`;
+      persistState(pi);
+      logIteration("error", { reason });
+      ctx.ui.notify(`Loop: model error, retrying in ${delay}s (attempt ${state.consecutiveErrorCount}): ${reason}`, "warning");
+      ctx.ui.setStatus("loop", `Loop retrying in ${delay}s (err #${state.totalErrorCount})`);
+      scheduleLoopTurn(pi, "recover", delay * 1000);
+      return;
+    }
+
+    // --- Degenerate-repetition abort (ours, not the operator's): treat as stuck, keep looping. ---
+    if (stopReason === "aborted" && degenerateAbortPending) {
+      degenerateAbortPending = false;
+      await interveneStuck(pi, ctx, "response degenerated into repeating one sentence; turn aborted mid-stream");
+      return;
+    }
+
+    // --- Operator abort (Esc): respect it, but keep state for /loop resume. ---
+    if (stopReason === "aborted") {
+      state.status = "paused";
+      state.lastNotice = "Turn aborted by operator. Use /loop resume to continue.";
+      persistState(pi);
+      logIteration("operator_abort");
+      ctx.ui.notify("Loop paused (turn aborted). Use /loop resume to continue.", "warning");
+      ctx.ui.setStatus("loop", "Loop paused (aborted)");
+      return;
+    }
+
+    state.consecutiveErrorCount = 0;
+    state.iterationCount++;
+
+    // Track narration-only turns (no tool calls at all).
+    if (state.toolCallsThisTurn === 0) {
+      state.turnsWithoutTools++;
+    } else {
+      state.turnsWithoutTools = 0;
+    }
+    state.toolCallsThisTurn = 0;
+
+    // --- Rescue turn finished: hand control back to the regular loop model. ---
+    if (state.rescueActive) {
+      state.rescueActive = false;
+      state.consecutiveStuckCount = 0;
+      if (state.loopModel) await switchModel(pi, ctx, state.loopModel);
+      state.status = "running";
+      state.lastNotice = "Rescue turn completed; back to loop model.";
+      persistState(pi);
+      logIteration("rescue_end");
+      ctx.ui.setStatus("loop", statusBarText());
+      if (!ctx.hasPendingMessages()) scheduleLoopTurn(pi, "continue", state.delaySeconds * 1000, ctx);
+      return;
+    }
+
+    // --- Objective goal function (if configured). ---
+    let scoreRegressed = false;
+    if (state.checkCommand) {
+      const outcome = await runGoalCheck(pi);
+      if (outcome.execFailed) {
+        ctx.ui.notify(`Loop: goal check could not run: ${outcome.output}`, "warning");
+      }
+      scoreRegressed = applyCheckOutcome(outcome);
+
+      // Verified completion: in until-done mode the check decides, not the model.
+      if (state.untilDone && outcome.passed && !outcome.execFailed) {
+        state.active = false;
+        state.status = "completed";
+        state.lastNotice = `Goal check passed: ${state.checkCommand}`;
+        persistState(pi);
+        logIteration("completed", { by: "check" });
+        ctx.ui.notify(`Loop completed — goal check passed: ${state.description}`, "info");
+        ctx.ui.setStatus("loop", "Loop completed (check passed)");
+        return;
+      }
+    }
+
+    // --- Completion marker. ---
+    if (/\bLOOP_DONE\s*:/i.test(lastAssistantText)) {
+      state.doneSignalCount++;
+      if (state.untilDone) {
+        if (state.checkCommand && state.lastCheckPassed === false) {
+          state.status = "running";
+          state.lastNotice = `LOOP_DONE claimed but goal check fails (streak ${state.checkFailStreak}).`;
+          persistState(pi);
+          logIteration("check_failed");
+          ctx.ui.notify("Loop: LOOP_DONE claimed, but the goal check fails — continuing.", "warning");
+          ctx.ui.setStatus("loop", statusBarText());
+          if (!ctx.hasPendingMessages()) scheduleLoopTurn(pi, "check_failed", state.delaySeconds * 1000, ctx);
+          return;
+        }
+        state.active = false;
+        state.status = "completed";
+        state.lastNotice = "Completion marker seen (until-done mode).";
+        persistState(pi);
+        logIteration("completed", { by: "marker" });
+        ctx.ui.notify(`Loop completed: ${state.description}`, "info");
+        ctx.ui.setStatus("loop", "Loop completed");
+        return;
+      }
+      state.status = "running";
+      state.lastNotice = `Done signal #${state.doneSignalCount}; continuing with improvements.`;
+      persistState(pi);
+      logIteration("done");
+      ctx.ui.notify(`Loop: goal reported done (#${state.doneSignalCount}); continuing with improvement work.`, "info");
+      ctx.ui.setStatus("loop", statusBarText());
+      if (!ctx.hasPendingMessages()) scheduleLoopTurn(pi, "improve", state.delaySeconds * 1000, ctx);
+      return;
+    }
+
+    // --- Blocked marker: never wait for the operator; force assumptions. ---
+    if (/\bLOOP_BLOCKED\s*:/i.test(lastAssistantText)) {
+      state.blockedSignalCount++;
+      state.status = "running";
+      state.lastNotice = `Blocked signal #${state.blockedSignalCount}; instructed to assume and continue.`;
+      persistState(pi);
+      logIteration("blocked");
+      ctx.ui.notify(`Loop: blocked reported (${snippet(lastAssistantText, 120)}); continuing with assumptions.`, "warning");
+      ctx.ui.setStatus("loop", statusBarText());
+      if (!ctx.hasPendingMessages()) scheduleLoopTurn(pi, "unblock", state.delaySeconds * 1000, ctx);
+      return;
+    }
+
+    // --- Optional iteration cap (only when --max was given). ---
+    if (state.maxIterations > 0 && state.iterationCount >= state.maxIterations) {
+      state.active = false;
+      state.status = "paused";
+      state.lastNotice = `Paused after max iterations (${state.maxIterations}).`;
+      persistState(pi);
+      logIteration("max_reached");
+      ctx.ui.notify(`Loop paused after ${state.maxIterations} iterations. Use /loop resume [--max N] to continue.`, "warning");
+      ctx.ui.setStatus("loop", "Loop paused (max iterations)");
+      return;
+    }
+
+    // --- Score regression: a change made the objective measure worse. ---
+    if (scoreRegressed) {
+      state.interventionCount++;
+      state.status = "running";
+      state.lastNotice = `Score regression: ${state.lastCheckScore} (best ${state.bestCheckScore}).`;
+      persistState(pi);
+      logIteration("regression");
+      ctx.ui.notify(`Loop: goal check score regressed to ${state.lastCheckScore} — requesting fix.`, "warning");
+      ctx.ui.setStatus("loop", statusBarText());
+      if (!ctx.hasPendingMessages()) scheduleLoopTurn(pi, "regression", state.delaySeconds * 1000, ctx);
+      return;
+    }
+
+    // --- Stuck detection: intervene with rotating strategies, never pause. ---
+    const stuckReason = detectStuck(lastAssistantText);
+    if (stuckReason) {
+      await interveneStuck(pi, ctx, stuckReason);
+      return;
+    }
+
+    // --- No-progress audit: analysis-only loops must produce artifacts. ---
+    if (state.iterationCount - state.lastStateChangeIteration >= NO_PROGRESS_WINDOW) {
+      state.lastStateChangeIteration = state.iterationCount;
+      state.interventionCount++;
+      state.status = "running";
+      state.lastNotice = `No concrete changes for ${NO_PROGRESS_WINDOW} iterations; audit nudge sent.`;
+      persistState(pi);
+      logIteration("audit");
+      ctx.ui.notify(`Loop: no concrete progress for ${NO_PROGRESS_WINDOW} iterations — requesting tangible output.`, "warning");
+      ctx.ui.setStatus("loop", statusBarText());
+      if (!ctx.hasPendingMessages()) scheduleLoopTurn(pi, "audit", state.delaySeconds * 1000, ctx);
+      return;
+    }
+
+    // --- Normal continue. ---
+    state.consecutiveStuckCount = 0;
+    if (state.penaltyTurnsRemaining > 0) state.penaltyTurnsRemaining--;
+    state.status = "running";
+    state.lastNotice = "";
+    persistState(pi);
+    logIteration("continue");
+    ctx.ui.setStatus("loop", statusBarText());
+
+    if (!ctx.hasPendingMessages()) {
+      scheduleLoopTurn(pi, "continue", state.delaySeconds * 1000, ctx);
+    }
+  });
+}