@lnilluv/pi-ralph-loop 0.1.1 → 0.2.0

package/.github/workflows/release.yml

@@ -24,10 +24,10 @@ jobs:
         with:
           fetch-depth: 0
 
-      - name: Setup Node.js 22
+      - name: Setup Node.js 24
         uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af
         with:
-          node-version: 22
+          node-version: 24
           registry-url: https://registry.npmjs.org
 
       - name: Install dependencies

package/README.md

@@ -41,6 +41,8 @@ commands:
     run: npm run lint
     timeout: 60
 max_iterations: 25
+timeout: 300
+completion_promise: "DONE"
 guardrails:
   block_commands:
     - "rm\\s+-rf\\s+/"
@@ -51,12 +53,15 @@ guardrails:
 ---
 You are fixing flaky tests in the auth module.
 
+<!-- This comment is stripped before sending to the agent -->
+
 Latest test output:
 {{ commands.tests }}
 
 Latest lint output:
 {{ commands.lint }}
 
+Iteration {{ ralph.iteration }} of {{ ralph.name }}.
 Apply the smallest safe fix and explain why it works.
 ```
 
@@ -67,9 +72,21 @@ Apply the smallest safe fix and explain why it works.
 | `commands[].run` | string | required | Shell command |
 | `commands[].timeout` | number | `60` | Seconds before kill |
 | `max_iterations` | number | `50` | Stop after N iterations |
+| `timeout` | number | `300` | Per-iteration timeout in seconds; stops the loop if the agent is stuck |
+| `completion_promise` | string | — | Agent signals completion by sending `<promise>DONE</promise>`; loop breaks on match |
 | `guardrails.block_commands` | string[] | `[]` | Regex patterns to block in bash |
 | `guardrails.protected_files` | string[] | `[]` | Glob patterns to block writes |
 
+### Placeholders
+
+| Placeholder | Description |
+|-------------|-------------|
+| `{{ commands.<name> }}` | Output from the named command |
+| `{{ ralph.iteration }}` | Current 1-based iteration number |
+| `{{ ralph.name }}` | Directory name containing the RALPH.md |
+
+HTML comments (`<!-- ... -->`) are stripped from the prompt body after placeholder resolution, so you can annotate your RALPH.md freely.
+
 ## Commands
 
 - `/ralph <path>`: Start the loop from a `RALPH.md` file or directory.
@@ -79,7 +96,7 @@ Apply the smallest safe fix and explain why it works.
 
 ### Guardrails
 
-`guardrails.block_commands` and `guardrails.protected_files` come from RALPH frontmatter. The extension enforces them in the `tool_call` hook. Matching bash commands are blocked, and writes/edits to protected file globs are denied.
+`guardrails.block_commands` and `guardrails.protected_files` come from RALPH frontmatter. The extension enforces them in the `tool_call` hook — but only for sessions created by the loop, so they don't leak into unrelated conversations. Matching bash commands are blocked, and writes/edits to protected file globs are denied.
 
 ### Cross-iteration memory
 
@@ -89,6 +106,18 @@ After each iteration, the extension stores a short summary with iteration number
 
 In the `tool_result` hook, bash outputs are scanned for failure patterns. After three or more failures in the same iteration, the extension appends a stop-and-think warning to push root-cause analysis before another retry.
 
+### Completion promise
+
+When `completion_promise` is set (e.g., `"DONE"`), the loop scans the agent's messages for `<promise>DONE</promise>` after each iteration. If found, the loop stops early — the agent signals it's finished rather than relying solely on `max_iterations`.
+
+### Iteration timeout
+
+Each iteration has a configurable timeout (default 300 seconds). If the agent is stuck and doesn't become idle within the timeout, the loop stops with a warning. This prevents runaway iterations from running forever.
+
+### Input validation
+
+The extension validates `RALPH.md` frontmatter before starting and on each re-parse: `max_iterations` must be a positive integer, `timeout` must be positive, `block_commands` regexes must compile, and commands must have non-empty names and run strings with positive timeouts.
+
 ## Comparison table
 
 | Feature | **@lnilluv/pi-ralph-loop** | pi-ralph | pi-ralph-wiggum | ralphi | ralphify |
@@ -99,8 +128,13 @@ In the `tool_result` hook, bash outputs are scanned for failure patterns. After
 | Cross-iteration memory | ✓ | ✗ | ✗ | ✗ | ✗ |
 | Mid-turn steering | ✓ | ✗ | ✗ | ✗ | ✗ |
 | Live prompt editing | ✓ | ✗ | ✗ | ✗ | ✓ |
+| Completion promise | ✓ | ✗ | ✗ | ✗ | ✓ |
+| Iteration timeout | ✓ | ✗ | ✗ | ✗ | ✗ |
+| Session-scoped hooks | ✓ | ✗ | ✗ | ✗ | ✗ |
+| Input validation | ✓ | ✗ | ✗ | ✗ | ✗ |
 | Setup required | RALPH.md | config | RALPH.md | PRD pipeline | RALPH.md |
 
 ## License
 
 MIT
+# CI provenance test

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lnilluv/pi-ralph-loop",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Pi-native ralph loop — autonomous coding iterations with mid-turn supervision",
   "type": "module",
   "pi": {

package/src/index.ts

@@ -4,64 +4,102 @@ import { readFileSync, existsSync } from "node:fs";
 import { resolve, join, dirname, basename } from "node:path";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 
-// --- Types ---
-
 type CommandDef = { name: string; run: string; timeout: number };
-
 type Frontmatter = {
   commands: CommandDef[];
   maxIterations: number;
+  timeout: number;
+  completionPromise?: string;
   guardrails: { blockCommands: string[]; protectedFiles: string[] };
 };
-
 type ParsedRalph = { frontmatter: Frontmatter; body: string };
 type CommandOutput = { name: string; output: string };
-
 type LoopState = {
   active: boolean;
   ralphPath: string;
   iteration: number;
   maxIterations: number;
+  timeout: number;
+  completionPromise?: string;
   stopRequested: boolean;
-  failCount: number;
   iterationSummaries: Array<{ iteration: number; duration: number }>;
-  guardrails: { blockCommands: RegExp[]; protectedFiles: string[] };
+  guardrails: { blockCommands: string[]; protectedFiles: string[] };
+  loopSessionFile?: string;
+};
+type PersistedLoopState = {
+  active: boolean;
+  sessionFile?: string;
+  iteration?: number;
+  maxIterations?: number;
+  iterationSummaries?: Array<{ iteration: number; duration: number }>;
+  guardrails?: { blockCommands: string[]; protectedFiles: string[] };
+  stopRequested?: boolean;
 };
-
-// --- Parsing ---
 
 function defaultFrontmatter(): Frontmatter {
-  return { commands: [], maxIterations: 50, guardrails: { blockCommands: [], protectedFiles: [] } };
+  return { commands: [], maxIterations: 50, timeout: 300, guardrails: { blockCommands: [], protectedFiles: [] } };
 }
 
 function parseRalphMd(filePath: string): ParsedRalph {
-  const raw = readFileSync(filePath, "utf8");
-  const match = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  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 yaml = parseYaml(match[1]) ?? {};
+  const yaml = (parseYaml(match[1]) ?? {}) as Record<string, any>;
   const commands: CommandDef[] = Array.isArray(yaml.commands)
-    ? yaml.commands.map((c: Record<string, unknown>) => ({
-        name: String(c.name ?? ""),
-        run: String(c.run ?? ""),
-        timeout: Number(c.timeout ?? 60),
-      }))
+    ? 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>;
 
-  const guardrails = yaml.guardrails ?? {};
   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 : [],
-        protectedFiles: Array.isArray(guardrails.protected_files) ? guardrails.protected_files : [],
+        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],
+    body: match[2] ?? "",
   };
 }
 
+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");
+    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);
@@ -70,201 +108,290 @@ function resolveRalphPath(args: string, cwd: string): string {
   throw new Error(`No RALPH.md found at ${abs}`);
 }
 
-function resolvePlaceholders(body: string, outputs: CommandOutput[]): string {
+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) ?? "");
+  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);
 }
 
-function parseGuardrails(fm: Frontmatter): LoopState["guardrails"] {
-  return {
-    blockCommands: fm.guardrails.blockCommands.map((p) => new RegExp(p)),
-    protectedFiles: fm.guardrails.protectedFiles,
-  };
-}
-
-// --- Command execution ---
-
-async function runCommands(
-  commands: CommandDef[],
-  cwd: string,
-  pi: ExtensionAPI,
-): Promise<CommandOutput[]> {
+async function runCommands(commands: CommandDef[], pi: ExtensionAPI): Promise<CommandOutput[]> {
   const results: CommandOutput[] = [];
   for (const cmd of commands) {
     try {
       const result = await pi.exec("bash", ["-c", cmd.run], { timeout: cmd.timeout * 1000 });
-      results.push({
-        name: cmd.name,
-        output: (result.stdout + result.stderr).trim(),
-      });
-    } catch {
-      results.push({ name: cmd.name, output: `[timed out after ${cmd.timeout}s]` });
+      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}]` });
     }
   }
   return results;
 }
 
