@neriros/ralphy 2.16.7 → 2.17.0

package/README.md

@@ -21,6 +21,65 @@ graph LR
 
 Each iteration reads the `## Steering` section of `proposal.md`, picks the first unchecked item from `tasks.md`, does the work, validates, and checks the item off. When all items are checked the loop archives the change automatically.
 
+## Agent Mode Flow
+
+The full orchestration cycle from Linear poll through teardown:
+
+```mermaid
+flowchart TD
+    LINEAR_POLL["Linear poll\n(todo / in-progress / conflicted)"]
+
+    LINEAR_POLL --> ISSUE_STATE{issue state}
+    ISSUE_STATE -- todo --> MODE_FRESH[mode: fresh\nscaffold change]
+    ISSUE_STATE -- in-progress --> MODE_RESUME[mode: resume]
+    ISSUE_STATE -- conflicted --> MODE_CONFLICT_FIX[mode: conflict-fix\nprepend fix task]
+
+    MODE_FRESH & MODE_RESUME & MODE_CONFLICT_FIX --> SET_IN_PROGRESS[Linear: setInProgress]
+    SET_IN_PROGRESS --> USE_WORKTREE{useWorktree?}
+    USE_WORKTREE -- yes --> SCAFFOLD[scaffolding\ncreate worktree + branch]
+    USE_WORKTREE -- no --> WORKER
+    SCAFFOLD --> WORKER([working\nClaude agent loop])
+
+    WORKER --> EXIT_CODE{exitCode?}
+    EXIT_CODE -- "non-zero" --> GAVE_UP
+    EXIT_CODE -- "0" --> WANT_PR{wantPr?}
+
+    WANT_PR -- no --> DONE
+    WANT_PR -- yes --> PUSH_AND_CREATE_PR["push + pr-create\n↺ rebase/hook-fix on rejection"]
+
+    PUSH_AND_CREATE_PR -- gave-up --> GAVE_UP
+    PUSH_AND_CREATE_PR -- no commits ahead --> DONE
+
+    PUSH_AND_CREATE_PR -- pr opened --> WATCH_LOOP
+
+    subgraph WATCH_LOOP["watch loop"]
+        direction LR
+        CONFLICT_CHECK[conflict-check] --> CI_POLL[ci-poll / ci-fix]
+        CI_POLL --> CONFLICT_CHECK
+    end
+
+    WATCH_LOOP -- green & clean --> DONE
+    WATCH_LOOP -- gave-up --> GAVE_UP
+
+    DONE([done]) --> WORKTREE_CLEANUP
+    GAVE_UP([gave-up]) --> WORKTREE_CLEANUP
+
+    subgraph WORKTREE_CLEANUP["cleanup"]
+        direction LR
+        SHOULD_REMOVE_WORKTREE{useWorktree\n& success\n& cleanupOnSuccess?}
+        SHOULD_REMOVE_WORKTREE -- yes --> REMOVE_WORKTREE[remove worktree]
+    end
+
+    WORKTREE_CLEANUP --> TEARDOWN[teardown]
+    TEARDOWN --> OUTCOME{ok?}
+
+    OUTCOME -- "yes,\nnot conflict-fix" --> LINEAR_SET_DONE["Linear: setDone\nclearInProgress\npost comment"]
+    OUTCOME -- "yes,\nconflict-fix" --> LINEAR_CLEAR_CONFLICTED["Linear: clearConflicted\npost comment"]
+    OUTCOME -- no --> LINEAR_SET_ERROR["Linear: setError\nclearInProgress\npost comment"]
+
+    LINEAR_SET_DONE & LINEAR_CLEAR_CONFLICTED & LINEAR_SET_ERROR --> LINEAR_POLL
+```
+
 ## Installation
 
 ### npm (global)
@@ -156,7 +215,7 @@ Marker types are `"label"` or `"status"`. Combine markers under `apply` when one
 
 With `--worktree` (or `useWorktree: true` in config) each task runs in an isolated worktree at `.ralph/worktrees/<change-name>` checked out onto a fresh `ralph/<change-name>` branch. The change is scaffolded _inside_ the worktree, and the loop's cwd is the worktree, so concurrent workers can't stomp on each other.
 
