@lnilluv/pi-ralph-loop 1.0.0 → 1.2.0

package/src/runner.ts

@@ -21,9 +21,12 @@ import {
   type RunnerStatusFile,
   appendIterationRecord,
   appendRunnerEvent,
+  checkCancelSignal,
   checkStopSignal,
+  clearCancelSignal,
   clearRunnerDir,
   clearStopSignal,
+  createCancelSignal,
   ensureRunnerDir,
   readActiveLoopRegistry,
   readIterationRecords,
@@ -52,6 +55,8 @@ export type RunnerConfig = {
   cwd: string;
   timeout: number;
   maxIterations: number;
+  /** Error policy: true = stop on error (default), false = continue on error */
+  stopOnError?: boolean;
   /** Completion promise string from RALPH.md */
   completionPromise?: string;
   guardrails: { blockCommands: string[]; protectedFiles: string[] };
@@ -412,6 +417,7 @@ export async function runRalphLoop(config: RunnerConfig): Promise<RunnerResult>
     pi,
     runtimeArgs: initialRuntimeArgs = {},
   } = config;
+  let currentStopOnError = config.stopOnError ?? true;
   const runtimeArgs = initialRuntimeArgs;
 
   const taskDir = dirname(ralphPath);
@@ -495,6 +501,13 @@ export async function runRalphLoop(config: RunnerConfig): Promise<RunnerResult>
         break;
       }
 