-// --- Extension ---
-
-let loopState: LoopState = {
-  active: false,
-  ralphPath: "",
-  iteration: 0,
-  maxIterations: 50,
-  stopRequested: false,
-  failCount: 0,
-  iterationSummaries: [],
-  guardrails: { blockCommands: [], protectedFiles: [] },
-};
+function defaultLoopState(): LoopState {
+  return { active: false, ralphPath: "", iteration: 0, maxIterations: 50, timeout: 300, completionPromise: undefined, stopRequested: false, iterationSummaries: [], guardrails: { blockCommands: [], protectedFiles: [] }, loopSessionFile: undefined };
+}
+
+function readPersistedLoopState(ctx: any): PersistedLoopState | undefined {
+  const entries = ctx.sessionManager.getEntries();
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i];
+    if (entry.type === "custom" && entry.customType === "ralph-loop-state") {
+      return typeof entry.data === "object" && entry.data ? (entry.data as PersistedLoopState) : undefined;
+    }
+  }
+  return undefined;
+}
+
+function persistLoopState(pi: ExtensionAPI, data: PersistedLoopState) {
+  pi.appendEntry("ralph-loop-state", data);
+}
+
+let loopState: LoopState = defaultLoopState();
 
 export default function (pi: ExtensionAPI) {
-  // Guardrails: block dangerous tool calls during loop
-  pi.on("tool_call", async (event) => {
-    if (!loopState.active) return;
+  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;
+  };
+
+  pi.on("tool_call", async (event: any, ctx: any) => {
+    if (!isLoopSession(ctx)) return;
+    const persisted = readPersistedLoopState(ctx);
+    if (!persisted) return;
 
     if (event.toolName === "bash") {
       const cmd = (event.input as { command?: string }).command ?? "";
-      for (const pattern of loopState.guardrails.blockCommands) {
-        if (pattern.test(cmd)) {
-          return { block: true, reason: `ralph: blocked (${pattern.source})` };
+      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
         }
       }
     }
 
     if (event.toolName === "write" || event.toolName === "edit") {
       const filePath = (event.input as { path?: string }).path ?? "";
-      for (const glob of loopState.guardrails.protectedFiles) {
-        if (minimatch(filePath, glob, { matchBase: true })) {
-          return { block: true, reason: `ralph: ${filePath} is protected` };
-        }
+      for (const glob of persisted.guardrails?.protectedFiles ?? []) {
+        if (minimatch(filePath, glob, { matchBase: true })) return { block: true, reason: `ralph: ${filePath} is protected` };
       }
     }
   });
 
-  // Cross-iteration memory: inject context into system prompt
-  pi.on("before_agent_start", async (event) => {
-    if (!loopState.active || loopState.iterationSummaries.length === 0) return;
-
-    const history = loopState.iterationSummaries
-      .map((s) => `- Iteration ${s.iteration}: ${s.duration}s`)
-      .join("\n");
+  pi.on("before_agent_start", async (event: any, ctx: any) => {
+    if (!isLoopSession(ctx)) return;
+    const persisted = readPersistedLoopState(ctx);
+    const summaries = persisted?.iterationSummaries ?? [];
+    if (summaries.length === 0) return;
 
+    const history = summaries.map((s) => `- Iteration ${s.iteration}: ${s.duration}s`).join("\n");
     return {
       systemPrompt:
         event.systemPrompt +
-        `\n\n## Ralph Loop Context\nIteration ${loopState.iteration}/${loopState.maxIterations}\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}\n\nPrevious iterations:\n${history}\n\nDo not repeat completed work. Check git log for recent changes.`,
     };
   });
 
-  // Mid-turn steering: warn after repeated failures
-  pi.on("tool_result", async (event) => {
-    if (!loopState.active || event.toolName !== "bash") return;
+  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;
 
-    const output = event.content
-      .map((c: { type: string; text?: string }) => (c.type === "text" ? c.text ?? "" : ""))
-      .join("");
+    const sessionFile = ctx.sessionManager.getSessionFile();
+    if (!sessionFile) return;
 
-    if (/FAIL|ERROR|error:|failed/i.test(output)) {
-      loopState.failCount++;
-    }
-
-    if (loopState.failCount >= 3) {
+    const next = (failCounts.get(sessionFile) ?? 0) + 1;
+    failCounts.set(sessionFile, next);
+    if (next >= 3) {
       return {
         content: [
           ...event.content,
-          {
-            type: "text" as const,
-            text: "\n\n⚠️ ralph: 3+ failures this iteration. Stop and describe the root cause before retrying.",
-          },
+          { type: "text" as const, text: "\n\n⚠️ ralph: 3+ failures this iteration. Stop and describe the root cause before retrying." },
         ],
       };
     }
   });
 
-  // /ralph command: start the loop
   pi.registerCommand("ralph", {
     description: "Start an autonomous ralph loop from a RALPH.md file",
-    handler: async (args, ctx) => {
+    handler: async (args: string, ctx: any) => {
       if (loopState.active) {
         ctx.ui.notify("A ralph loop is already running. Use /ralph-stop first.", "warning");
         return;
       }
 
-      let ralphPath: string;
+      let name: string;
       try {
-        ralphPath = resolveRalphPath(args ?? "", ctx.cwd);
+        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;
       }
-
-      const { frontmatter } = parseRalphMd(ralphPath);
-      loopState = {
-        active: true,
-        ralphPath,
-        iteration: 0,
-        maxIterations: frontmatter.maxIterations,
-        stopRequested: false,
-        failCount: 0,
-        iterationSummaries: [],
-        guardrails: parseGuardrails(frontmatter),
-      };
-
-      const name = basename(dirname(ralphPath));
       ctx.ui.notify(`Ralph loop started: ${name} (max ${loopState.maxIterations} iterations)`, "info");
 
-      for (let i = 1; i <= loopState.maxIterations; i++) {
-        if (loopState.stopRequested) break;
-
-        loopState.iteration = i;
-        loopState.failCount = 0;
-        const iterStart = Date.now();
-
-        // Re-parse every iteration (live editing support)
-        const { frontmatter: fm, body } = parseRalphMd(loopState.ralphPath);
-        loopState.maxIterations = fm.maxIterations;
-        loopState.guardrails = parseGuardrails(fm);
-
-        // Run commands and resolve placeholders
-        const outputs = await runCommands(fm.commands, ctx.cwd, pi);
-        const header = `[ralph: iteration ${i}/${loopState.maxIterations}]\n\n`;
-        const prompt = header + resolvePlaceholders(body, outputs);
-
-        // Fresh session
-        ctx.ui.setStatus("ralph", `🔁 ${name}: iteration ${i}/${loopState.maxIterations}`);
-        await ctx.newSession();
-
-        // Send prompt and wait for agent to finish
-        pi.sendUserMessage(prompt);
-        await ctx.waitForIdle();
-
-        // Record iteration
-        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 });
+      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;
+          }
+
+          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;
+          }
+
+          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;
+          }
+
+          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,
+          });
+
+          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 (timer) clearTimeout(timer);
+          if (timedOut) {
+            ctx.ui.notify(`Iteration ${i} timed out after ${fm.timeout}s, stopping loop`, "warning");
+            break;
+          }
+          if (idleError) {
+            ctx.ui.notify(`Iteration ${i} agent error: ${idleError.message}, stopping loop`, "error");
+            break;
+          }
+
+          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 persistedAfter = readPersistedLoopState(ctx);
+          if (persistedAfter?.active && persistedAfter.stopRequested) {
+            loopState.stopRequested = true;
+            ctx.ui.notify("Ralph loop stopping after current iteration…", "info");
+            break;
+          }
+
+          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;
+                }
+              }
+            }
+          }
+
+          ctx.ui.notify(`Iteration ${i} complete (${elapsed}s)`, "info");
+        }
 