-Use `setupScript` (run inside the worktree right after scaffolding) to install dependencies, copy `.env`, etc. Use `teardownScript` (run after the loop exits, before any worktree cleanup) to gather artifacts or roll back local mutations. Both run via `sh -c`; failures are logged but never block the loop. With `cleanupWorktreeOnSuccess: true` the worktree is removed when the worker exits 0 — failed workers always keep their worktree (and branch) for human inspection.
+Use `setupScript` (run inside the worktree right after scaffolding) to install dependencies, copy `.env`, etc. Use `teardownScript` (run after the loop exits and worktree cleanup) to gather artifacts or roll back local mutations. Both run via `sh -c`; failures are logged but never block the loop. With `cleanupWorktreeOnSuccess: true` the worktree is removed when the worker exits 0 — failed workers always keep their worktree (and branch) for human inspection.
 
 **`appendPrompt`** (or `--prompt` in agent mode) is appended to every scaffolded `proposal.md` under an `## Additional instructions` section — use it for cross-cutting guidance every task should see.
 

package/dist/cli/index.js

@@ -35029,8 +35029,8 @@ import { readFileSync as readFileSync2 } from "fs";
 import { resolve } from "path";
 function getVersion() {
   try {
-    if ("2.16.7")
-      return "2.16.7";
+    if ("2.17.0")
+      return "2.17.0";
   } catch {}
   const dirsToTry = [];
   try {
@@ -35340,7 +35340,7 @@ var VERSION, VALID_MODES, VALID_MODELS, INDICATOR_KEYS, GET_KEYS, HELP_TEXT;
 var init_cli = __esm(() => {
   init_output();
   VERSION = getVersion();
-  VALID_MODES = new Set(["task", "list", "status", "init", "agent", "clean"]);
+  VALID_MODES = new Set(["task", "list", "status", "init", "agent", "clean", "debug"]);
   VALID_MODELS = new Set(["haiku", "sonnet", "opus"]);
   INDICATOR_KEYS = new Set([
     "getTodo",
@@ -35365,6 +35365,7 @@ var init_cli = __esm(() => {
     "  init                    Initialize OpenSpec in current directory",
     "  agent                   Poll Linear for new tasks and run loops concurrently",
     "  clean                   Remove worktree, branch, openspec change, and task state for --name",
+    "  debug                   Show agent log timeline, Linear state, and GitHub PR for --name",
     "",
     "Options:",
     "  --name <name>           Change name (required for most commands)",
@@ -59949,6 +59950,9 @@ class AgentCoordinator {
       capture("agent_linear_poll_failed", { error: err.message });
       return { found: 0, added: 0 };
     }
+    if (todo.length + inProgress.length + conflicted.length > 0) {
+      this.deps.onLog(`  poll: ${todo.length} todo, ${inProgress.length} in-progress, ${conflicted.length} conflicted`, "gray");
+    }
     const queuedIds = new Set(this.queue.map((q) => q.issue.id));
     const activeIds = new Set(this.workers.map((w) => w.issueId));
     const eligible = (id) => !queuedIds.has(id) && !activeIds.has(id) && !this.pendingIds.has(id);
@@ -59970,6 +59974,7 @@ class AgentCoordinator {
       this.queue.push({ issue, mode: "resume" });
       queuedIds.add(issue.id);
       added += 1;
+      this.deps.onLog(`  \u21B3 ${issue.identifier} queued (resume)`, "gray");
     }
     for (const issue of conflicted) {
       if (atTicketLimit())
@@ -59979,6 +59984,7 @@ class AgentCoordinator {
       this.queue.push({ issue, mode: "conflict-fix" });
       queuedIds.add(issue.id);
       added += 1;
+      this.deps.onLog(`  \u21B3 ${issue.identifier} queued (conflict-fix)`, "gray");
     }
     for (const issue of todo) {
       if (atTicketLimit())
@@ -59990,6 +59996,7 @@ class AgentCoordinator {
       this.queue.push({ issue, mode: "fresh" });
       queuedIds.add(issue.id);
       added += 1;
+      this.deps.onLog(`  \u21B3 ${issue.identifier} queued (fresh)`, "gray");
     }
     if (added > 0) {
       const modeRank = {
@@ -60048,6 +60055,7 @@ class AgentCoordinator {
       try {
         await this.deps.postComment(w.issue, `\uD83D\uDD04 Ralph progress update: iteration ${count} on \`${w.changeName}\``);
         w.lastReportedIteration = count;
+        this.deps.onLog(`  ${w.issueIdentifier}: posted progress comment (iteration ${count})`, "gray");
       } catch (err) {
         this.deps.onLog(`! Linear progress comment failed for ${w.issueIdentifier}: ${err.message}`, "red");
       }
@@ -60087,6 +60095,7 @@ class AgentCoordinator {
       capture("agent_conflict_detected", { issue_identifier: issue.identifier });
       try {
         await this.deps.applyIndicator(issue, this.opts.setConflicted);
+        this.deps.onLog(`  ${issue.identifier}: setConflicted applied`, "gray");
       } catch (err) {
         this.deps.onLog(`! Linear setConflicted failed for ${issue.identifier}: ${err.message}`, "red");
         capture("agent_indicator_failed", {
@@ -60100,6 +60109,7 @@ class AgentCoordinator {
       if (this.opts.postComments !== false) {
         try {
           await this.deps.postComment(issue, `\u26A0 Ralph detected merge conflicts on this PR (${pr.url}) \u2014 re-running to resolve`);
+          this.deps.onLog(`  ${issue.identifier}: posted conflict comment`, "gray");
         } catch (err) {
           this.deps.onLog(`! Linear conflict comment failed for ${issue.identifier}: ${err.message}`, "yellow");
         }
@@ -60139,6 +60149,7 @@ class AgentCoordinator {
     if (mode !== "resume" && this.opts.setInProgress) {
       try {
         await this.deps.applyIndicator(issue, this.opts.setInProgress);
+        this.deps.onLog(`  ${issue.identifier}: setInProgress applied`, "gray");
       } catch (err) {
         this.deps.onLog(`! Linear setInProgress failed for ${issue.identifier}: ${err.message}`, "yellow");
         capture("agent_indicator_failed", {
@@ -60159,6 +60170,7 @@ class AgentCoordinator {
       if (!alreadyPosted) {
         try {
           await this.deps.postComment(issue, `\uD83E\uDD16 Ralph started working on this issue. Tracking change: \`${prep.changeName}\``);
+          this.deps.onLog(`  ${issue.identifier}: posted "started" comment`, "gray");
         } catch (err) {
           this.deps.onLog(`! Linear comment failed for ${issue.identifier}: ${err.message}`, "red");
         }
@@ -60212,6 +60224,7 @@ class AgentCoordinator {
 ` + `This issue has been quarantined and will not be auto-resumed on the next poll. ` + `Inspect the worktree at \`~/.ralph/<project>/worktrees/${changeName}\`, fix the ` + `underlying failure, then remove the error marker on this Linear issue (or run ` + `\`ralph clean --name ${changeName}\`) to clear the quarantine.`;
       try {
         await this.deps.postComment(issue, body);
+        this.deps.onLog(`  ${issue.identifier}: posted completion comment`, "gray");
       } catch (err) {
         this.deps.onLog(`! Linear comment failed for ${issue.identifier}: ${err.message}`, "red");
       }
@@ -60221,6 +60234,7 @@ class AgentCoordinator {
         if (this.opts.clearConflicted) {
           try {
             await this.deps.removeIndicator(issue, this.opts.clearConflicted);
+            this.deps.onLog(`  ${issue.identifier}: clearConflicted applied`, "gray");
           } catch (err) {
             this.deps.onLog(`! Linear clearConflicted failed for ${issue.identifier}: ${err.message}`, "red");
             capture("agent_indicator_failed", {
@@ -60234,6 +60248,7 @@ class AgentCoordinator {
       } else if (this.opts.setDone) {
         try {
           await this.deps.applyIndicator(issue, this.opts.setDone);
+          this.deps.onLog(`  ${issue.identifier}: setDone applied`, "gray");
         } catch (err) {
           this.deps.onLog(`! Linear setDone failed for ${issue.identifier}: ${err.message}`, "red");
           capture("agent_indicator_failed", {
@@ -60245,12 +60260,14 @@ class AgentCoordinator {
         if (this.opts.setInProgress) {
           try {
             await this.deps.removeIndicator(issue, this.opts.setInProgress);
+            this.deps.onLog(`  ${issue.identifier}: clearInProgress applied`, "gray");
           } catch {}
         }
       }
     } else if (this.opts.setError) {
       try {
         await this.deps.applyIndicator(issue, this.opts.setError);
+        this.deps.onLog(`  ${issue.identifier}: setError applied`, "gray");
       } catch (err) {
         this.deps.onLog(`! Linear setError failed for ${issue.identifier}: ${err.message}`, "red");
         capture("agent_indicator_failed", {
@@ -60262,6 +60279,7 @@ class AgentCoordinator {
       if (this.opts.setInProgress) {
         try {
           await this.deps.removeIndicator(issue, this.opts.setInProgress);
+          this.deps.onLog(`  ${issue.identifier}: clearInProgress applied`, "gray");
         } catch {}
       }
     }
@@ -60838,6 +60856,88 @@ async function fixConflictsAndCiLoop(ctx, prUrl, wantFixCi, checkPrConflict) {
   }
   return 0;
 }
+async function runPrPhase(input, deps) {
+  const { changeName, cwd: cwd2, branch, changeDir, stateFilePath, issue, wantFixCi, cfg } = input;
+  const { cmd, log: log2, emit, respawnWorker, registerPr, checkPrConflict } = deps;
+  if (!branch || !issue) {
+    log2(`! createPr requested but no worktree branch is tracked for ${changeName} (use --worktree)`, "yellow");
+    return PR_FAILED_EXIT;
+  }
+  const ctx = {
+    changeName,
+    cwd: cwd2,
+    branch,
+    changeDir,
+    stateFilePath,
+    cfg,
+    cmd,
+    log: log2,
+    emit,
+    respawnWorker
+  };
+  try {
+    const status = await cmd.run(["git", "status", "--porcelain"], cwd2);
+    if (status.stdout.trim()) {
+      log2(`! ${changeName} has uncommitted changes after worker exit \u2014 the agent should commit everything before finishing. These changes will not be included in the PR.`, "yellow");
+    }
+  } catch (err) {
+    log2(`! git status check failed for ${changeName}: ${err.message}`, "yellow");
+  }
+  const { pr, gaveUp: prGaveUp } = await createPrWithRetry(ctx, issue);
+  if (prGaveUp)
+    return PR_FAILED_EXIT;
+  if (!pr) {
+    log2(`  no commits ahead of ${cfg.prBaseBranch} \u2014 skipping PR`, "gray");
+    return 0;
+  }
+  log2(`  ${pr.created ? "opened" : "found existing"} PR: ${pr.url}`, "green");
+  registerPr?.(changeName, pr.url);
+  return fixConflictsAndCiLoop(ctx, pr.url, wantFixCi, checkPrConflict);
+}
+async function runWorktreeCleanupPhase(input, deps) {
+  const { changeName, cwd: cwd2, projectRoot, useWorktree, effectiveCode, cfg } = input;
+  const { git, log: log2, emit } = deps;
+  if (!useWorktree || cwd2 === projectRoot)
+    return;
+  emit("cleanup", "checking worktree safety");
+  if (effectiveCode !== 0 || !cfg.cleanupWorktreeOnSuccess)
+    return;
+  const check = await isWorktreeSafeToRemove(cwd2, cfg.prBaseBranch, git).catch((err) => ({
+    safe: false,
+    reason: `safety check failed: ${err.message}`,
+    dirty: "",
+    unpushedCommits: ""
+  }));
+  if (!check.safe) {
+    log2(`! preserving worktree for ${changeName}: ${check.reason}`, "yellow");
+    if (check.dirty)
+      log2(`    uncommitted:
+${check.dirty}`, "yellow");
+    if (check.unpushedCommits)
+      log2(`    commits:
+${check.unpushedCommits}`, "yellow");
+    log2(`    path: ${cwd2}`, "yellow");
+    return;
+  }
+  try {
+    await removeWorktree(projectRoot, cwd2, git);
+    log2(`  removed worktree ${cwd2}`, "gray");
+  } catch (err) {
+    log2(`! worktree remove failed for ${changeName}: ${err.message}`, "yellow");
+  }
+}
+async function runTeardownPhase(input, deps) {
+  const { cwd: cwd2, teardownScript } = input;
+  const { runScript, log: log2, emit } = deps;
+  if (!teardownScript)
+    return;
+  emit("teardown", teardownScript);
+  try {
+    await runScript("teardown", teardownScript, cwd2);
+  } catch (err) {
+    log2(`! teardown script threw: ${err.message}`, "yellow");
+  }
+}
 async function runPostTask(input, deps) {
   const { log: log2, cmd, git, runScript } = deps;
   const emit = (phase, detail) => deps.onPhase?.(phase, detail);
@@ -60857,88 +60957,22 @@ async function runPostTask(input, deps) {
     respawnWorker
   } = input;
   let effectiveCode = exitCode;
-  const ok = exitCode === 0;
-  if (ok && wantPr) {
-    if (!branch || !issue) {
-      log2(`! createPr requested but no worktree branch is tracked for ${changeName} (use --worktree)`, "yellow");
-      effectiveCode = PR_FAILED_EXIT;
-    } else {
-      const ctx = {
-        changeName,
-        cwd: cwd2,
-        branch,
-        changeDir,
-        stateFilePath,
-        cfg,
-        cmd,
-        log: log2,
-        emit,
-        respawnWorker
-      };
-      try {
-        const status = await cmd.run(["git", "status", "--porcelain"], cwd2);
-        if (status.stdout.trim()) {
-          log2(`! ${changeName} has uncommitted changes after worker exit \u2014 the agent should commit everything before finishing. These changes will not be included in the PR.`, "yellow");
-        }
-      } catch (err) {
-        log2(`! git status check failed for ${changeName}: ${err.message}`, "yellow");
-      }
-      {
-        const { pr, gaveUp: prGaveUp } = await createPrWithRetry(ctx, issue);
-        if (prGaveUp) {
-          effectiveCode = PR_FAILED_EXIT;
-        } else if (!pr) {
-          log2(`  no commits ahead of ${cfg.prBaseBranch} \u2014 skipping PR`, "gray");
-        } else {
-          log2(`  ${pr.created ? "opened" : "found existing"} PR: ${pr.url}`, "green");
-          deps.registerPr?.(changeName, pr.url);
-          const loopCode = await fixConflictsAndCiLoop(ctx, pr.url, wantFixCi, deps.checkPrConflict);
-          if (loopCode !== 0)
-            effectiveCode = loopCode;
-        }
-      }
-    }
-  }
-  if (effectiveCode === 0)
-    emit("done");
-  else
-    emit("gave-up", `exit ${effectiveCode}`);
-  if (effectiveCode === 0 && cfg.teardownScript) {
-    emit("teardown", cfg.teardownScript);
-    try {
-      await runScript("teardown", cfg.teardownScript, cwd2);
-    } catch (err) {
-      log2(`! teardown script threw: ${err.message}`, "yellow");
-    }
+  if (effectiveCode !== 0 && wantPr) {
+    log2(`  skipping PR phase for ${changeName} (worker exited with code ${effectiveCode})`, "gray");
   }
-  if (useWorktree && cwd2 !== projectRoot) {
-    emit("cleanup", "checking worktree safety");
-    if (effectiveCode === 0 && cfg.cleanupWorktreeOnSuccess) {
-      const check = await isWorktreeSafeToRemove(cwd2, cfg.prBaseBranch, git).catch((err) => ({
-        safe: false,
-        reason: `safety check failed: ${err.message}`,
-        dirty: "",
-        unpushedCommits: ""
-      }));
-      if (!check.safe) {
-        log2(`! preserving worktree for ${changeName}: ${check.reason}`, "yellow");
-        if (check.dirty)
-          log2(`    uncommitted:
-${check.dirty}`, "yellow");
-        if (check.unpushedCommits)
-          log2(`    commits:
-${check.unpushedCommits}`, "yellow");
-        log2(`    path: ${cwd2}`, "yellow");
-      } else {
-        try {
-          await removeWorktree(projectRoot, cwd2, git);
-          log2(`  removed worktree ${cwd2}`, "gray");
-        } catch (err) {
-          log2(`! worktree remove failed for ${changeName}: ${err.message}`, "yellow");
-        }
-      }
-    }
+  if (effectiveCode === 0 && wantPr) {
+    effectiveCode = await runPrPhase({ changeName, cwd: cwd2, branch, changeDir, stateFilePath, issue, wantFixCi, cfg }, {
+      cmd,
+      log: log2,
+      emit,
+      respawnWorker,
+      ...deps.registerPr !== undefined ? { registerPr: deps.registerPr } : {},
+      ...deps.checkPrConflict !== undefined ? { checkPrConflict: deps.checkPrConflict } : {}
+    });
   }
+  emit(effectiveCode === 0 ? "done" : "gave-up", effectiveCode !== 0 ? `exit ${effectiveCode}` : undefined);
+  await runWorktreeCleanupPhase({ changeName, cwd: cwd2, projectRoot, useWorktree, effectiveCode, cfg }, { git, log: log2, emit });
+  await runTeardownPhase({ cwd: cwd2, teardownScript: cfg.teardownScript }, { runScript, log: log2, emit });
   return effectiveCode;
 }
 var CI_FAILED_EXIT = 70, PR_FAILED_EXIT = 71;
@@ -61584,7 +61618,7 @@ var exports_json_runner = {};
 __export(exports_json_runner, {
   runAgentJson: () => runAgentJson
 });
-import { join as join20 } from "path";
+import { join as join21 } from "path";
 import { mkdir as mkdir6 } from "fs/promises";
 import { homedir as homedir4 } from "os";
 function cleanOutputLine2(raw) {
@@ -61609,7 +61643,7 @@ async function runAgentJson({
   statesDir,
   tasksDir
 }) {
-  await mkdir6(join20(homedir4(), ".ralph"), { recursive: true }).catch(() => {
+  await mkdir6(join21(homedir4(), ".ralph"), { recursive: true }).catch(() => {
     return;
   });
   const cfgPath = await ensureRalphyConfig(projectRoot);
@@ -61715,7 +61749,7 @@ var init_json_runner = __esm(() => {
 });
 
 // apps/cli/src/index.ts
-import { resolve as resolve2, join as join21, dirname as dirname6 } from "path";
+import { resolve as resolve2, join as join22, dirname as dirname6 } from "path";
 import { exists as exists2, mkdir as mkdir7, rm } from "fs/promises";
 
 // node_modules/.bun/ink@5.2.1+1f88f629f0141b18/node_modules/ink/build/render.js
@@ -73684,6 +73718,7 @@ function App2({ args, statesDir, tasksDir, projectRoot }) {
         }, undefined, false, undefined, this)
       }, undefined, false, undefined, this);
     case "clean":
+    case "debug":
       return /* @__PURE__ */ jsx_dev_runtime10.jsxDEV(ExitAfterRender, {
         children: /* @__PURE__ */ jsx_dev_runtime10.jsxDEV(Text, {}, undefined, false, undefined, this)
       }, undefined, false, undefined, this);
@@ -73706,6 +73741,235 @@ function App2({ args, statesDir, tasksDir, projectRoot }) {
 // apps/cli/src/index.ts
 init_layout();
 init_worktree();
+
+// apps/cli/src/debug.ts
+init_log();
+import { join as join20 } from "path";
+var LOG_LINE_RE = /^\[(.+?)\] \[(.+?)\] (.+)$/;
+function parseLog(content) {
+  return content.split(`
+`).filter(Boolean).flatMap((line) => {
+    const m = LOG_LINE_RE.exec(line);
+    if (!m)
+      return [];
+    const ts = new Date(m[1]);
+    if (isNaN(ts.getTime()))
+      return [];
+    return [{ ts, type: m[2], text: m[3] }];
+  });
+}
+function fmtTs(d) {
+  return d.toISOString().replace("T", " ").slice(0, 23);
+}
+var SPAWN_RE = /\u25B6 (\S+) \u2192 (\S+)/;
+async function resolveDebugTarget(opts) {
+  const agentLogFile = Bun.file(AGENT_LOG_PATH);
+  const agentLines = await agentLogFile.exists() ? parseLog(await agentLogFile.text()) : [];
+  if (opts.name && !opts.issue) {
+    for (const line of agentLines) {
+      const m = SPAWN_RE.exec(line.text);
+      if (m && m[2] === opts.name)
+        return { changeName: opts.name, identifier: m[1] };
+    }
+    return { changeName: opts.name, identifier: undefined };
+  }
+  if (opts.issue && !opts.name) {
+    for (const line of agentLines) {
+      const m = SPAWN_RE.exec(line.text);
+      if (m && m[1] === opts.issue)
+        return { changeName: m[2], identifier: opts.issue };
+    }
+    return { changeName: opts.issue, identifier: opts.issue };
+  }
+  return { changeName: opts.name, identifier: opts.issue };
+}
+async function fetchLinearIssue(identifier) {
+  const apiKey = process.env.LINEAR_API_KEY;
+  if (!apiKey)
+    return null;
+  const query = `
+    query($identifier: String!) {
+      issues(filter: { identifier: { eq: $identifier } }, first: 1) {
+        nodes {
+          identifier title url
+          state { name type }
+          labels { nodes { name } }
+        }
+      }
+    }
+  `;
+  try {
+    const res = await fetch("https://api.linear.app/graphql", {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Authorization: apiKey },
+      body: JSON.stringify({ query, variables: { identifier } })
+    });
+    const json = await res.json();
+    return json.data?.issues?.nodes?.[0] ?? null;
+  } catch {
+    return null;
+  }
+}
+function spawnGh(args) {
+  const result2 = Bun.spawnSync(["gh", ...args], { stderr: "ignore" });
+  if (result2.exitCode !== 0)
+    return null;
+  try {
+    return JSON.parse(result2.stdout.toString());
+  } catch {
+    return null;
+  }
+}
+async function fetchGithubPr(changeName) {
+  const branch = `ralph/${changeName}`;
+  const prs = spawnGh([
+    "pr",
+    "list",
+    "--head",
+    branch,
+    "--state",
+    "all",
+    "--json",
+    "number,title,url,state,mergeable"
+  ]);
+  if (!prs?.length)
+    return null;
+  const pr = prs[0];
+  const checks = spawnGh([
+    "pr",
+    "checks",
+    String(pr.number),
+    "--json",
+    "name,state,conclusion"
+  ]) ?? [];
+  return { ...pr, checks };
+}
+async function runDebug(opts) {
+  const { projectRoot } = opts;
+  const agentLogFile = Bun.file(AGENT_LOG_PATH);
+  const agentLogContent = await agentLogFile.exists() ? await agentLogFile.text() : "";
+  const agentLines = parseLog(agentLogContent);
+  let { changeName, identifier: issueIdentifier } = await resolveDebugTarget({
+    ...opts.name !== undefined ? { name: opts.name } : {},
+    ...opts.issue !== undefined ? { issue: opts.issue } : {}
+  });
+  if (!changeName) {
+    process.stderr.write(`! Could not resolve a change name for ${opts.issue ?? opts.name}. Has this issue been started?
+`);
+    process.exit(1);
+  }
+  const relevant = agentLines.filter((l) => l.text.includes(changeName) || issueIdentifier !== undefined && l.text.includes(issueIdentifier));
+  if (!issueIdentifier) {
+    for (const line of relevant) {
+      const m = SPAWN_RE.exec(line.text);
+      if (m && m[2] === changeName) {
+        issueIdentifier = m[1];
+        break;
+      }
+    }
+  }
+  const workerLogPath = join20(projectRoot, ".ralph", "logs", `${changeName}.log`);
+  const workerLogFile = Bun.file(workerLogPath);
+  const workerLines = await workerLogFile.exists() ? parseLog(await workerLogFile.text()) : [];
+  const merged = [...relevant, ...workerLines].sort((a, b) => +a.ts - +b.ts);
+  const seen = new Set;
+  const timeline = merged.filter((l) => {
+    const key = `${l.ts.getTime()}:${l.type}:${l.text}`;
+    if (seen.has(key))
+      return false;
+    seen.add(key);
+    return true;
+  });
+  const out = (s) => process.stdout.write(s + `
+`);
+  out(`
+=== Ralph Debug: ${changeName}${issueIdentifier ? ` (${issueIdentifier})` : ""} ===
+`);
+  out("\u2500\u2500 Timeline \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+  if (!timeline.length) {
+    out("  (no log entries found)");
+  } else {
+    for (const line of timeline) {
+      const prefix = line.type === "output" ? "  \u2502" : "  \xB7";
+      out(`${prefix} ${fmtTs(line.ts)}  [${line.type.padEnd(7)}]  ${line.text}`);
+    }
+  }
+  out("");
+  out("\u2500\u2500 Current Linear state \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+  if (!issueIdentifier) {
+    out("  (unknown identifier \u2014 pass --issue to query Linear directly)");
+  } else if (!process.env.LINEAR_API_KEY) {
+    out("  (set LINEAR_API_KEY to fetch current Linear state)");
+  } else {
+    const issue = await fetchLinearIssue(issueIdentifier);
+    if (!issue) {
+      out(`  ! Could not fetch ${issueIdentifier} from Linear`);
+    } else {
+      const labels = issue.labels.nodes.map((l) => l.name).join(", ") || "(none)";
+      out(`  Title  : ${issue.title}`);
+      out(`  Status : ${issue.state.name} (${issue.state.type})`);
+      out(`  Labels : ${labels}`);
+      out(`  URL    : ${issue.url}`);
+    }
+  }
+  out("");
+  out("\u2500\u2500 Current GitHub PR \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+  const pr = await fetchGithubPr(changeName);
+  if (!pr) {
+    out(`  (no PR found for branch ralph/${changeName})`);
+  } else {
+    const failing = pr.checks.filter((c) => c.conclusion === "FAILURE" || c.conclusion === "failure");
+    const pending = pr.checks.filter((c) => c.state === "PENDING" || c.state === "IN_PROGRESS");
+    out(`  PR #${pr.number} : ${pr.url}`);
+    out(`  State     : ${pr.state}`);
+    out(`  Mergeable : ${pr.mergeable}`);
+    if (pr.checks.length) {
+      out(`  Checks    : ${pr.checks.length} total, ${failing.length} failing, ${pending.length} pending`);
+      for (const c of failing)
+        out(`    \u2717 ${c.name}`);
+      for (const c of pending)
+        out(`    \u29D7 ${c.name}`);
+    } else {
+      out("  Checks    : (none or not yet available)");
+    }
+  }
+  out("");
+  out("\u2500\u2500 Diagnosis \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+  const lastEvent = timeline.at(-1);
+  if (lastEvent)
+    out(`  Last event : ${fmtTs(lastEvent.ts)}  ${lastEvent.text}`);
+  const exitLine = relevant.find((l) => /exited \(code \d+\)/.test(l.text));
+  if (exitLine) {
+    const code = Number(/code (\d+)/.exec(exitLine.text)?.[1]);
+    const meaning = code === 0 ? "success" : code === 70 ? "CI fix loop exhausted its attempt budget" : code === 71 ? "push or PR creation failed (pre-push hook or remote rejection)" : "worker subprocess failed";
+    out(`  Exit code  : ${code} \u2014 ${meaning}`);
+  }
+  const logHas = (s) => relevant.some((l) => l.text.includes(s));
+  if (logHas("setError applied"))
+    out("  \u26A0 setError applied \u2014 issue is quarantined in Linear");
+  if (logHas("setDone applied"))
+    out("  \u2713 setDone applied \u2014 issue marked done in Linear");
+  if (logHas("clearConflicted applied"))
+    out("  \u2713 clearConflicted applied \u2014 conflicts resolved");
+  if (logHas("setConflicted applied"))
+    out("  \u26A0 setConflicted applied \u2014 merge conflicts detected");
+  if (logHas("skipping PR phase"))
+    out("  \u21A9 PR phase skipped \u2014 worker exited non-zero");
+  if (pr?.mergeable === "CONFLICTING")
+    out("  \u26A0 PR currently has merge conflicts");
+  if (pr?.checks.some((c) => c.conclusion === "FAILURE" || c.conclusion === "failure")) {
+    out("  \u26A0 PR has failing CI checks");
+  }
+  const worktreePath = join20(projectRoot, ".ralph", "worktrees", changeName);
+  const worktreeExists = await Bun.file(join20(worktreePath, ".git")).exists();
+  if (worktreeExists)
+    out(`  Worktree   : ${worktreePath}`);
+  if (!timeline.length)
+    out("  (no log entries \u2014 has this change been started yet?)");
+  out("");
+}
+
+// apps/cli/src/index.ts
 init_src();
 if (typeof globalThis.Bun === "undefined") {
   process.stderr.write(`ralph requires the Bun runtime (https://bun.sh/). It is not compatible with plain Node.js.
@@ -73715,7 +73979,7 @@ if (typeof globalThis.Bun === "undefined") {
 async function findProjectRoot() {
   let dir = process.cwd();
   while (dir !== "/") {
-    if (await exists2(join21(dir, "openspec")))
+    if (await exists2(join22(dir, "openspec")))
       return dir;
     dir = resolve2(dir, "..");
   }
@@ -73756,22 +74020,32 @@ try {
   const tasksDir = layout.tasksDir;
   if (args.mode === "init") {
     await mkdir7(statesDir, { recursive: true });
-    const openspecBin = join21(dirname6(Bun.resolveSync("@fission-ai/openspec/package.json", import.meta.dir)), "bin", "openspec.js");
+    const openspecBin = join22(dirname6(Bun.resolveSync("@fission-ai/openspec/package.json", import.meta.dir)), "bin", "openspec.js");
     Bun.spawnSync({
       cmd: [process.execPath, openspecBin, "init", "--tools", "none", "--force"],
       stdio: ["inherit", "inherit", "inherit"],
       cwd: process.cwd()
     });
   }
+  if (args.mode === "debug") {
+    if (!args.name) {
+      process.stderr.write(`Error: --name is required for debug mode
+`);
+      process.exit(1);
+    }
+    await runDebug({ name: args.name, projectRoot });
+    await shutdown();
+    process.exit(0);
+  }
   if (args.mode === "clean") {
     if (!args.name) {
       process.stderr.write(`Error: --name is required for clean mode
 `);
       process.exit(1);
     }
-    const worktreeDir = join21(worktreesDir(projectRoot), args.name);
-    const changeDir = join21(tasksDir, args.name);
-    const stateDir = join21(statesDir, args.name);
+    const worktreeDir = join22(worktreesDir(projectRoot), args.name);
+    const changeDir = join22(tasksDir, args.name);
+    const stateDir = join22(statesDir, args.name);
     const branch = `ralph/${args.name}`;
     const removed = [];
     if (await exists2(worktreeDir)) {
@@ -73823,13 +74097,13 @@ try {
     process.exit(0);
   }
   if (args.mode === "task" && args.name) {
-    await mkdir7(join21(statesDir, args.name), { recursive: true });
-    await mkdir7(join21(tasksDir, args.name), { recursive: true });
+    await mkdir7(join22(statesDir, args.name), { recursive: true });
+    await mkdir7(join22(tasksDir, args.name), { recursive: true });
   }
   if (args.mode === "agent") {
     await mkdir7(statesDir, { recursive: true });
     await mkdir7(tasksDir, { recursive: true });
-    await mkdir7(join21(projectRoot, ".ralph"), { recursive: true });
+    await mkdir7(join22(projectRoot, ".ralph"), { recursive: true });
   }
   if (args.mode === "agent" && args.jsonOutput) {
     const { runAgentJson: runAgentJson2 } = await Promise.resolve().then(() => (init_json_runner(), exports_json_runner));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neriros/ralphy",
-  "version": "2.16.7",
+  "version": "2.17.0",
   "description": "An iterative AI task execution framework. Orchestrates multi-phase autonomous work using Claude or Codex engines.",
   "keywords": [
     "agent",