+      if (checkCancelSignal(taskDir)) {
+        recordActiveLoopStopObservation(cwd, taskDir, new Date().toISOString());
+        clearCancelSignal(taskDir);
+        finalStatus = "cancelled";
+        break;
+      }
+
       // Re-parse RALPH.md every iteration (live editing support)
       if (!existsSync(ralphPath)) {
         onNotify?.(`RALPH.md not found at ${ralphPath}, stopping runner`, "error");
@@ -523,6 +536,7 @@ export async function runRalphLoop(config: RunnerConfig): Promise<RunnerResult>
       currentRequiredOutputs = fm.requiredOutputs ?? [];
       currentInterIterationDelay = fm.interIterationDelay;
       currentGuardrails = { blockCommands: fm.guardrails.blockCommands, protectedFiles: fm.guardrails.protectedFiles };
+      currentStopOnError = config.stopOnError ?? fm.stopOnError;
 
       // Update status to running
       const runningStatus: RunnerStatusFile = {
@@ -540,6 +554,7 @@ export async function runRalphLoop(config: RunnerConfig): Promise<RunnerResult>
       onIterationStart?.(i, currentMaxIterations);
 
       const iterStartMs = Date.now();
+      const iterationAbortController = new AbortController();
       const completionRecord = currentCompletionPromise ? createCompletionRecord() : undefined;
       logRunnerEvent(taskDir, {
         type: "iteration.started",
@@ -577,29 +592,75 @@ export async function runRalphLoop(config: RunnerConfig): Promise<RunnerResult>
       // Run RPC iteration
       onNotify?.(`Iteration ${i}/${currentMaxIterations} starting`, "info");
 
-      const rpcResult = await runRpcIteration({
-        prompt,
-        cwd,
-        timeoutMs: currentTimeout * 1000,
-        spawnCommand,
-        spawnArgs,
-        env: {
-          RALPH_RUNNER_TASK_DIR: taskDir,
-          RALPH_RUNNER_CWD: cwd,
-          RALPH_RUNNER_LOOP_TOKEN: loopToken,
-          RALPH_RUNNER_CURRENT_ITERATION: String(i),
-          RALPH_RUNNER_MAX_ITERATIONS: String(currentMaxIterations),
-          RALPH_RUNNER_NO_PROGRESS_STREAK: String(noProgressStreak),
-          RALPH_RUNNER_GUARDRAILS: JSON.stringify(currentGuardrails),
-        },
-        modelPattern: config.modelPattern,
-        provider: config.provider,
-        modelId: config.modelId,
-        thinkingLevel: config.thinkingLevel,
-      });
+      const cancelPollInterval = setInterval(() => {
+        if (checkCancelSignal(taskDir)) {
+          iterationAbortController.abort();
+        }
+      }, 500);
+
+      let rpcResult: RpcSubprocessResult;
+      try {
+        rpcResult = await runRpcIteration({
+          prompt,
+          cwd,
+          timeoutMs: currentTimeout * 1000,
+          spawnCommand,
+          spawnArgs,
+          env: {
+            RALPH_RUNNER_TASK_DIR: taskDir,
+            RALPH_RUNNER_CWD: cwd,
+            RALPH_RUNNER_LOOP_TOKEN: loopToken,
+            RALPH_RUNNER_CURRENT_ITERATION: String(i),
+            RALPH_RUNNER_MAX_ITERATIONS: String(currentMaxIterations),
+            RALPH_RUNNER_NO_PROGRESS_STREAK: String(noProgressStreak),
+            RALPH_RUNNER_GUARDRAILS: JSON.stringify(currentGuardrails),
+          },
+          modelPattern: config.modelPattern,
+          provider: config.provider,
+          modelId: config.modelId,
+          thinkingLevel: config.thinkingLevel,
+          signal: iterationAbortController.signal,
+        });
+      } finally {
+        clearInterval(cancelPollInterval);
+      }
 
       const iterEndMs = Date.now();
 
+      if (rpcResult.cancelled) {
+        const iterRecord: IterationRecord = {
+          iteration: i,
+          status: "cancelled",
+          startedAt: new Date(iterStartMs).toISOString(),
+          completedAt: new Date(iterEndMs).toISOString(),
+          durationMs: iterEndMs - iterStartMs,
+          progress: false,
+          changedFiles: [],
+          noProgressStreak: noProgressStreak + 1,
+          loopToken,
+          rpcTelemetry: rpcResult.telemetry,
+        };
+        iterations.push(iterRecord);
+        appendIterationRecord(taskDir, iterRecord);
+        writeIterationTranscriptSafe(iterRecord, rpcResult.lastAssistantText, "Iteration cancelled by operator");
+        logRunnerEvent(taskDir, {
+          type: "iteration.completed",
+          timestamp: new Date(iterEndMs).toISOString(),
+          iteration: i,
+          loopToken,
+          status: "cancelled",
+          progress: iterRecord.progress,
+          changedFiles: [],
+          noProgressStreak: iterRecord.noProgressStreak,
+          reason: "operator-cancel",
+        });
+        recordActiveLoopStopObservation(cwd, taskDir, new Date().toISOString());
+        clearCancelSignal(taskDir);
+        finalStatus = "cancelled";
+        onIterationComplete?.(iterRecord);
+        break;
+      }
+
       // Handle RPC failure
       if (!rpcResult.success) {
         const iterRecord: IterationRecord = {
@@ -639,13 +700,29 @@ export async function runRalphLoop(config: RunnerConfig): Promise<RunnerResult>
 
         if (rpcResult.timedOut) {
           onNotify?.(`Iteration ${i} timed out after ${currentTimeout}s`, "warning");
-          finalStatus = "timeout";
+          if (currentStopOnError) {
+            finalStatus = "timeout";
+            onIterationComplete?.(iterRecord);
+            break;
+          } else {
+            noProgressStreak += 1;
+            onNotify?.(`Continuing (stop_on_error=false).`, "warning");
+            onIterationComplete?.(iterRecord);
+            continue;
+          }
         } else {
           onNotify?.(`Iteration ${i} error: ${rpcResult.error ?? "unknown"}`, "error");
-          finalStatus = "error";
+          if (currentStopOnError) {
+            finalStatus = "error";
+            onIterationComplete?.(iterRecord);
+            break;
+          } else {
+            noProgressStreak += 1;
+            onNotify?.(`Continuing (stop_on_error=false).`, "warning");
+            onIterationComplete?.(iterRecord);
+            continue;
+          }
         }
-        onIterationComplete?.(iterRecord);
-        break;
       }
 
       // After snapshot
@@ -878,6 +955,14 @@ export async function runRalphLoop(config: RunnerConfig): Promise<RunnerResult>
 
       onNotify?.(`Iteration ${i} complete (${Math.round((iterEndMs - iterStartMs) / 1000)}s)`, "info");
 
+      // Quick cancel check before delay
+      if (checkCancelSignal(taskDir)) {
+        recordActiveLoopStopObservation(cwd, taskDir, new Date().toISOString());
+        clearCancelSignal(taskDir);
+        finalStatus = "cancelled";
+        break;
+      }
+
       if (i < currentMaxIterations && currentInterIterationDelay > 0) {
         const stoppedDuringDelay = await waitForInterIterationDelay(taskDir, cwd, currentInterIterationDelay);
         if (stoppedDuringDelay) {

package/tests/index.test.ts

@@ -1,11 +1,11 @@
 import assert from "node:assert/strict";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import test from "node:test";
-import registerRalphCommands, { runCommands } from "../src/index.ts";
+import registerRalphCommands, { parseLogExportArgs, runCommands } from "../src/index.ts";
 import { SECRET_PATH_POLICY_TOKEN } from "../src/secret-paths.ts";
-import { generateDraft, parseRalphMarkdown, slugifyTask, validateFrontmatter, type DraftPlan, type DraftTarget } from "../src/ralph.ts";
+import { generateDraft, inspectDraftContent, parseRalphMarkdown, slugifyTask, validateFrontmatter, type DraftPlan, type DraftTarget } from "../src/ralph.ts";
 import type { StrengthenDraftRuntime } from "../src/ralph-draft-llm.ts";
 import type { RunnerConfig, RunnerResult } from "../src/runner.ts";
 import { runRalphLoop as realRunRalphLoop, captureTaskDirectorySnapshot, assessTaskDirectoryProgress, summarizeChangedFiles } from "../src/runner.ts";
@@ -398,7 +398,7 @@ test("registerRalphCommands is idempotent for the same extension API instance",
   registerRalphCommands(pi, {} as any);
   registerRalphCommands(pi, {} as any);
 
-  assert.deepEqual(registeredCommands, ["ralph", "ralph-draft", "ralph-stop"]);
+  assert.deepEqual(registeredCommands, ["ralph", "ralph-draft", "ralph-stop", "ralph-cancel", "ralph-scaffold", "ralph-logs"]);
   assert.deepEqual(registeredEvents, [
     "tool_call",
     "tool_execution_start",
@@ -574,6 +574,462 @@ test("/ralph-stop writes the durable stop flag from persisted active loop state
   assert.equal(notifications.some(({ message }) => message.includes("No active ralph loop")), false);
 });
 
+test("/ralph-cancel writes the cancel flag from persisted active loop state after reload", async (t) => {
+  const cwd = createTempDir();
+  t.after(() => rmSync(cwd, { recursive: true, force: true }));
+
+  const taskDir = join(cwd, "persisted-loop-task");
+  mkdirSync(taskDir, { recursive: true });
+  const persistedState = {
+    active: true,
+    loopToken: "persisted-loop-token",
+    cwd,
+    taskDir,
+    iteration: 3,
+    maxIterations: 5,
+    noProgressStreak: 0,
+    iterationSummaries: [],
+    guardrails: { blockCommands: [], protectedFiles: [] },
+    stopRequested: false,
+  };
+  writeStatusFile(taskDir, {
+    loopToken: persistedState.loopToken,
+    ralphPath: join(taskDir, "RALPH.md"),
+    taskDir,
+    cwd,
+    status: "running",
+    currentIteration: 3,
+    maxIterations: 5,
+    timeout: 300,
+    startedAt: new Date().toISOString(),
+    guardrails: { blockCommands: [], protectedFiles: [] },
+  });
+  const notifications: Array<{ message: string; level: string }> = [];
+  const harness = createHarness();
+  const handler = harness.handler("ralph-cancel");
+  let ctx: any;
+  ctx = {
+    cwd,
+    hasUI: true,
+    ui: {
+      notify: (message: string, level: string) => notifications.push({ message, level }),
+      select: async () => undefined,
+      input: async () => undefined,
+      editor: async () => undefined,
+      setStatus: () => undefined,
+    },
+    sessionManager: createSessionManager([
+      {
+        type: "custom",
+        customType: "ralph-loop-state",
+        data: persistedState,
+      },
+    ], "session-a"),
+    getRuntimeCtx: () => ctx,
+  };
+
+  await handler("", ctx);
+
+  assert.equal(existsSync(join(taskDir, ".ralph-runner", "cancel.flag")), true);
+  assert.equal(existsSync(join(taskDir, ".ralph-runner", "stop.flag")), false);
+  assert.ok(notifications.some(({ message }) => message.includes("Cancel requested. The active iteration will be terminated immediately.")));
+  assert.equal(notifications.some(({ message }) => message.includes("No active ralph loop")), false);
+});
+
+test("/ralph-cancel refuses when the loop already finished", async (t) => {
+  const cwd = createTempDir();
+  t.after(() => rmSync(cwd, { recursive: true, force: true }));
+
+  const taskDir = join(cwd, "finished-loop-task");
+  mkdirSync(taskDir, { recursive: true });
+  writeStatusFile(taskDir, {
+    loopToken: "finished-loop-token",
+    ralphPath: join(taskDir, "RALPH.md"),
+    taskDir,
+    cwd,
+    status: "complete",
+    currentIteration: 3,
+    maxIterations: 5,
+    timeout: 300,
+    startedAt: new Date().toISOString(),
+    completedAt: new Date().toISOString(),
+    guardrails: { blockCommands: [], protectedFiles: [] },
+  });
+  const notifications: Array<{ message: string; level: string }> = [];
+  const harness = createHarness();
+  const handler = harness.handler("ralph-cancel");
+  let ctx: any;
+  ctx = {
+    cwd,
+    hasUI: true,
+    ui: {
+      notify: (message: string, level: string) => notifications.push({ message, level }),
+      select: async () => undefined,
+      input: async () => undefined,
+      editor: async () => undefined,
+      setStatus: () => undefined,
+    },
+    sessionManager: createSessionManager([
+      {
+        type: "custom",
+        customType: "ralph-loop-state",
+        data: {
+          active: true,
+          loopToken: "finished-loop-token",
+          cwd,
+          taskDir,
+          iteration: 3,
+          maxIterations: 5,
+          noProgressStreak: 0,
+          iterationSummaries: [],
+          guardrails: { blockCommands: [], protectedFiles: [] },
+          stopRequested: false,
+        },
+      },
+    ], "session-a"),
+    getRuntimeCtx: () => ctx,
+  };
+
+  await handler("", ctx);
+
+  assert.equal(existsSync(join(taskDir, ".ralph-runner", "cancel.flag")), false);
+  assert.ok(notifications.some(({ message, level }) => level === "warning" && message.includes("The loop already ended with status: complete.")));
+});
+
+test("/ralph-cancel refuses when no status.json exists", async (t) => {
+  const cwd = createTempDir();
+  t.after(() => rmSync(cwd, { recursive: true, force: true }));
+
+  const taskDir = join(cwd, "missing-status-task");
+  mkdirSync(taskDir, { recursive: true });
+  const notifications: Array<{ message: string; level: string }> = [];
+  const harness = createHarness();
+  const handler = harness.handler("ralph-cancel");
+  let ctx: any;
+  ctx = {
+    cwd,
+    hasUI: true,
+    ui: {
+      notify: (message: string, level: string) => notifications.push({ message, level }),
+      select: async () => undefined,
+      input: async () => undefined,
+      editor: async () => undefined,
+      setStatus: () => undefined,
+    },
+    sessionManager: createSessionManager([
+      {
+        type: "custom",
+        customType: "ralph-loop-state",
+        data: {
+          active: true,
+          loopToken: "missing-status-loop-token",
+          cwd,
+          taskDir,
+          iteration: 3,
+          maxIterations: 5,
+          noProgressStreak: 0,
+          iterationSummaries: [],
+          guardrails: { blockCommands: [], protectedFiles: [] },
+          stopRequested: false,
+        },
+      },
+    ], "session-a"),
+    getRuntimeCtx: () => ctx,
+  };
+
+  await handler("", ctx);
+
+  assert.equal(existsSync(join(taskDir, ".ralph-runner", "cancel.flag")), false);
+  assert.ok(notifications.some(({ message, level }) => level === "warning" && message.includes("No run data exists.")));
+});
+
+test("/ralph-scaffold creates a parseable scaffold from a task name", async (t) => {
+  const cwd = createTempDir();
+  t.after(() => rmSync(cwd, { recursive: true, force: true }));
+
+  const notifications: Array<{ message: string; level: string }> = [];
+  const harness = createHarness();
+  const handler = harness.handler("ralph-scaffold");
+  const ctx = {
+    cwd,
+    hasUI: true,
+    ui: {
+      notify: (message: string, level: string) => notifications.push({ message, level }),
+      select: async () => undefined,
+      input: async () => undefined,
+      editor: async () => undefined,
+      setStatus: () => undefined,
+    },
+    sessionManager: { getEntries: () => [], getSessionFile: () => "session-a" },
+  };
+
+  await handler("my-task", ctx);
+
+  const ralphPath = join(cwd, "my-task", "RALPH.md");
+  assert.equal(existsSync(ralphPath), true);
+  const inspection = inspectDraftContent(readFileSync(ralphPath, "utf8"));
+  assert.equal(inspection.error, undefined);
+  assert.equal(inspection.parsed?.frontmatter.maxIterations, 10);
+  assert.equal(inspection.parsed?.frontmatter.timeout, 120);
+  assert.deepEqual(inspection.parsed?.frontmatter.commands, []);
+  assert.ok(notifications.some(({ message, level }) => level === "info" && message.includes("Scaffolded")));
+});
+
+test("/ralph-scaffold accepts path-style arguments", async (t) => {
+  const cwd = createTempDir();
+  t.after(() => rmSync(cwd, { recursive: true, force: true }));
+
+  const harness = createHarness();
+  const handler = harness.handler("ralph-scaffold");
+  const ctx = {
+    cwd,
+    hasUI: true,
+    ui: {
+      notify: () => undefined,
+      select: async () => undefined,
+      input: async () => undefined,
+      editor: async () => undefined,
+      setStatus: () => undefined,
+    },
+    sessionManager: { getEntries: () => [], getSessionFile: () => "session-a" },
+  };
+
+  await handler("feature/new-task", ctx);
+
+  assert.equal(existsSync(join(cwd, "feature", "new-task", "RALPH.md")), true);
+});
+
+test("/ralph-scaffold rejects paths outside the current working directory", async (t) => {
+  const cwd = createTempDir();
+  t.after(() => rmSync(cwd, { recursive: true, force: true }));
+
+  const escapedTaskDir = join(cwd, "..", "escape");
+  t.after(() => rmSync(escapedTaskDir, { recursive: true, force: true }));
+
+  const notifications: Array<{ message: string; level: string }> = [];
+  const harness = createHarness();
+  const handler = harness.handler("ralph-scaffold");
+  const ctx = {
+    cwd,
+    hasUI: true,
+    ui: {
+      notify: (message: string, level: string) => notifications.push({ message, level }),
+      select: async () => undefined,
+      input: async () => undefined,
+      editor: async () => undefined,
+      setStatus: () => undefined,
+    },
+    sessionManager: { getEntries: () => [], getSessionFile: () => "session-a" },
+  };
+
+  await handler("../escape", ctx);
+
+  assert.equal(existsSync(join(escapedTaskDir, "RALPH.md")), false);
+  assert.deepEqual(notifications, [{ message: "Task path must be within the current working directory.", level: "error" }]);
+});
+
+test("/ralph-scaffold refuses to overwrite an existing RALPH.md", async (t) => {
+  const cwd = createTempDir();
+  t.after(() => rmSync(cwd, { recursive: true, force: true }));
+
+  const taskDir = join(cwd, "my-task");
+  mkdirSync(taskDir, { recursive: true });
+  const ralphPath = join(taskDir, "RALPH.md");
+  writeFileSync(ralphPath, "---\nmax_iterations: 10\ntimeout: 120\ncommands: []\n---\n# my-task\n", "utf8");
+
+  const notifications: Array<{ message: string; level: string }> = [];
+  const harness = createHarness();
+  const handler = harness.handler("ralph-scaffold");
+  const ctx = {
+    cwd,
+    hasUI: true,
+    ui: {
+      notify: (message: string, level: string) => notifications.push({ message, level }),
+      select: async () => undefined,
+      input: async () => undefined,
+      editor: async () => undefined,
+      setStatus: () => undefined,
+    },
+    sessionManager: { getEntries: () => [], getSessionFile: () => "session-a" },
+  };
+
+  await handler("my-task", ctx);
+
+  assert.equal(readFileSync(ralphPath, "utf8"), "---\nmax_iterations: 10\ntimeout: 120\ncommands: []\n---\n# my-task\n");
+  assert.ok(notifications.some(({ message, level }) => level === "error" && message.includes("already exists at")));
+});
+
+test("/ralph-scaffold requires a task name", async (t) => {
+  const cwd = createTempDir();
+  t.after(() => rmSync(cwd, { recursive: true, force: true }));
+
+  const notifications: Array<{ message: string; level: string }> = [];
+  const harness = createHarness();
+  const handler = harness.handler("ralph-scaffold");
+  const ctx = {
+    cwd,
+    hasUI: true,
+    ui: {
+      notify: (message: string, level: string) => notifications.push({ message, level }),
+      select: async () => undefined,
+      input: async () => undefined,
+      editor: async () => undefined,
+      setStatus: () => undefined,
+    },
+    sessionManager: { getEntries: () => [], getSessionFile: () => "session-a" },
+  };
+
+  await handler("   ", ctx);
+
+  assert.deepEqual(notifications, [{ message: "/ralph-scaffold expects a task name or path.", level: "error" }]);
+});
+
+test("/ralph-logs exports artifacts from a task with .ralph-runner/", async (t) => {
+  const cwd = createTempDir();
+  t.after(() => rmSync(cwd, { recursive: true, force: true }));
+
+  const taskDir = join(cwd, "my-task");
+  mkdirSync(join(taskDir, ".ralph-runner", "transcripts"), { recursive: true });
+  writeFileSync(join(taskDir, "RALPH.md"), "---\nmax_iterations: 10\ntimeout: 120\ncommands: []\n---\n# my-task\n", "utf8");
+  writeFileSync(join(taskDir, ".ralph-runner", "status.json"), JSON.stringify({ status: "running" }), "utf8");
+  writeFileSync(join(taskDir, ".ralph-runner", "iterations.jsonl"), "{\"iteration\":1}\n{\"iteration\":2}\n", "utf8");
+  writeFileSync(join(taskDir, ".ralph-runner", "events.jsonl"), "{\"event\":1}\n", "utf8");
+  writeFileSync(join(taskDir, ".ralph-runner", "transcripts", "one.txt"), "one", "utf8");
+  writeFileSync(join(taskDir, ".ralph-runner", "transcripts", "two.txt"), "two", "utf8");
+
+  const notifications: Array<{ message: string; level: string }> = [];
+  const harness = createHarness();
+  const handler = harness.handler("ralph-logs");
+  const ctx = {
+    cwd,
+    hasUI: true,
+    ui: {
+      notify: (message: string, level: string) => notifications.push({ message, level }),
+      select: async () => undefined,
+      input: async () => undefined,
+      editor: async () => undefined,
+      setStatus: () => undefined,
+    },
+    sessionManager: { getEntries: () => [], getSessionFile: () => "session-a" },
+  };
+
+  await handler("my-task --dest exported", ctx);
+
+  const exportedDir = join(cwd, "exported");
+  assert.equal(existsSync(join(exportedDir, "status.json")), true);
+  assert.equal(readFileSync(join(exportedDir, "iterations.jsonl"), "utf8"), "{\"iteration\":1}\n{\"iteration\":2}\n");
+  assert.equal(readFileSync(join(exportedDir, "events.jsonl"), "utf8"), "{\"event\":1}\n");
+  assert.equal(readFileSync(join(exportedDir, "transcripts", "one.txt"), "utf8"), "one");
+  assert.equal(readFileSync(join(exportedDir, "transcripts", "two.txt"), "utf8"), "two");
+  assert.ok(notifications.some(({ message, level }) => level === "info" && message.includes("Exported 2 iteration records, 1 events, 2 transcripts to ./exported")));
+});
+
+test("/ralph-logs fails when no .ralph-runner/ exists", async (t) => {
+  const cwd = createTempDir();
+  t.after(() => rmSync(cwd, { recursive: true, force: true }));
+
+  const taskDir = join(cwd, "my-task");
+  mkdirSync(taskDir, { recursive: true });
+  writeFileSync(join(taskDir, "RALPH.md"), "---\nmax_iterations: 10\ntimeout: 120\ncommands: []\n---\n# my-task\n", "utf8");
+
+  const notifications: Array<{ message: string; level: string }> = [];
+  const harness = createHarness();
+  const handler = harness.handler("ralph-logs");
+  const ctx = {
+    cwd,
+    hasUI: true,
+    ui: {
+      notify: (message: string, level: string) => notifications.push({ message, level }),
+      select: async () => undefined,
+      input: async () => undefined,
+      editor: async () => undefined,
+      setStatus: () => undefined,
+    },
+    sessionManager: { getEntries: () => [], getSessionFile: () => "session-a" },
+  };
+
+  await handler("my-task", ctx);
+
+  assert.ok(notifications.some(({ message, level }) => level === "error" && message.startsWith("Log export failed: No .ralph-runner directory found at ")));
+});
+
+test("parseLogExportArgs parses --dest correctly", () => {
+  assert.deepEqual(parseLogExportArgs("my-task --dest exported"), { path: "my-task", dest: "exported" });
+});
+
+test("/ralph-logs excludes runtime control files", async (t) => {
+  const cwd = createTempDir();
+  t.after(() => rmSync(cwd, { recursive: true, force: true }));
+
+  const taskDir = join(cwd, "my-task");
+  mkdirSync(join(taskDir, ".ralph-runner", "active-loops"), { recursive: true });
+  writeFileSync(join(taskDir, "RALPH.md"), "---\nmax_iterations: 10\ntimeout: 120\ncommands: []\n---\n# my-task\n", "utf8");
+  writeFileSync(join(taskDir, ".ralph-runner", "status.json"), JSON.stringify({ status: "running" }), "utf8");
+  writeFileSync(join(taskDir, ".ralph-runner", "iterations.jsonl"), "{\"iteration\":1}\n", "utf8");
+  writeFileSync(join(taskDir, ".ralph-runner", "events.jsonl"), "{\"event\":1}\n", "utf8");
+  writeFileSync(join(taskDir, ".ralph-runner", "stop.flag"), "", "utf8");
+  writeFileSync(join(taskDir, ".ralph-runner", "cancel.flag"), "", "utf8");
+  writeFileSync(join(taskDir, ".ralph-runner", "active-loops", "nested.txt"), "skip me", "utf8");
+
+  const harness = createHarness();
+  const handler = harness.handler("ralph-logs");
+  const ctx = {
+    cwd,
+    hasUI: true,
+    ui: {
+      notify: () => undefined,
+      select: async () => undefined,
+      input: async () => undefined,
+      editor: async () => undefined,
+      setStatus: () => undefined,
+    },
+    sessionManager: { getEntries: () => [], getSessionFile: () => "session-a" },
+  };
+
+  await handler("my-task --dest exported", ctx);
+
+  const exportedDir = join(cwd, "exported");
+  assert.equal(existsSync(join(exportedDir, "stop.flag")), false);
+  assert.equal(existsSync(join(exportedDir, "cancel.flag")), false);
+  assert.equal(existsSync(join(exportedDir, "active-loops")), false);
+});
+
+test("/ralph-logs skips symlinked transcript entries", async (t) => {
+  const cwd = createTempDir();
+  t.after(() => rmSync(cwd, { recursive: true, force: true }));
+
+  const taskDir = join(cwd, "my-task");
+  mkdirSync(join(taskDir, ".ralph-runner", "transcripts"), { recursive: true });
+  writeFileSync(join(taskDir, "RALPH.md"), "---\nmax_iterations: 10\ntimeout: 120\ncommands: []\n---\n# my-task\n", "utf8");
+  writeFileSync(join(taskDir, ".ralph-runner", "status.json"), JSON.stringify({ status: "running" }), "utf8");
+  writeFileSync(join(taskDir, ".ralph-runner", "iterations.jsonl"), "{\"iteration\":1}\n", "utf8");
+  writeFileSync(join(taskDir, ".ralph-runner", "events.jsonl"), "{\"event\":1}\n", "utf8");
+  writeFileSync(join(taskDir, "secret.txt"), "top secret", "utf8");
+  writeFileSync(join(taskDir, ".ralph-runner", "transcripts", "good.txt"), "good", "utf8");
+  symlinkSync(join(taskDir, "secret.txt"), join(taskDir, ".ralph-runner", "transcripts", "leak.txt"));
+
+  const harness = createHarness();
+  const handler = harness.handler("ralph-logs");
+  const ctx = {
+    cwd,
+    hasUI: true,
+    ui: {
+      notify: () => undefined,
+      select: async () => undefined,
+      input: async () => undefined,
+      editor: async () => undefined,
+      setStatus: () => undefined,
+    },
+    sessionManager: { getEntries: () => [], getSessionFile: () => "session-a" },
+  };
+
+  await handler("my-task --dest exported", ctx);
+
+  const exportedDir = join(cwd, "exported");
+  assert.equal(existsSync(join(exportedDir, "transcripts", "good.txt")), true);
+  assert.equal(existsSync(join(exportedDir, "transcripts", "leak.txt")), false);
+});
+
 test("/ralph reverse engineer this app with an injected llm-strengthened draft still shows review before start", async (t) => {
   const cwd = createTempDir();
   t.after(() => rmSync(cwd, { recursive: true, force: true }));