-        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 });
       }
-
-      loopState.active = false;
-      ctx.ui.setStatus("ralph", undefined);
-      const total = loopState.iterationSummaries.reduce((a, s) => a + s.duration, 0);
-      ctx.ui.notify(
-        `Ralph loop done: ${loopState.iteration} iterations, ${total}s total`,
-        "info",
-      );
     },
   });
 
-  // /ralph-stop command: graceful stop
   pi.registerCommand("ralph-stop", {
     description: "Stop the ralph loop after the current iteration",
-    handler: async (_args, ctx) => {
-      if (!loopState.active) {
-        ctx.ui.notify("No active ralph loop", "warning");
+    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");
         return;
       }
       loopState.stopRequested = true;
+      persistLoopState(pi, { ...persisted, stopRequested: true });
       ctx.ui.notify("Ralph loop stopping after current iteration…", "info");
     },
   });

package/src/shims.d.ts

@@ -0,0 +1,23 @@
+declare module "yaml" {
+  export function parse(input: string): any;
+}
+
+declare module "minimatch" {
+  export function minimatch(path: string, pattern: string, options?: any): boolean;
+}
+
+declare module "node:fs" {
+  export function readFileSync(path: string, encoding: string): string;
+  export function existsSync(path: string): boolean;
+}
+
+declare module "node:path" {
+  export function resolve(...paths: string[]): string;
+  export function join(...paths: string[]): string;
+  export function dirname(path: string): string;
+  export function basename(path: string): string;
+}
+
+declare module "@mariozechner/pi-coding-agent" {
+  export type ExtensionAPI = any;
+}