@lnilluv/pi-ralph-loop 0.2.1 → 1.0.0

package/src/index.ts

@@ -1,129 +1,184 @@
-import { parse as parseYaml } from "yaml";
-import { minimatch } from "minimatch";
-import { readFileSync, existsSync } from "node:fs";
-import { resolve, join, dirname, basename } from "node:path";
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-
-type CommandDef = { name: string; run: string; timeout: number };
-type Frontmatter = {
-  commands: CommandDef[];
-  maxIterations: number;
-  timeout: number;
-  completionPromise?: string;
-  guardrails: { blockCommands: string[]; protectedFiles: string[] };
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import type { ExtensionAPI, ExtensionCommandContext, SessionEntry, AgentEndEvent as PiAgentEndEvent, ToolResultEvent as PiToolResultEvent } from "@mariozechner/pi-coding-agent";
+import {
+  buildMissionBrief,
+  inspectExistingTarget,
+  parseCommandArgs,
+  parseRalphMarkdown,
+  planTaskDraftTarget,
+  renderIterationPrompt,
+  renderRalphBody,
+  resolveCommandRun,
+  replaceArgsPlaceholders,
+  runtimeArgEntriesToMap,
+  shouldStopForCompletionPromise,
+  shouldWarnForBashFailure,
+  shouldValidateExistingDraft,
+  validateDraftContent,
+  validateFrontmatter as validateFrontmatterMessage,
+  validateRuntimeArgs,
+  createSiblingTarget,
+  findBlockedCommandPattern,
+} from "./ralph.ts";
+import { matchesProtectedPath } from "./secret-paths.ts";
+import type { CommandDef, CommandOutput, DraftPlan, DraftTarget, Frontmatter, RuntimeArgs } from "./ralph.ts";
+import { createDraftPlan as createDraftPlanService } from "./ralph-draft.ts";
+import type { StrengthenDraftRuntime } from "./ralph-draft-llm.ts";
+import { runRalphLoop } from "./runner.ts";
+import {
+  checkStopSignal,
+  createStopSignal,
+  listActiveLoopRegistryEntries,
+  readActiveLoopRegistry,
+  readIterationRecords,
+  readStatusFile,
+  recordActiveLoopStopRequest,
+  writeActiveLoopRegistryEntry,
+  type ActiveLoopRegistryEntry,
+} from "./runner-state.ts";
+
+type ProgressState = boolean | "unknown";
+
+type IterationSummary = {
+  iteration: number;
+  duration: number;
+  progress: ProgressState;
+  changedFiles: string[];
+  noProgressStreak: number;
+  snapshotTruncated?: boolean;
+  snapshotErrorCount?: number;
 };
-type ParsedRalph = { frontmatter: Frontmatter; body: string };
-type CommandOutput = { name: string; output: string };
+
 type LoopState = {
   active: boolean;
   ralphPath: string;
+  taskDir: string;
+  cwd: string;
   iteration: number;
   maxIterations: number;
   timeout: number;
   completionPromise?: string;
   stopRequested: boolean;
-  iterationSummaries: Array<{ iteration: number; duration: number }>;
+  noProgressStreak: number;
+  iterationSummaries: IterationSummary[];
   guardrails: { blockCommands: string[]; protectedFiles: string[] };
-  loopSessionFile?: string;
+  observedTaskDirWrites: Set<string>;
+  loopToken?: string;
 };
 type PersistedLoopState = {
   active: boolean;
-  sessionFile?: string;
+  loopToken?: string;
+  cwd?: string;
+  taskDir?: string;
   iteration?: number;
   maxIterations?: number;
-  iterationSummaries?: Array<{ iteration: number; duration: number }>;
+  noProgressStreak?: number;
+  iterationSummaries?: IterationSummary[];
   guardrails?: { blockCommands: string[]; protectedFiles: string[] };
   stopRequested?: boolean;
 };
 
-function defaultFrontmatter(): Frontmatter {
-  return { commands: [], maxIterations: 50, timeout: 300, guardrails: { blockCommands: [], protectedFiles: [] } };
-}
+type ActiveLoopState = PersistedLoopState & { active: true; loopToken: string; envMalformed?: boolean };
+type ActiveIterationState = ActiveLoopState & { iteration: number };
 
-function parseRalphMd(filePath: string): ParsedRalph {
-  let raw = readFileSync(filePath, "utf8");
-  raw = raw.replace(/^\uFEFF/, "").replace(/\r\n/g, "\n");
-  const match = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
-  if (!match) return { frontmatter: defaultFrontmatter(), body: raw };
+const RALPH_RUNNER_TASK_DIR_ENV = "RALPH_RUNNER_TASK_DIR";
+const RALPH_RUNNER_CWD_ENV = "RALPH_RUNNER_CWD";
+const RALPH_RUNNER_LOOP_TOKEN_ENV = "RALPH_RUNNER_LOOP_TOKEN";
+const RALPH_RUNNER_CURRENT_ITERATION_ENV = "RALPH_RUNNER_CURRENT_ITERATION";
+const RALPH_RUNNER_MAX_ITERATIONS_ENV = "RALPH_RUNNER_MAX_ITERATIONS";
+const RALPH_RUNNER_NO_PROGRESS_STREAK_ENV = "RALPH_RUNNER_NO_PROGRESS_STREAK";
+const RALPH_RUNNER_GUARDRAILS_ENV = "RALPH_RUNNER_GUARDRAILS";
 
-  const yaml = (parseYaml(match[1]) ?? {}) as Record<string, any>;
-  const commands: CommandDef[] = Array.isArray(yaml.commands)
-    ? yaml.commands.map((c: Record<string, any>) => ({ name: String(c.name ?? ""), run: String(c.run ?? ""), timeout: Number(c.timeout ?? 60) }))
-    : [];
-  const guardrails = (yaml.guardrails ?? {}) as Record<string, any>;
+type CommandContext = ExtensionCommandContext;
+type CommandSessionEntry = SessionEntry;
 
-  return {
-    frontmatter: {
-      commands,
-      maxIterations: Number(yaml.max_iterations ?? 50),
-      timeout: Number(yaml.timeout ?? 300),
-      completionPromise:
-        typeof yaml.completion_promise === "string" && yaml.completion_promise.trim() ? yaml.completion_promise : undefined,
-      guardrails: {
-        blockCommands: Array.isArray(guardrails.block_commands) ? guardrails.block_commands.map((p: unknown) => String(p)) : [],
-        protectedFiles: Array.isArray(guardrails.protected_files) ? guardrails.protected_files.map((p: unknown) => String(p)) : [],
-      },
-    },
-    body: match[2] ?? "",
+type DraftPlanFactory = (
+  task: string,
+  target: DraftTarget,
+  cwd: string,
+  runtime?: StrengthenDraftRuntime,
+) => Promise<DraftPlan>;
+
+type RegisterRalphCommandServices = {
+  createDraftPlan?: DraftPlanFactory;
+  runRalphLoopFn?: typeof runRalphLoop;
+};
+
+type StopTargetSource = "session" | "registry" | "status";
+
+type StopTarget = {
+  cwd: string;
+  taskDir: string;
+  ralphPath: string;
+  loopToken: string;
+  currentIteration: number;
+  maxIterations: number;
+  startedAt: string;
+  source: StopTargetSource;
+};
+
+type ToolEvent = {
+  toolName?: string;
+  toolCallId?: string;
+  input?: {
+    path?: string;
+    command?: string;
   };
-}
+  isError?: boolean;
+  success?: boolean;
+};
 
-function validateFrontmatter(fm: Frontmatter, ctx: any): boolean {
-  if (!Number.isFinite(fm.maxIterations) || !Number.isInteger(fm.maxIterations) || fm.maxIterations <= 0) {
-    ctx.ui.notify("Invalid max_iterations: must be a positive finite integer", "error");
-    return false;
-  }
-  if (!Number.isFinite(fm.timeout) || fm.timeout <= 0) {
-    ctx.ui.notify("Invalid timeout: must be a positive finite number", "error");
+type AgentEndEvent = PiAgentEndEvent;
+
+type ToolResultEvent = PiToolResultEvent;
+
+type BeforeAgentStartEvent = {
+  systemPrompt: string;
+};
+
+type EventContext = Pick<CommandContext, "sessionManager">;
+
+
+function validateFrontmatter(fm: Frontmatter, ctx: Pick<CommandContext, "ui">): boolean {
+  const error = validateFrontmatterMessage(fm);
+  if (error) {
+    ctx.ui.notify(error, "error");
     return false;
   }
-  for (const pattern of fm.guardrails.blockCommands) {
-    try { new RegExp(pattern); } catch {
-      ctx.ui.notify(`Invalid block_commands regex: ${pattern}`, "error");
-      return false;
-    }
-  }
-  for (const cmd of fm.commands) {
-    if (!cmd.name.trim()) {
-      ctx.ui.notify("Invalid command: name is required", "error");
-      return false;
-    }
-    if (!cmd.run.trim()) {
-      ctx.ui.notify(`Invalid command ${cmd.name}: run is required`, "error");
-      return false;
-    }
-    if (!Number.isFinite(cmd.timeout) || cmd.timeout <= 0) {
-      ctx.ui.notify(`Invalid command ${cmd.name}: timeout must be positive`, "error");
-      return false;
-    }
-  }
   return true;
 }
 
-function resolveRalphPath(args: string, cwd: string): string {
-  const target = args.trim() || ".";
-  const abs = resolve(cwd, target);
-  if (existsSync(abs) && abs.endsWith(".md")) return abs;
-  if (existsSync(join(abs, "RALPH.md"))) return join(abs, "RALPH.md");
-  throw new Error(`No RALPH.md found at ${abs}`);
-}
-
-function resolvePlaceholders(body: string, outputs: CommandOutput[], ralph: { iteration: number; name: string }): string {
-  const map = new Map(outputs.map((o) => [o.name, o.output]));
-  return body
-    .replace(/\{\{\s*commands\.(\w[\w-]*)\s*\}\}/g, (_, name) => map.get(name) ?? "")
-    .replace(/\{\{\s*ralph\.iteration\s*\}\}/g, String(ralph.iteration))
-    .replace(/\{\{\s*ralph\.name\s*\}\}/g, ralph.name);
-}
-
-async function runCommands(commands: CommandDef[], pi: ExtensionAPI): Promise<CommandOutput[]> {
+export async function runCommands(
+  commands: CommandDef[],
+  blockPatterns: string[],
+  pi: ExtensionAPI,
+  runtimeArgs: RuntimeArgs = {},
+  cwd?: string,
+  taskDir?: string,
+): Promise<CommandOutput[]> {
+  const repoCwd = cwd ?? process.cwd();
   const results: CommandOutput[] = [];
   for (const cmd of commands) {
+    const semanticRun = replaceArgsPlaceholders(cmd.run, runtimeArgs);
+    const blockedPattern = findBlockedCommandPattern(semanticRun, blockPatterns);
+    const resolvedRun = resolveCommandRun(cmd.run, runtimeArgs);
+    if (blockedPattern) {
+      pi.appendEntry?.("ralph-blocked-command", { name: cmd.name, command: semanticRun, blockedPattern, cwd: repoCwd, taskDir });
+      results.push({ name: cmd.name, output: `[blocked by guardrail: ${blockedPattern}]` });
+      continue;
+    }
+
+    const commandCwd = semanticRun.trim().startsWith("./") ? taskDir ?? repoCwd : repoCwd;
+
     try {
-      const result = await pi.exec("bash", ["-c", cmd.run], { timeout: cmd.timeout * 1000 });
-      results.push(result.killed
-        ? { name: cmd.name, output: `[timed out after ${cmd.timeout}s]` }
-        : { name: cmd.name, output: (result.stdout + result.stderr).trim() });
+      const result = await pi.exec("bash", ["-c", resolvedRun], { timeout: cmd.timeout * 1000, cwd: commandCwd });
+      results.push(
+        result.killed
+          ? { name: cmd.name, output: `[timed out after ${cmd.timeout}s]` }
+          : { name: cmd.name, output: (result.stdout + result.stderr).trim() },
+      );
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       results.push({ name: cmd.name, output: `[error: ${message}]` });
@@ -132,11 +187,99 @@ async function runCommands(commands: CommandDef[], pi: ExtensionAPI): Promise<Co
   return results;
 }
 
+const SNAPSHOT_IGNORED_DIR_NAMES = new Set([
+  ".git",
+  "node_modules",
+  ".next",
+  ".turbo",
+  ".cache",
+  "coverage",
+  "dist",
+  "build",
+  ".ralph-runner",
+]);
+const SNAPSHOT_MAX_FILES = 200;
+const SNAPSHOT_MAX_BYTES = 2 * 1024 * 1024;
+const SNAPSHOT_POST_IDLE_POLL_INTERVAL_MS = 20;
+const SNAPSHOT_POST_IDLE_POLL_WINDOW_MS = 100;
+const RALPH_PROGRESS_FILE = "RALPH_PROGRESS.md";
+
+type WorkspaceSnapshot = {
+  files: Map<string, string>;
+  truncated: boolean;
+  errorCount: number;
+};
+
+type ProgressAssessment = {
+  progress: ProgressState;
+  changedFiles: string[];
+  snapshotTruncated: boolean;
+  snapshotErrorCount: number;
+};
+
+type IterationCompletion = {
+  messages: PiAgentEndEvent["messages"];
+  observedTaskDirWrites: Set<string>;
+  error?: Error;
+};
+
+type Deferred<T> = {
+  promise: Promise<T>;
+  resolve(value: T): void;
+  reject(reason?: unknown): void;
+  settled: boolean;
+};
+
+type PendingIterationState = {
+  prompt: string;
+  completion: Deferred<IterationCompletion>;
+  toolCallPaths: Map<string, string>;
+  observedTaskDirWrites: Set<string>;
+};
+
+function createDeferred<T>(): Deferred<T> {
+  let resolvePromise!: (value: T) => void;
+  let rejectPromise!: (reason?: unknown) => void;
+  const deferred: Deferred<T> = {
+    promise: new Promise<T>((resolve, reject) => {
+      resolvePromise = resolve;
+      rejectPromise = reject;
+    }),
+    resolve(value: T) {
+      if (deferred.settled) return;
+      deferred.settled = true;
+      resolvePromise(value);
+    },
+    reject(reason?: unknown) {
+      if (deferred.settled) return;
+      deferred.settled = true;
+      rejectPromise(reason);
+    },
+    settled: false,
+  };
+  return deferred;
+}
+
 function defaultLoopState(): LoopState {
-  return { active: false, ralphPath: "", iteration: 0, maxIterations: 50, timeout: 300, completionPromise: undefined, stopRequested: false, iterationSummaries: [], guardrails: { blockCommands: [], protectedFiles: [] }, loopSessionFile: undefined };
+  return {
+    active: false,
+    ralphPath: "",
+    taskDir: "",
+    iteration: 0,
+    maxIterations: 50,
+    timeout: 300,
+    completionPromise: undefined,
+    stopRequested: false,
+    noProgressStreak: 0,
+    iterationSummaries: [],
+    guardrails: { blockCommands: [], protectedFiles: [] },
+    observedTaskDirWrites: new Set(),
+    loopToken: undefined,
+    cwd: "",
+  };
 }
 
-function readPersistedLoopState(ctx: any): PersistedLoopState | undefined {
+function readPersistedLoopState(ctx: Pick<CommandContext, "sessionManager">): PersistedLoopState | undefined {
   const entries = ctx.sessionManager.getEntries();
   for (let i = entries.length - 1; i >= 0; i--) {
     const entry = entries[i];
@@ -151,64 +294,1070 @@ function persistLoopState(pi: ExtensionAPI, data: PersistedLoopState) {
   pi.appendEntry("ralph-loop-state", data);
 }
 
+function toPersistedLoopState(state: LoopState, overrides: Partial<PersistedLoopState> = {}): PersistedLoopState {
+  return {
+    active: state.active,
+    loopToken: state.loopToken,
+    cwd: state.cwd,
+    taskDir: state.taskDir,
+    iteration: state.iteration,
+    maxIterations: state.maxIterations,
+    noProgressStreak: state.noProgressStreak,
+    iterationSummaries: state.iterationSummaries,
+    guardrails: { blockCommands: state.guardrails.blockCommands, protectedFiles: state.guardrails.protectedFiles },
+    stopRequested: state.stopRequested,
+    ...overrides,
+  };
+}
+
+function readActiveLoopState(ctx: Pick<CommandContext, "sessionManager">): ActiveLoopState | undefined {
+  const state = readPersistedLoopState(ctx);
+  if (state?.active !== true) return undefined;
+  if (typeof state.loopToken !== "string" || state.loopToken.length === 0) return undefined;
+  return state as ActiveLoopState;
+}
+
+function sanitizeStringArray(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((item): item is string => typeof item === "string") : [];
+}
+
+function sanitizeGuardrails(value: unknown): { blockCommands: string[]; protectedFiles: string[] } {
+  if (!value || typeof value !== "object") {
+    return { blockCommands: [], protectedFiles: [] };
+  }
+  const guardrails = value as { blockCommands?: unknown; protectedFiles?: unknown };
+  return {
+    blockCommands: sanitizeStringArray(guardrails.blockCommands),
+    protectedFiles: sanitizeStringArray(guardrails.protectedFiles),
+  };
+}
+
+function sanitizeProgressState(value: unknown): ProgressState {
+  return value === true || value === false || value === "unknown" ? value : "unknown";
+}
+
+function sanitizeIterationSummary(record: unknown, loopToken: string): IterationSummary | undefined {
+  if (!record || typeof record !== "object") return undefined;
+  const iterationRecord = record as {
+    loopToken?: unknown;
+    iteration?: unknown;
+    durationMs?: unknown;
+    progress?: unknown;
+    changedFiles?: unknown;
+    noProgressStreak?: unknown;
+    snapshotTruncated?: unknown;
+    snapshotErrorCount?: unknown;
+  };
+  if (iterationRecord.loopToken !== loopToken) return undefined;
+  if (typeof iterationRecord.iteration !== "number" || !Number.isFinite(iterationRecord.iteration)) return undefined;
+
+  const durationMs = typeof iterationRecord.durationMs === "number" && Number.isFinite(iterationRecord.durationMs)
+    ? iterationRecord.durationMs
+    : 0;
+  const noProgressStreak = typeof iterationRecord.noProgressStreak === "number" && Number.isFinite(iterationRecord.noProgressStreak)
+    ? iterationRecord.noProgressStreak
+    : 0;
+  const snapshotErrorCount = typeof iterationRecord.snapshotErrorCount === "number" && Number.isFinite(iterationRecord.snapshotErrorCount)
+    ? iterationRecord.snapshotErrorCount
+    : undefined;
+
+  return {
+    iteration: iterationRecord.iteration,
+    duration: Math.round(durationMs / 1000),
+    progress: sanitizeProgressState(iterationRecord.progress),
+    changedFiles: sanitizeStringArray(iterationRecord.changedFiles),
+    noProgressStreak,
+    snapshotTruncated: typeof iterationRecord.snapshotTruncated === "boolean" ? iterationRecord.snapshotTruncated : undefined,
+    snapshotErrorCount,
+  };
+}
+
+function parseLoopContractInteger(raw: string | undefined): number | undefined {
+  if (typeof raw !== "string") return undefined;
+  const trimmed = raw.trim();
+  if (!/^-?\d+$/.test(trimmed)) return undefined;
+  const parsed = Number(trimmed);
+  return Number.isSafeInteger(parsed) ? parsed : undefined;
+}
+
+function parseLoopContractGuardrails(raw: string | undefined): { blockCommands: string[]; protectedFiles: string[] } | undefined {
+  if (typeof raw !== "string") return undefined;
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object") return undefined;
+    const guardrails = parsed as { blockCommands?: unknown; protectedFiles?: unknown };
+    if (
+      !Array.isArray(guardrails.blockCommands) ||
+      !guardrails.blockCommands.every((item) => typeof item === "string") ||
+      !Array.isArray(guardrails.protectedFiles) ||
+      !guardrails.protectedFiles.every((item) => typeof item === "string")
+    ) {
+      return undefined;
+    }
+    return {
+      blockCommands: [...guardrails.blockCommands],
+      protectedFiles: [...guardrails.protectedFiles],
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+function areStringArraysEqual(left: string[], right: string[]): boolean {
+  return left.length === right.length && left.every((item, index) => item === right[index]);
+}
+
+function createFailClosedLoopState(taskDir: string, cwd?: string): ActiveLoopState {
+  return {
+    active: true,
+    loopToken: "",
+    cwd: cwd && cwd.length > 0 ? cwd : taskDir,
+    taskDir,
+    iteration: 0,
+    maxIterations: 0,
+    noProgressStreak: 0,
+    iterationSummaries: [],
+    guardrails: { blockCommands: [".*"], protectedFiles: ["**/*"] },
+    stopRequested: checkStopSignal(taskDir),
+    envMalformed: true,
+  };
+}
+
+function readEnvLoopState(taskDir: string): ActiveLoopState | undefined {
+  const cwd = process.env[RALPH_RUNNER_CWD_ENV]?.trim();
+  const loopToken = process.env[RALPH_RUNNER_LOOP_TOKEN_ENV]?.trim();
+  const currentIteration = parseLoopContractInteger(process.env[RALPH_RUNNER_CURRENT_ITERATION_ENV]);
+  const maxIterations = parseLoopContractInteger(process.env[RALPH_RUNNER_MAX_ITERATIONS_ENV]);
+  const noProgressStreak = parseLoopContractInteger(process.env[RALPH_RUNNER_NO_PROGRESS_STREAK_ENV]);
+  const guardrails = parseLoopContractGuardrails(process.env[RALPH_RUNNER_GUARDRAILS_ENV]);
+
+  if (
+    !cwd ||
+    !loopToken ||
+    currentIteration === undefined ||
+    currentIteration < 0 ||
+    maxIterations === undefined ||
+    maxIterations <= 0 ||
+    noProgressStreak === undefined ||
+    noProgressStreak < 0 ||
+    !guardrails
+  ) {
+    return undefined;
+  }
+
+  const iterationSummaries = readIterationRecords(taskDir)
+    .map((record) => sanitizeIterationSummary(record, loopToken))
+    .filter((summary): summary is IterationSummary => summary !== undefined);
+
+  return {
+    active: true,
+    loopToken,
+    cwd,
+    taskDir,
+    iteration: currentIteration,
+    maxIterations,
+    noProgressStreak,
+    iterationSummaries,
+    guardrails,
+    stopRequested: checkStopSignal(taskDir),
+  };
+}
+
+function readDurableLoopState(taskDir: string, envState: ActiveLoopState): ActiveLoopState | undefined {
+  const envGuardrails = envState.guardrails;
+  if (!envGuardrails) return undefined;
+
+  const durableStatus = readStatusFile(taskDir);
+  if (!durableStatus || typeof durableStatus !== "object") return undefined;
+
+  const status = durableStatus as Record<string, unknown>;
+  const guardrails = status.guardrails as Record<string, unknown> | undefined;
+  if (
+    typeof status.loopToken !== "string" ||
+    status.loopToken.length === 0 ||
+    typeof status.cwd !== "string" ||
+    status.cwd.length === 0 ||
+    typeof status.currentIteration !== "number" ||
+    !Number.isInteger(status.currentIteration) ||
+    status.currentIteration < 0 ||
+    typeof status.maxIterations !== "number" ||
+    !Number.isInteger(status.maxIterations) ||
+    status.maxIterations <= 0 ||
+    typeof status.taskDir !== "string" ||
+    status.taskDir !== taskDir ||
+    !guardrails ||
+    !isStringArray(guardrails.blockCommands) ||
+    !isStringArray(guardrails.protectedFiles)
+  ) {
+    return undefined;
+  }
+
+  const durableLoopToken = status.loopToken;
+  const durableCwd = status.cwd;
+  const durableGuardrails = guardrails as { blockCommands: string[]; protectedFiles: string[] };
+
+  if (
+    durableLoopToken !== envState.loopToken ||
+    durableCwd !== envState.cwd ||
+    status.currentIteration !== envState.iteration ||
+    status.maxIterations !== envState.maxIterations ||
+    !areStringArraysEqual(durableGuardrails.blockCommands, envGuardrails.blockCommands) ||
+    !areStringArraysEqual(durableGuardrails.protectedFiles, envGuardrails.protectedFiles)
+  ) {
+    return undefined;
+  }
+
+  const iterationSummaries = readIterationRecords(taskDir)
+    .map((record) => sanitizeIterationSummary(record, durableLoopToken))
+    .filter((summary): summary is IterationSummary => summary !== undefined);
+
+  return {
+    active: true,
+    loopToken: durableLoopToken,
+    cwd: durableCwd,
+    taskDir,
+    iteration: status.currentIteration,
+    maxIterations: status.maxIterations,
+    noProgressStreak: envState.noProgressStreak,
+    iterationSummaries,
+    guardrails: {
+      blockCommands: [...durableGuardrails.blockCommands],
+      protectedFiles: [...durableGuardrails.protectedFiles],
+    },
+    stopRequested: checkStopSignal(taskDir),
+  };
+}
+
+function resolveActiveLoopState(ctx: Pick<CommandContext, "sessionManager">): ActiveLoopState | undefined {
+  const taskDir = process.env[RALPH_RUNNER_TASK_DIR_ENV]?.trim();
+  if (taskDir) {
+    const envState = readEnvLoopState(taskDir);
+    if (!envState) return createFailClosedLoopState(taskDir, process.env[RALPH_RUNNER_CWD_ENV]?.trim() || undefined);
+    return readDurableLoopState(taskDir, envState) ?? createFailClosedLoopState(taskDir, envState.cwd);
+  }
+  return readActiveLoopState(ctx);
+}
+
+function resolveActiveIterationState(ctx: Pick<CommandContext, "sessionManager">): ActiveIterationState | undefined {
+  const state = resolveActiveLoopState(ctx);
+  if (!state || typeof state.iteration !== "number") return undefined;
+  return state as ActiveIterationState;
+}
+
+function getLoopIterationKey(loopToken: string, iteration: number): string {
+  return `${loopToken}:${iteration}`;
+}
+
+function normalizeSnapshotPath(filePath: string): string {
+  return filePath.split("\\").join("/");
+}
+
+function captureTaskDirectorySnapshot(ralphPath: string): WorkspaceSnapshot {
+  const taskDir = dirname(ralphPath);
+  const progressMemoryPath = join(taskDir, RALPH_PROGRESS_FILE);
+  const files = new Map<string, string>();
+  let truncated = false;
+  let bytesRead = 0;
+  let errorCount = 0;
+
+  const walk = (dirPath: string) => {
+    let entries;
+    try {
+      entries = readdirSync(dirPath, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    } catch {
+      errorCount += 1;
+      return;
+    }
+
+    for (const entry of entries) {
+      if (truncated) return;
+      const fullPath = join(dirPath, entry.name);
+
+      if (entry.isDirectory()) {
+        if (SNAPSHOT_IGNORED_DIR_NAMES.has(entry.name)) continue;
+        walk(fullPath);
+        continue;
+      }
+      if (!entry.isFile() || fullPath === ralphPath || fullPath === progressMemoryPath) continue;
+      if (files.size >= SNAPSHOT_MAX_FILES) {
+        truncated = true;
+        return;
+      }
+
+      const relPath = normalizeSnapshotPath(relative(taskDir, fullPath));
+      if (!relPath || relPath.startsWith("..")) continue;
+
+      let content;
+      try {
+        content = readFileSync(fullPath);
+      } catch {
+        errorCount += 1;
+        continue;
+      }
+      if (bytesRead + content.byteLength > SNAPSHOT_MAX_BYTES) {
+        truncated = true;
+        return;
+      }
+
+      bytesRead += content.byteLength;
+      files.set(relPath, `${content.byteLength}:${createHash("sha1").update(content).digest("hex")}`);
+    }
+  };
+
+  if (existsSync(taskDir)) walk(taskDir);
+  return { files, truncated, errorCount };
+}
+
+function diffTaskDirectorySnapshots(before: WorkspaceSnapshot, after: WorkspaceSnapshot): string[] {
+  const changed = new Set<string>();
+  for (const [filePath, fingerprint] of before.files) {
+    if (after.files.get(filePath) !== fingerprint) changed.add(filePath);
+  }
+  for (const filePath of after.files.keys()) {
+    if (!before.files.has(filePath)) changed.add(filePath);
+  }
+  return [...changed].sort((a, b) => a.localeCompare(b));
+}
+
+function resolveTaskDirObservedPath(taskDir: string, cwd: string, filePath: string): string | undefined {
+  if (!taskDir || !cwd || !filePath) return undefined;
+  const relPath = normalizeSnapshotPath(relative(resolve(taskDir), resolve(cwd, filePath)));
+  if (!relPath || relPath === "." || relPath.startsWith("..")) return undefined;
+  return relPath;
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolveDelay) => {
+    setTimeout(resolveDelay, ms);
+  });
+}
+
+async function assessTaskDirectoryProgress(
+  ralphPath: string,
+  before: WorkspaceSnapshot,
+  observedTaskDirWrites: ReadonlySet<string>,
+): Promise<ProgressAssessment> {
+  let after = captureTaskDirectorySnapshot(ralphPath);
+  let changedFiles = diffTaskDirectorySnapshots(before, after);
+  let snapshotTruncated = before.truncated || after.truncated;
+  let snapshotErrorCount = before.errorCount + after.errorCount;
+
+  if (changedFiles.length > 0) {
+    return { progress: true, changedFiles, snapshotTruncated, snapshotErrorCount };
+  }
+
+  for (let remainingMs = SNAPSHOT_POST_IDLE_POLL_WINDOW_MS; remainingMs > 0; remainingMs -= SNAPSHOT_POST_IDLE_POLL_INTERVAL_MS) {
+    await delay(Math.min(SNAPSHOT_POST_IDLE_POLL_INTERVAL_MS, remainingMs));
+    after = captureTaskDirectorySnapshot(ralphPath);
+    changedFiles = diffTaskDirectorySnapshots(before, after);
+    snapshotTruncated ||= after.truncated;
+    snapshotErrorCount += after.errorCount;
+    if (changedFiles.length > 0) {
+      return { progress: true, changedFiles, snapshotTruncated, snapshotErrorCount };
+    }
+  }
+
+  if (observedTaskDirWrites.size > 0) {
+    return { progress: "unknown", changedFiles: [], snapshotTruncated, snapshotErrorCount };
+  }
+
+  return {
+    progress: snapshotTruncated || snapshotErrorCount > 0 ? "unknown" : false,
+    changedFiles,
+    snapshotTruncated,
+    snapshotErrorCount,
+  };
+}
+
+function summarizeChangedFiles(changedFiles: string[]): string {
+  if (changedFiles.length === 0) return "none";
+  const visible = changedFiles.slice(0, 5);
+  if (visible.length === changedFiles.length) return visible.join(", ");
+  return `${visible.join(", ")} (+${changedFiles.length - visible.length} more)`;
+}
+
+function summarizeSnapshotCoverage(truncated: boolean, errorCount: number): string {
+  const parts: string[] = [];
+  if (truncated) parts.push("snapshot truncated");
+  if (errorCount > 0) parts.push(errorCount === 1 ? "1 file unreadable" : `${errorCount} files unreadable`);
+  return parts.join(", ");
+}
+
+function summarizeIterationProgress(summary: Pick<IterationSummary, "progress" | "changedFiles" | "snapshotTruncated" | "snapshotErrorCount">): string {
+  if (summary.progress === true) return `durable progress (${summarizeChangedFiles(summary.changedFiles)})`;
+  if (summary.progress === false) return "no durable progress";
+  const coverage = summarizeSnapshotCoverage(summary.snapshotTruncated ?? false, summary.snapshotErrorCount ?? 0);
+  return coverage ? `durable progress unknown (${coverage})` : "durable progress unknown";
+}
+
+function summarizeLastIterationFeedback(summary: IterationSummary | undefined, fallbackNoProgressStreak: number): string {
+  if (!summary) return "";
+  if (summary.progress === true) {
+    return `Last iteration durable progress: ${summarizeChangedFiles(summary.changedFiles)}.`;
+  }
+  if (summary.progress === false) {
+    return `Last iteration made no durable progress. No-progress streak: ${summary.noProgressStreak ?? fallbackNoProgressStreak}.`;
+  }
+  const coverage = summarizeSnapshotCoverage(summary.snapshotTruncated ?? false, summary.snapshotErrorCount ?? 0);
+  const detail = coverage ? ` (${coverage})` : "";
+  return `Last iteration durable progress could not be verified${detail}. No-progress streak remains ${summary.noProgressStreak ?? fallbackNoProgressStreak}.`;
+}
+
+function writeDraftFile(ralphPath: string, content: string) {
+  mkdirSync(dirname(ralphPath), { recursive: true });
+  writeFileSync(ralphPath, content, "utf8");
+}
+
+function displayPath(cwd: string, filePath: string): string {
+  const rel = relative(cwd, filePath);
+  return rel && !rel.startsWith("..") ? `./${rel}` : filePath;
+}
+
+async function promptForTask(ctx: Pick<CommandContext, "hasUI" | "ui">, title: string, placeholder: string): Promise<string | undefined> {
+  if (!ctx.hasUI) return undefined;
+  const value = await ctx.ui.input(title, placeholder);
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+async function reviewDraft(plan: DraftPlan, mode: "run" | "draft", ctx: Pick<CommandContext, "ui">): Promise<{ action: "start" | "save" | "cancel"; content: string }> {
+  let content = plan.content;
+
+  while (true) {
+    const nextPlan = { ...plan, content };
+    const contentError = validateDraftContent(content);
+    const options = contentError
+      ? ["Open RALPH.md", "Cancel"]
+      : mode === "run"
+        ? ["Start", "Open RALPH.md", "Cancel"]
+        : ["Save draft", "Open RALPH.md", "Cancel"];
+    const choice = await ctx.ui.select(buildMissionBrief(nextPlan), options);
+
+    if (!choice || choice === "Cancel") {
+      return { action: "cancel", content };
+    }
+    if (choice === "Open RALPH.md") {
+      const edited = await ctx.ui.editor("Edit RALPH.md", content);
+      if (typeof edited === "string") content = edited;
+      continue;
+    }
+    if (contentError) {
+      ctx.ui.notify(`Invalid RALPH.md: ${contentError}`, "error");
+      continue;
+    }
+    if (choice === "Save draft") {
+      return { action: "save", content };
+    }
+    return { action: "start", content };
+  }
+}
+
+async function editExistingDraft(ralphPath: string, ctx: Pick<CommandContext, "cwd" | "hasUI" | "ui">, saveMessage = "Saved RALPH.md") {
+  if (!ctx.hasUI) {
+    ctx.ui.notify(`Use ${displayPath(ctx.cwd, ralphPath)} in an interactive session to edit the draft.`, "warning");
+    return;
+  }
+
+  let content = readFileSync(ralphPath, "utf8");
+  const strictValidation = shouldValidateExistingDraft(content);
+  while (true) {
+    const edited = await ctx.ui.editor("Edit RALPH.md", content);
+    if (typeof edited !== "string") return;
+
+    if (strictValidation) {
+      const error = validateDraftContent(edited);
+      if (error) {
+        ctx.ui.notify(`Invalid RALPH.md: ${error}`, "error");
+        content = edited;
+        continue;
+      }
+    }
+
+    if (edited !== content) {
+      writeDraftFile(ralphPath, edited);
+      ctx.ui.notify(saveMessage, "info");
+    }
+    return;
+  }
+}
+
+async function chooseRecoveryMode(
+  input: string,
+  dirPath: string,
+  ctx: Pick<CommandContext, "cwd" | "ui">,
+  allowTaskFallback = true,
+): Promise<"draft-path" | "task" | "cancel"> {
+  const options = allowTaskFallback ? ["Draft in that folder", "Treat as task text", "Cancel"] : ["Draft in that folder", "Cancel"];
+  const choice = await ctx.ui.select(`No RALPH.md in ${displayPath(ctx.cwd, dirPath)}.`, options);
+  if (choice === "Draft in that folder") return "draft-path";
+  if (choice === "Treat as task text") return "task";
+  return "cancel";
+}
+
+async function chooseConflictTarget(commandName: "ralph" | "ralph-draft", task: string, target: DraftTarget, ctx: Pick<CommandContext, "cwd" | "ui">): Promise<{ action: "run-existing" | "open-existing" | "draft-target" | "cancel"; target?: DraftTarget }> {
+  const hasExistingDraft = existsSync(target.ralphPath);
+  const title = hasExistingDraft
+    ? `Found an existing RALPH at ${displayPath(ctx.cwd, target.ralphPath)} for “${task}”.`
+    : `Found an occupied draft directory at ${displayPath(ctx.cwd, target.dirPath)} for “${task}”.`;
+  const options =
+    commandName === "ralph"
+      ? hasExistingDraft
+        ? ["Run existing", "Open existing RALPH.md", "Create sibling", "Cancel"]
+        : ["Create sibling", "Cancel"]
+      : hasExistingDraft
+        ? ["Open existing RALPH.md", "Create sibling", "Cancel"]
+        : ["Create sibling", "Cancel"];
+  const choice = await ctx.ui.select(title, options);
+
+  if (!choice || choice === "Cancel") return { action: "cancel" };
+  if (choice === "Run existing") return { action: "run-existing" };
+  if (choice === "Open existing RALPH.md") return { action: "open-existing" };
+  return { action: "draft-target", target: createSiblingTarget(ctx.cwd, target.slug) };
+}
+
+function getDraftStrengtheningRuntime(ctx: Pick<CommandContext, "model" | "modelRegistry">): StrengthenDraftRuntime | undefined {
+  if (!ctx.model || !ctx.modelRegistry) return undefined;
+  return {
+    model: ctx.model,
+    modelRegistry: ctx.modelRegistry,
+  };
+}
+
+async function draftFromTask(
+  commandName: "ralph" | "ralph-draft",
+  task: string,
+  target: DraftTarget,
+  ctx: Pick<CommandContext, "cwd" | "ui">,
+  draftPlanFactory: DraftPlanFactory,
+  runtime?: StrengthenDraftRuntime,
+): Promise<string | undefined> {
+  const plan = await draftPlanFactory(task, target, ctx.cwd, runtime);
+  const review = await reviewDraft(plan, commandName === "ralph" ? "run" : "draft", ctx);
+  if (review.action === "cancel") return undefined;
+
+  writeDraftFile(target.ralphPath, review.content);
+  if (review.action === "save") {
+    ctx.ui.notify(`Draft saved to ${displayPath(ctx.cwd, target.ralphPath)}`, "info");
+    return undefined;
+  }
+  return target.ralphPath;
+}
+
+function resolveSessionStopTarget(ctx: Pick<CommandContext, "cwd" | "sessionManager">, now: string): {
+  target?: StopTarget;
+  persistedSessionState?: ActiveLoopState;
+} {
+  if (loopState.active) {
+    return {
+      target: {
+        cwd: loopState.cwd || ctx.cwd,
+        taskDir: loopState.taskDir,
+        ralphPath: loopState.ralphPath,
+        loopToken: loopState.loopToken ?? "",
+        currentIteration: loopState.iteration,
+        maxIterations: loopState.maxIterations,
+        startedAt: now,
+        source: "session",
+      },
+    };
+  }
+
+  const persistedSessionState = readActiveLoopState(ctx);
+  if (
+    !persistedSessionState ||
+    typeof persistedSessionState.taskDir !== "string" ||
+    persistedSessionState.taskDir.length === 0 ||
+    typeof persistedSessionState.loopToken !== "string" ||
+    persistedSessionState.loopToken.length === 0 ||
+    typeof persistedSessionState.iteration !== "number" ||
+    typeof persistedSessionState.maxIterations !== "number"
+  ) {
+    return { persistedSessionState };
+  }
+
+  return {
+    persistedSessionState,
+    target: {
+      cwd: typeof persistedSessionState.cwd === "string" && persistedSessionState.cwd.length > 0 ? persistedSessionState.cwd : ctx.cwd,
+      taskDir: persistedSessionState.taskDir,
+      ralphPath: join(persistedSessionState.taskDir, "RALPH.md"),
+      loopToken: persistedSessionState.loopToken,
+      currentIteration: persistedSessionState.iteration,
+      maxIterations: persistedSessionState.maxIterations,
+      startedAt: now,
+      source: "session",
+    },
+  };
+}
+
+function materializeRegistryStopTarget(entry: ActiveLoopRegistryEntry): StopTarget {
+  return {
+    cwd: entry.cwd,
+    taskDir: entry.taskDir,
+    ralphPath: entry.ralphPath,
+    loopToken: entry.loopToken,
+    currentIteration: entry.currentIteration,
+    maxIterations: entry.maxIterations,
+    startedAt: entry.startedAt,
+    source: "registry",
+  };
+}
+
+function applyStopTarget(
+  pi: ExtensionAPI,
+  ctx: Pick<CommandContext, "cwd" | "ui">,
+  target: StopTarget,
+  now: string,
+  persistedSessionState?: ActiveLoopState,
+): void {
+  createStopSignal(target.taskDir);
+
+  const registryCwd = target.cwd;
+  const existingEntry = readActiveLoopRegistry(registryCwd).find((entry) => entry.taskDir === target.taskDir);
+  const registryEntry: ActiveLoopRegistryEntry = existingEntry
+    ? {
+        ...existingEntry,
+        taskDir: target.taskDir,
+        ralphPath: target.ralphPath,
+        cwd: registryCwd,
+        updatedAt: now,
+      }
+    : {
+        taskDir: target.taskDir,
+        ralphPath: target.ralphPath,
+        cwd: registryCwd,
+        loopToken: target.loopToken,
+        status: "running",
+        currentIteration: target.currentIteration,
+        maxIterations: target.maxIterations,
+        startedAt: target.startedAt,
+        updatedAt: now,
+      };
+  writeActiveLoopRegistryEntry(registryCwd, registryEntry);
+  recordActiveLoopStopRequest(registryCwd, target.taskDir, now);
+
+  if (target.source === "session") {
+    loopState.stopRequested = true;
+    if (loopState.active) {
+      persistLoopState(pi, toPersistedLoopState(loopState, { active: true, stopRequested: true }));
+    } else if (persistedSessionState?.active) {
+      persistLoopState(pi, { ...persistedSessionState, stopRequested: true });
+    }
+  }
+
+  ctx.ui.notify("Ralph loop stopping after current iteration…", "info");
+}
+
 let loopState: LoopState = defaultLoopState();
+const RALPH_EXTENSION_REGISTERED = Symbol.for("pi-ralph-loop.registered");
 
-export default function (pi: ExtensionAPI) {
+export default function (pi: ExtensionAPI, services: RegisterRalphCommandServices = {}) {
+  const registeredPi = pi as ExtensionAPI & Record<symbol, boolean | undefined>;
+  if (registeredPi[RALPH_EXTENSION_REGISTERED]) return;
+  registeredPi[RALPH_EXTENSION_REGISTERED] = true;
   const failCounts = new Map<string, number>();
-  const isLoopSession = (ctx: any): boolean => {
-    const state = readPersistedLoopState(ctx);
-    const sessionFile = ctx.sessionManager.getSessionFile();
-    return state?.active === true && state.sessionFile === sessionFile;
+  const pendingIterations = new Map<string, PendingIterationState>();
+  const draftPlanFactory = services.createDraftPlan ?? createDraftPlanService;
+  const isLoopSession = (ctx: Pick<CommandContext, "sessionManager">): boolean => resolveActiveLoopState(ctx) !== undefined;
+  const appendLoopProofEntry = (customType: string, data: Record<string, unknown>): void => {
+    try {
+      pi.appendEntry?.(customType, data);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      try {
+        process.stderr.write(`Ralph proof logging failed for ${customType}: ${message}\n`);
+      } catch {
+        // Best-effort surfacing only.
+      }
+    }
+  };
+  const getPendingIteration = (ctx: Pick<CommandContext, "sessionManager">): PendingIterationState | undefined => {
+    const state = resolveActiveIterationState(ctx);
+    return state ? pendingIterations.get(getLoopIterationKey(state.loopToken, state.iteration)) : undefined;
+  };
+  const registerPendingIteration = (loopToken: string, iteration: number, prompt: string): PendingIterationState => {
+    const pending: PendingIterationState = {
+      prompt,
+      completion: createDeferred<IterationCompletion>(),
+      toolCallPaths: new Map(),
+      observedTaskDirWrites: new Set(),
+    };
+    pendingIterations.set(getLoopIterationKey(loopToken, iteration), pending);
+    return pending;
+  };
+  const clearPendingIteration = (loopToken: string, iteration: number) => {
+    pendingIterations.delete(getLoopIterationKey(loopToken, iteration));
+  };
+  const resolvePendingIteration = (ctx: EventContext, event: AgentEndEvent) => {
+    const state = resolveActiveIterationState(ctx);
+    if (!state) return;
+    const pendingKey = getLoopIterationKey(state.loopToken, state.iteration);
+    const pending = pendingIterations.get(pendingKey);
+    if (!pending) return;
+    pendingIterations.delete(pendingKey);
+    const rawError = (event as { error?: unknown }).error;
+    const error = rawError instanceof Error ? rawError : rawError ? new Error(String(rawError)) : undefined;
+    pending.completion.resolve({
+      messages: event.messages ?? [],
+      observedTaskDirWrites: new Set(pending.observedTaskDirWrites),
+      error,
+    });
+  };
+  const recordPendingToolPath = (ctx: EventContext, event: ToolEvent) => {
+    const pending = getPendingIteration(ctx);
+    if (!pending) return;
+    if (event.toolName !== "write" && event.toolName !== "edit") return;
+    const toolCallId = typeof event.toolCallId === "string" ? event.toolCallId : undefined;
+    const filePath = event.input?.path ?? "";
+    if (toolCallId && filePath) pending.toolCallPaths.set(toolCallId, filePath);
+  };
+  const recordSuccessfulTaskDirWrite = (ctx: EventContext, event: ToolEvent) => {
+    const pending = getPendingIteration(ctx);
+    if (!pending) return;
+    if (event.toolName !== "write" && event.toolName !== "edit") return;
+    const toolCallId = typeof event.toolCallId === "string" ? event.toolCallId : undefined;
+    const filePath = toolCallId ? pending.toolCallPaths.get(toolCallId) : undefined;
+    if (toolCallId) pending.toolCallPaths.delete(toolCallId);
+    if (event.isError === true || event.success === false || !filePath) return;
+    const persisted = resolveActiveLoopState(ctx);
+    const taskDirPath = persisted?.taskDir ?? loopState.taskDir;
+    const cwd = persisted?.cwd ?? loopState.cwd;
+    const relPath = resolveTaskDirObservedPath(taskDirPath ?? "", cwd ?? taskDirPath ?? "", filePath);
+    if (relPath && relPath !== RALPH_PROGRESS_FILE) pending.observedTaskDirWrites.add(relPath);
   };
 
-  pi.on("tool_call", async (event: any, ctx: any) => {
-    if (!isLoopSession(ctx)) return;
-    const persisted = readPersistedLoopState(ctx);
+  async function startRalphLoop(ralphPath: string, ctx: CommandContext, runLoopFn: typeof runRalphLoop = runRalphLoop, runtimeArgs: RuntimeArgs = {}) {
+    let name: string;
+    try {
+      const raw = readFileSync(ralphPath, "utf8");
+      const draftError = validateDraftContent(raw);
+      if (draftError) {
+        ctx.ui.notify(`Invalid RALPH.md: ${draftError}`, "error");
+        return;
+      }
+      const parsed = parseRalphMarkdown(raw);
+      const { frontmatter } = parsed;
+      if (!validateFrontmatter(frontmatter, ctx)) return;
+      const runtimeValidationError = validateRuntimeArgs(frontmatter, parsed.body, frontmatter.commands, runtimeArgs);
+      if (runtimeValidationError) {
+        ctx.ui.notify(runtimeValidationError, "error");
+        return;
+      }
+      const taskDir = dirname(ralphPath);
+      name = basename(taskDir);
+      loopState = {
+        active: true,
+        ralphPath,
+        taskDir,
+        cwd: ctx.cwd,
+        iteration: 0,
+        maxIterations: frontmatter.maxIterations,
+        timeout: frontmatter.timeout,
+        completionPromise: frontmatter.completionPromise,
+        stopRequested: false,
+        noProgressStreak: 0,
+        iterationSummaries: [],
+        guardrails: { blockCommands: frontmatter.guardrails.blockCommands, protectedFiles: frontmatter.guardrails.protectedFiles },
+        observedTaskDirWrites: new Set(),
+        loopToken: randomUUID(),
+      };
+    } catch (err) {
+      ctx.ui.notify(String(err), "error");
+      return;
+    }
+    ctx.ui.notify(`Ralph loop started: ${name} (max ${loopState.maxIterations} iterations)`, "info");
+
+    try {
+      const result = await runLoopFn({
+        ralphPath,
+        cwd: ctx.cwd,
+        timeout: loopState.timeout,
+        maxIterations: loopState.maxIterations,
+        guardrails: loopState.guardrails,
+        runtimeArgs,
+        modelPattern: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined,
+        thinkingLevel: ctx.model?.reasoning ? "high" : undefined,
+        runCommandsFn: async (commands, blocked, commandPi, cwd, taskDir) => runCommands(commands, blocked, commandPi as ExtensionAPI, runtimeArgs, cwd, taskDir),
+        onStatusChange(status) {
+          ctx.ui.setStatus("ralph", status === "running" || status === "initializing" ? `🔁 ${name}: running` : undefined);
+        },
+        onNotify(message, level) {
+          ctx.ui.notify(message, level);
+        },
+        onIterationComplete(record) {
+          loopState.iteration = record.iteration;
+          loopState.noProgressStreak = record.noProgressStreak;
+          const summary: IterationSummary = {
+            iteration: record.iteration,
+            duration: record.durationMs ? Math.round(record.durationMs / 1000) : 0,
+            progress: record.progress,
+            changedFiles: record.changedFiles,
+            noProgressStreak: record.noProgressStreak,
+          };
+          loopState.iterationSummaries.push(summary);
+          pi.appendEntry("ralph-iteration", {
+            iteration: record.iteration,
+            duration: summary.duration,
+            ralphPath: loopState.ralphPath,
+            progress: record.progress,
+            changedFiles: record.changedFiles,
+            noProgressStreak: record.noProgressStreak,
+          });
+          persistLoopState(pi, toPersistedLoopState(loopState, { active: true, stopRequested: false }));
+        },
+        pi,
+      });
+
+      // Map runner result to UI notifications
+      const total = loopState.iterationSummaries.reduce((a, s) => a + s.duration, 0);
+      switch (result.status) {
+        case "complete":
+          ctx.ui.notify(`Ralph loop complete: completion promise matched on iteration ${result.iterations.length} (${total}s total)`, "info");
+          break;
+        case "max-iterations":
+          ctx.ui.notify(`Ralph loop reached max iterations: ${result.iterations.length} iterations, ${total}s total`, "info");
+          break;
+        case "no-progress-exhaustion":
+          ctx.ui.notify(`Ralph loop exhausted without verified progress: ${result.iterations.length} iterations, ${total}s total`, "warning");
+          break;
+        case "stopped":
+          ctx.ui.notify(`Ralph loop stopped: ${result.iterations.length} iterations, ${total}s total`, "info");
+          break;
+        case "timeout":
+          ctx.ui.notify(`Ralph loop stopped after a timeout: ${result.iterations.length} iterations, ${total}s total`, "warning");
+          break;
+        case "error":
+          ctx.ui.notify(`Ralph loop failed: ${result.iterations.length} iterations, ${total}s total`, "error");
+          break;
+        default:
+          ctx.ui.notify(`Ralph loop ended: ${result.status} (${total}s total)`, "info");
+          break;
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      ctx.ui.notify(`Ralph loop failed: ${message}`, "error");
+    } finally {
+      failCounts.clear();
+      pendingIterations.clear();
+      loopState.active = false;
+      loopState.stopRequested = false;
+      loopState.loopToken = undefined;
+      ctx.ui.setStatus("ralph", undefined);
+      persistLoopState(pi, toPersistedLoopState(loopState, { active: false, stopRequested: false }));
+    }
+  }
+
+  let runtimeArgsForStart: RuntimeArgs = {};
+
+  async function handleDraftCommand(commandName: "ralph" | "ralph-draft", args: string, ctx: CommandContext): Promise<string | undefined> {
+    const parsed = parseCommandArgs(args);
+    if (parsed.error) {
+      ctx.ui.notify(parsed.error, "error");
+      return undefined;
+    }
+    const runtimeArgsResult = runtimeArgEntriesToMap(parsed.runtimeArgs);
+    if (runtimeArgsResult.error) {
+      ctx.ui.notify(runtimeArgsResult.error, "error");
+      return undefined;
+    }
+    const runtimeArgs = runtimeArgsResult.runtimeArgs;
+    if (parsed.runtimeArgs.length > 0 && (commandName === "ralph-draft" || parsed.mode !== "path")) {
+      ctx.ui.notify("--arg is only supported with /ralph --path", "error");
+      return undefined;
+    }
+    runtimeArgsForStart = runtimeArgs;
+    const draftRuntime = getDraftStrengtheningRuntime(ctx);
+
+    const resolveTaskForFolder = async (target: DraftTarget): Promise<string | undefined> => {
+      const task = await promptForTask(ctx, "What should Ralph work on in this folder?", "reverse engineer this app");
+      if (!task) return undefined;
+      return draftFromTask(commandName, task, target, ctx, draftPlanFactory, draftRuntime);
+    };
+
+    const handleExistingInspection = async (input: string, explicitPath = false, runtimeArgsProvided = false): Promise<string | undefined> => {
+      const inspection = inspectExistingTarget(input, ctx.cwd, explicitPath);
+      if (runtimeArgsProvided && inspection.kind !== "run") {
+        ctx.ui.notify("--arg is only supported with /ralph --path to an existing RALPH.md", "error");
+        return undefined;
+      }
+      switch (inspection.kind) {
+        case "run":
+          if (commandName === "ralph") return inspection.ralphPath;
+          await editExistingDraft(inspection.ralphPath, ctx, `Saved ${displayPath(ctx.cwd, inspection.ralphPath)}`);
+          return undefined;
+        case "invalid-markdown":
+          ctx.ui.notify(`Only task folders or RALPH.md can be run directly. ${displayPath(ctx.cwd, inspection.path)} is not runnable.`, "error");
+          return undefined;
+        case "invalid-target":
+          ctx.ui.notify(`Only task folders or RALPH.md can be run directly. ${displayPath(ctx.cwd, inspection.path)} is a file, not a task folder.`, "error");
+          return undefined;
+        case "dir-without-ralph":
+        case "missing-path": {
+          if (!ctx.hasUI) {
+            ctx.ui.notify("Draft review requires an interactive session. Pass a task folder or RALPH.md path instead.", "warning");
+            return undefined;
+          }
+          const recovery = await chooseRecoveryMode(input, inspection.dirPath, ctx, !explicitPath);
+          if (recovery === "cancel") return undefined;
+          if (recovery === "task") {
+            return handleTaskFlow(input);
+          }
+          return resolveTaskForFolder({ slug: basename(inspection.dirPath), dirPath: inspection.dirPath, ralphPath: inspection.ralphPath });
+        }
+        case "not-path":
+          return handleTaskFlow(input);
+      }
+    };
+
+    const handleTaskFlow = async (taskInput: string): Promise<string | undefined> => {
+      const task = taskInput.trim();
+      if (!task) return undefined;
+      if (!ctx.hasUI) {
+        ctx.ui.notify("Draft review requires an interactive session. Use /ralph with a task folder or RALPH.md path instead.", "warning");
+        return undefined;
+      }
+
+      let planned = planTaskDraftTarget(ctx.cwd, task);
+      if (planned.kind === "conflict") {
+        const decision = await chooseConflictTarget(commandName, task, planned.target, ctx);
+        if (decision.action === "cancel") return undefined;
+        if (decision.action === "run-existing") return planned.target.ralphPath;
+        if (decision.action === "open-existing") {
+          await editExistingDraft(planned.target.ralphPath, ctx, `Saved ${displayPath(ctx.cwd, planned.target.ralphPath)}`);
+          return undefined;
+        }
+        planned = { kind: "draft", target: decision.target! };
+      }
+      return draftFromTask(commandName, task, planned.target, ctx, draftPlanFactory, draftRuntime);
+    };
+
+    if (parsed.mode === "task") {
+      return handleTaskFlow(parsed.value);
+    }
+    if (parsed.mode === "path") {
+      return handleExistingInspection(parsed.value || ".", true, parsed.runtimeArgs.length > 0);
+    }
+    if (!parsed.value) {
+      const inspection = inspectExistingTarget(".", ctx.cwd);
+      if (inspection.kind === "run") {
+        if (commandName === "ralph") return inspection.ralphPath;
+        await editExistingDraft(inspection.ralphPath, ctx, `Saved ${displayPath(ctx.cwd, inspection.ralphPath)}`);
+        return undefined;
+      }
+      if (!ctx.hasUI) {
+        ctx.ui.notify("Draft review requires an interactive session. Pass a task folder or RALPH.md path instead.", "warning");
+        return undefined;
+      }
+      return resolveTaskForFolder({ slug: basename(ctx.cwd), dirPath: ctx.cwd, ralphPath: join(ctx.cwd, "RALPH.md") });
+    }
+    return handleExistingInspection(parsed.value);
+  }
+
+  pi.on("tool_call", async (event: ToolEvent, ctx: EventContext) => {
+    const persisted = resolveActiveLoopState(ctx);
     if (!persisted) return;
 
+    if (persisted.envMalformed && (event.toolName === "bash" || event.toolName === "write" || event.toolName === "edit")) {
+      return { block: true, reason: "ralph: invalid loop contract" };
+    }
+
     if (event.toolName === "bash") {
       const cmd = (event.input as { command?: string }).command ?? "";
-      for (const pattern of persisted.guardrails?.blockCommands ?? []) {
-        try {
-          if (new RegExp(pattern).test(cmd)) return { block: true, reason: `ralph: blocked (${pattern})` };
-        } catch {
-          // ignore malformed persisted regex
-        }
+      const blockedPattern = findBlockedCommandPattern(cmd, persisted.guardrails?.blockCommands ?? []);
+      if (blockedPattern) {
+        appendLoopProofEntry("ralph-blocked-command", {
+          loopToken: persisted.loopToken,
+          iteration: persisted.iteration,
+          command: cmd,
+          blockedPattern,
+        });
+        return { block: true, reason: `ralph: blocked (${blockedPattern})` };
       }
     }
 
     if (event.toolName === "write" || event.toolName === "edit") {
       const filePath = (event.input as { path?: string }).path ?? "";
-      for (const glob of persisted.guardrails?.protectedFiles ?? []) {
-        if (minimatch(filePath, glob, { matchBase: true })) return { block: true, reason: `ralph: ${filePath} is protected` };
+      if (matchesProtectedPath(filePath, persisted.guardrails?.protectedFiles ?? [], persisted.cwd)) {
+        appendLoopProofEntry("ralph-blocked-write", {
+          loopToken: persisted.loopToken,
+          iteration: persisted.iteration,
+          toolName: event.toolName,
+          path: filePath,
+          reason: `ralph: ${filePath} is protected`,
+        });
+        return { block: true, reason: `ralph: ${filePath} is protected` };
       }
     }
+
+    recordPendingToolPath(ctx, event);
+  });
+
+  pi.on("tool_execution_start", async (event: ToolEvent, ctx: EventContext) => {
+    recordPendingToolPath(ctx, event);
   });
 
-  pi.on("before_agent_start", async (event: any, ctx: any) => {
-    if (!isLoopSession(ctx)) return;
-    const persisted = readPersistedLoopState(ctx);
+  pi.on("tool_execution_end", async (event: ToolEvent, ctx: EventContext) => {
+    recordSuccessfulTaskDirWrite(ctx, event);
+  });
+
+  pi.on("agent_end", async (event: AgentEndEvent, ctx: EventContext) => {
+    resolvePendingIteration(ctx, event);
+  });
+
+  pi.on("before_agent_start", async (event: BeforeAgentStartEvent, ctx: EventContext) => {
+    const persisted = resolveActiveLoopState(ctx);
+    if (!persisted) return;
     const summaries = persisted?.iterationSummaries ?? [];
     if (summaries.length === 0) return;
 
-    const history = summaries.map((s) => `- Iteration ${s.iteration}: ${s.duration}s`).join("\n");
+    const history = summaries
+      .map((summary) => {
+        const status = summarizeIterationProgress(summary);
+        return `- Iteration ${summary.iteration}: ${summary.duration}s — ${status}; no-progress streak: ${summary.noProgressStreak ?? persisted?.noProgressStreak ?? 0}`;
+      })
+      .join("\n");
+    const lastSummary = summaries[summaries.length - 1];
+    const lastFeedback = summarizeLastIterationFeedback(lastSummary, persisted?.noProgressStreak ?? 0);
+    const taskDirLabel = persisted?.taskDir ? displayPath(persisted.cwd ?? persisted.taskDir, persisted.taskDir) : "the Ralph task directory";
+    appendLoopProofEntry("ralph-steering-injected", {
+      loopToken: persisted?.loopToken,
+      iteration: persisted?.iteration,
+      maxIterations: persisted?.maxIterations,
+      taskDir: taskDirLabel,
+    });
+    appendLoopProofEntry("ralph-loop-context-injected", {
+      loopToken: persisted?.loopToken,
+      iteration: persisted?.iteration,
+      maxIterations: persisted?.maxIterations,
+      taskDir: taskDirLabel,
+      summaryCount: summaries.length,
+    });
+
     return {
       systemPrompt:
         event.systemPrompt +
-        `\n\n## Ralph Loop Context\nIteration ${persisted?.iteration ?? 0}/${persisted?.maxIterations ?? 0}\n\nPrevious iterations:\n${history}\n\nDo not repeat completed work. Check git log for recent changes.`,
+        `\n\n## Ralph Loop Context\nIteration ${persisted?.iteration ?? 0}/${persisted?.maxIterations ?? 0}\nTask directory: ${taskDirLabel}\n\nPrevious iterations:\n${history}\n\n${lastFeedback}\nPersist findings to files in the Ralph task directory. Do not only report them in chat. If you make progress this iteration, leave durable file changes and mention the changed paths.\nDo not repeat completed work. Check git log for recent changes.`,
     };
   });
 
-  pi.on("tool_result", async (event: any, ctx: any) => {
-    if (!isLoopSession(ctx) || event.toolName !== "bash") return;
-    const output = event.content.map((c: { type: string; text?: string }) => (c.type === "text" ? c.text ?? "" : "")).join("");
-    if (!/FAIL|ERROR|error:|failed/i.test(output)) return;
+  pi.on("tool_result", async (event: ToolResultEvent, ctx: EventContext) => {
+    const persisted = resolveActiveLoopState(ctx);
+    if (!persisted) return;
+
+    if (event.toolName !== "bash") return;
+    const output = event.content.map((c) => (c.type === "text" ? c.text ?? "" : "")).join("");
+    if (!shouldWarnForBashFailure(output)) return;
 
-    const sessionFile = ctx.sessionManager.getSessionFile();
-    if (!sessionFile) return;
+    const state = resolveActiveIterationState(ctx);
+    if (!state) return;
 
-    const next = (failCounts.get(sessionFile) ?? 0) + 1;
-    failCounts.set(sessionFile, next);
+    const failKey = getLoopIterationKey(state.loopToken, state.iteration);
+    const next = (failCounts.get(failKey) ?? 0) + 1;
+    failCounts.set(failKey, next);
     if (next >= 3) {
       return {
         content: [
@@ -220,179 +1369,115 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.registerCommand("ralph", {
-    description: "Start an autonomous ralph loop from a RALPH.md file",
-    handler: async (args: string, ctx: any) => {
+    description: "Start Ralph from a task folder or RALPH.md",
+    handler: async (args: string, ctx: CommandContext) => {
       if (loopState.active) {
         ctx.ui.notify("A ralph loop is already running. Use /ralph-stop first.", "warning");
         return;
       }
 
-      let name: string;
-      try {
-        const ralphPath = resolveRalphPath(args ?? "", ctx.cwd);
-        const { frontmatter } = parseRalphMd(ralphPath);
-        if (!validateFrontmatter(frontmatter, ctx)) return;
-        name = basename(dirname(ralphPath));
-        loopState = {
-          active: true,
-          ralphPath,
-          iteration: 0,
-          maxIterations: frontmatter.maxIterations,
-          timeout: frontmatter.timeout,
-          completionPromise: frontmatter.completionPromise,
-          stopRequested: false,
-          iterationSummaries: [],
-          guardrails: { blockCommands: frontmatter.guardrails.blockCommands, protectedFiles: frontmatter.guardrails.protectedFiles },
-          loopSessionFile: undefined,
-        };
-      } catch (err) {
-        ctx.ui.notify(String(err), "error");
-        return;
-      }
-      ctx.ui.notify(`Ralph loop started: ${name} (max ${loopState.maxIterations} iterations)`, "info");
+      const ralphPath = await handleDraftCommand("ralph", args ?? "", ctx);
+      if (!ralphPath) return;
+      await startRalphLoop(ralphPath, ctx, services.runRalphLoopFn, runtimeArgsForStart);
+    },
+  });
 
-      try {
-        iterationLoop: for (let i = 1; i <= loopState.maxIterations; i++) {
-          if (loopState.stopRequested) break;
-          const persistedBefore = readPersistedLoopState(ctx);
-          if (persistedBefore?.active && persistedBefore.stopRequested) {
-            loopState.stopRequested = true;
-            ctx.ui.notify("Ralph loop stopping after current iteration…", "info");
-            break;
-          }
+  pi.registerCommand("ralph-draft", {
+    description: "Draft a Ralph task without starting it",
+    handler: async (args: string, ctx: CommandContext) => {
+      await handleDraftCommand("ralph-draft", args ?? "", ctx);
+    },
+  });
 
-          loopState.iteration = i;
-          const iterStart = Date.now();
-          const { frontmatter: fm, body: rawBody } = parseRalphMd(loopState.ralphPath);
-          if (!validateFrontmatter(fm, ctx)) {
-            ctx.ui.notify(`Invalid RALPH.md on iteration ${i}, stopping loop`, "error");
-            break;
-          }
+  pi.registerCommand("ralph-stop", {
+    description: "Stop the ralph loop after the current iteration",
+    handler: async (args: string, ctx: CommandContext) => {
+      const parsed = parseCommandArgs(args ?? "");
+      if (parsed.error) {
+        ctx.ui.notify(parsed.error, "error");
+        return;
+      }
+      if (parsed.mode === "task") {
+        ctx.ui.notify("/ralph-stop expects a task folder or RALPH.md path, not task text.", "error");
+        return;
+      }
 
-          loopState.maxIterations = fm.maxIterations;
-          loopState.timeout = fm.timeout;
-          loopState.completionPromise = fm.completionPromise;
-          loopState.guardrails = { blockCommands: fm.guardrails.blockCommands, protectedFiles: fm.guardrails.protectedFiles };
-
-          const outputs = await runCommands(fm.commands, pi);
-          let body = resolvePlaceholders(rawBody, outputs, { iteration: i, name });
-          body = body.replace(/<!--[\s\S]*?-->/g, "");
-          const prompt = `[ralph: iteration ${i}/${loopState.maxIterations}]\n\n${body}`;
-
-          const prevPersisted = readPersistedLoopState(ctx);
-          if (prevPersisted?.active && prevPersisted.sessionFile === ctx.sessionManager.getSessionFile()) persistLoopState(pi, { ...prevPersisted, active: false });
-          ctx.ui.setStatus("ralph", `🔁 ${name}: iteration ${i}/${loopState.maxIterations}`);
-          const prevSessionFile = loopState.loopSessionFile;
-          const { cancelled } = await ctx.newSession();
-          if (cancelled) {
-            ctx.ui.notify("Session switch cancelled, stopping loop", "warning");
-            break;
-          }
+      const now = new Date().toISOString();
+      const activeRegistryEntries = () => listActiveLoopRegistryEntries(ctx.cwd);
+      const { target: sessionTarget, persistedSessionState } = resolveSessionStopTarget(ctx, now);
 
-          loopState.loopSessionFile = ctx.sessionManager.getSessionFile();
-          if (prevSessionFile && prevSessionFile !== loopState.loopSessionFile) failCounts.delete(prevSessionFile);
-          if (loopState.loopSessionFile) failCounts.set(loopState.loopSessionFile, 0);
-          persistLoopState(pi, {
-            active: true,
-            sessionFile: loopState.loopSessionFile,
-            iteration: loopState.iteration,
-            maxIterations: loopState.maxIterations,
-            iterationSummaries: loopState.iterationSummaries,
-            guardrails: { blockCommands: loopState.guardrails.blockCommands, protectedFiles: loopState.guardrails.protectedFiles },
-            stopRequested: false,
-          });
+      if (sessionTarget && !parsed.value) {
+        applyStopTarget(pi, ctx, sessionTarget, now, persistedSessionState);
+        return;
+      }
 
-          pi.sendUserMessage(prompt);
-          const timeoutMs = fm.timeout * 1000;
-          let timedOut = false;
-          let idleError: Error | undefined;
-          let timer: ReturnType<typeof setTimeout> | undefined;
-          try {
-            await Promise.race([
-              ctx.waitForIdle().catch((e: any) => {
-                idleError = e instanceof Error ? e : new Error(String(e));
-                throw e;
-              }),
-              new Promise<never>((_, reject) => {
-                timer = setTimeout(() => {
-                  timedOut = true;
-                  reject(new Error("timeout"));
-                }, timeoutMs);
-              }),
-            ]);
-          } catch {
-            // timedOut is set by timer; idleError means waitForIdle failed
+      if (parsed.value) {
+        const inspection = inspectExistingTarget(parsed.value, ctx.cwd, true);
+        if (inspection.kind !== "run") {
+          if (inspection.kind === "invalid-markdown") {
+            ctx.ui.notify(`Only task folders or RALPH.md can be stopped directly. ${displayPath(ctx.cwd, inspection.path)} is not stoppable.`, "error");
+            return;
           }
-          if (timer) clearTimeout(timer);
-          if (timedOut) {
-            ctx.ui.notify(`Iteration ${i} timed out after ${fm.timeout}s, stopping loop`, "warning");
-            break;
+          if (inspection.kind === "invalid-target") {
+            ctx.ui.notify(`Only task folders or RALPH.md can be stopped directly. ${displayPath(ctx.cwd, inspection.path)} is a file, not a task folder.`, "error");
+            return;
           }
-          if (idleError) {
-            ctx.ui.notify(`Iteration ${i} agent error: ${idleError.message}, stopping loop`, "error");
-            break;
+          if (inspection.kind === "dir-without-ralph" || inspection.kind === "missing-path") {
+            ctx.ui.notify(`No active ralph loop found at ${displayPath(ctx.cwd, inspection.dirPath)}.`, "warning");
+            return;
           }
+          ctx.ui.notify("/ralph-stop expects a task folder or RALPH.md path.", "error");
+          return;
+        }
 
-          const elapsed = Math.round((Date.now() - iterStart) / 1000);
-          loopState.iterationSummaries.push({ iteration: i, duration: elapsed });
-          pi.appendEntry("ralph-iteration", { iteration: i, duration: elapsed, ralphPath: loopState.ralphPath });
+        const taskDir = dirname(inspection.ralphPath);
+        if (sessionTarget && sessionTarget.taskDir === taskDir) {
+          applyStopTarget(pi, ctx, sessionTarget, now, persistedSessionState);
+          return;
+        }
 
-          const persistedAfter = readPersistedLoopState(ctx);
-          if (persistedAfter?.active && persistedAfter.stopRequested) {
-            loopState.stopRequested = true;
-            ctx.ui.notify("Ralph loop stopping after current iteration…", "info");
-            break;
-          }
+        const registryTarget = activeRegistryEntries().find((entry) => entry.taskDir === taskDir || entry.ralphPath === inspection.ralphPath);
+        if (registryTarget) {
+          applyStopTarget(pi, ctx, materializeRegistryStopTarget(registryTarget), now);
+          return;
+        }
 
-          if (fm.completionPromise) {
-            const entries = ctx.sessionManager.getEntries();
-            for (const entry of entries) {
-              if (entry.type === "message" && entry.message?.role === "assistant") {
-                const text = entry.message.content?.filter((b: any) => b.type === "text")?.map((b: any) => b.text)?.join("") ?? "";
-                const match = text.match(/<promise>([^<]+)<\/promise>/);
-                if (match && fm.completionPromise && match[1].trim() === fm.completionPromise.trim()) {
-                  ctx.ui.notify(`Completion promise matched on iteration ${i}`, "info");
-                  break iterationLoop;
-                }
-              }
-            }
+        const statusFile = readStatusFile(taskDir);
+        if (
+          statusFile &&
+          (statusFile.status === "running" || statusFile.status === "initializing") &&
+          typeof statusFile.cwd === "string" &&
+          statusFile.cwd.length > 0
+        ) {
+          const statusRegistryTarget = listActiveLoopRegistryEntries(statusFile.cwd).find(
+            (entry) => entry.taskDir === taskDir && entry.loopToken === statusFile.loopToken,
+          );
+          if (statusRegistryTarget) {
+            applyStopTarget(pi, ctx, materializeRegistryStopTarget(statusRegistryTarget), now);
+            return;
           }
-
-          ctx.ui.notify(`Iteration ${i} complete (${elapsed}s)`, "info");
         }
 
-        const total = loopState.iterationSummaries.reduce((a, s) => a + s.duration, 0);
-        ctx.ui.notify(`Ralph loop done: ${loopState.iteration} iterations, ${total}s total`, "info");
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        ctx.ui.notify(`Ralph loop failed: ${message}`, "error");
-      } finally {
-        failCounts.clear();
-        loopState.active = false;
-        loopState.stopRequested = false;
-        loopState.loopSessionFile = undefined;
-        ctx.ui.setStatus("ralph", undefined);
-        persistLoopState(pi, { active: false });
+        ctx.ui.notify(`No active ralph loop found at ${displayPath(ctx.cwd, inspection.ralphPath)}.`, "warning");
+        return;
       }
-    },
-  });
 
-  pi.registerCommand("ralph-stop", {
-    description: "Stop the ralph loop after the current iteration",
-    handler: async (_args: string, ctx: any) => {
-      const persisted = readPersistedLoopState(ctx);
-      if (!persisted?.active) {
-        if (!loopState.active) {
-          ctx.ui.notify("No active ralph loop", "warning");
-          return;
-        }
-        loopState.stopRequested = true;
-        ctx.ui.notify("Ralph loop stopping after current iteration…", "info");
+      if (sessionTarget) {
+        applyStopTarget(pi, ctx, sessionTarget, now, persistedSessionState);
         return;
       }
-      loopState.stopRequested = true;
-      persistLoopState(pi, { ...persisted, stopRequested: true });
-      ctx.ui.notify("Ralph loop stopping after current iteration…", "info");
+
+      const activeEntries = activeRegistryEntries();
+      if (activeEntries.length === 0) {
+        ctx.ui.notify("No active ralph loops found.", "warning");
+        return;
+      }
+      if (activeEntries.length > 1) {
+        ctx.ui.notify("Multiple active ralph loops found. Use /ralph-stop --path <task folder or RALPH.md> for an explicit target path.", "error");
+        return;
+      }
+
+      applyStopTarget(pi, ctx, materializeRegistryStopTarget(activeEntries[0]), now);
     },
   });
 }