capyai 0.5.4 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "capyai",
-  "version": "0.5.4",
+  "version": "0.6.0",
   "type": "module",
   "description": "Unofficial Capy.ai CLI for agent orchestration with quality gates",
   "bin": {

package/skills/capy/SKILL.md

@@ -3,7 +3,7 @@ name: capy
 description: Orchestrate Capy.ai coding agents with quality gates. Delegate coding work, wait for completion, review quality, approve or retry.
 metadata:
   author: yazcaleb
-  version: "0.5.0"
+  version: "0.6.0"
 ---
 
 # capy
@@ -56,7 +56,7 @@ When you encounter a task, look at its status and act accordingly. Do exactly on
 **If status is `needs_review`:**
 1. Check if it has a diff: `capy get <id> --json` and look at `pullRequest` field
 2. If no diff was produced (no `pullRequest`, and `capy diff <id> --json` returns `stats.files: 0`):
-   → Task is stuck. Retry with instructions: `capy retry <id> --fix="describe what went wrong" --json`
+   → Task is stuck. Resume with instructions: `capy captain --resume <id> --fix="describe what went wrong" --json`
 3. If diff exists but no PR:
    → Create a PR first: `capy pr <id> --json`
    → Then review: `capy review <id> --json`
@@ -69,7 +69,7 @@ When you encounter a task, look at its status and act accordingly. Do exactly on
 → Start it. `capy start <id> --json`
 
 **If status is `failed`:**
-→ Retry. `capy retry <id> --fix="..." --json`
+→ Resume. `capy captain --resume <id> --fix="..." --json`
 
 **If status is `archived`:**
 → Ignore. This task is dead.
@@ -83,7 +83,7 @@ These are the mistakes agents make. Do not make them.
 
 1. **Never message a task with idle jams.** If the last jam has `status: "idle"` and zero credits, the task is finished. It cannot receive messages. Sending `capy msg` will appear to succeed but nothing happens. If you need to change something, use `capy retry` to start a new attempt.
 
-2. **Never create a new Captain thread for work that already has a diff.** If a task produced code changes, that work exists. Create a PR for the existing task with `capy pr <id>`. Starting a new Captain thread throws away the existing work and burns credits.
+2. **Always check for existing work before starting a new Captain thread.** Run `capy triage --brief --json` or `capy list --json` first. If a task or thread already exists for the same work (in any state: `in_progress`, `needs_review`, `backlog`, `stuck`), resume it instead of creating a new thread. Use `capy captain --resume <id> --fix="..."` to resume stuck/failed tasks, `capy wait <id>` for in-progress ones, `capy pr <id>` for ones needing a PR. Only start a new Captain thread when no related work exists. Creating duplicate threads throws away existing progress and burns credits.
 
 3. **Never call `capy review` on a task with no PR.** It will fail with `error.code: "no_pr"`. Always create the PR first with `capy pr <id> --json`, then review.
 
@@ -97,9 +97,13 @@ These are the mistakes agents make. Do not make them.
 
 ## Workflow: Start new work
 
-Default to `capy captain`. It plans, orchestrates, and can spawn multiple tasks. Only use `capy build` for small single-task work where Captain is overkill.
+Before creating a new Captain thread, check if related work already exists. If it does, resume it (see Decision tree). Only start new work when nothing related is in flight.
 
 ```bash
+# 0. Check for existing related work first
+capy triage --brief --json
+# If something related exists → use retry/wait/pr on that task instead of starting new
+
 # 1. Start a Captain thread (the default for almost everything)
 RESULT=$(capy captain "We need feature X implemented. Make sure tests pass and CI is green." --json)
 THREAD_ID=$(echo "$RESULT" | jq -r '.id')
@@ -129,15 +133,15 @@ for TASK in $TASKS; do
   QUALITY=$(capy review "$TASK" --json)
   PASS=$(echo "$QUALITY" | jq -r '.quality.pass')
 
-  # Retry loop (max 3)
+  # Resume loop (max 3)
   ATTEMPTS=0
   while [ "$PASS" != "true" ] && [ "$ATTEMPTS" -lt 3 ]; do
     FAILING=$(echo "$QUALITY" | jq -r '.quality.gates[] | select(.pass == false) | .name + ": " + .detail')
-    RETRY=$(capy retry "$TASK" --fix="Fix these failures: $FAILING" --json)
-    NEW_THREAD=$(echo "$RETRY" | jq -r '.newThread')
+    RESUME=$(capy captain --resume "$TASK" --fix="Fix these failures: $FAILING" --json)
+    RESUME_THREAD=$(echo "$RESUME" | jq -r '.threadId')
 
-    capy wait "$NEW_THREAD" --timeout=600 --json
-    TASK=$(capy threads get "$NEW_THREAD" --json | jq -r '.tasks[0].identifier')
+    capy wait "$RESUME_THREAD" --timeout=600 --json
+    TASK=$(capy threads get "$RESUME_THREAD" --json | jq -r '.tasks[-1].identifier')
 
     HAS_PR=$(capy get "$TASK" --json | jq -r '.pullRequest.number // empty')
     [ -z "$HAS_PR" ] && capy pr "$TASK" --json
@@ -183,7 +187,7 @@ Map categories to actions:
 - `in_progress` → wait
 - `needs_pr` → `capy pr <id>` then review
 - `ready` → `capy review <id>` then approve/retry
-- `stuck` → `capy retry <id> --fix="..."` or `capy stop <id>`
+- `stuck` → `capy captain --resume <id> --fix="..."` or `capy stop <id>`
 - `backlog` → `capy start <id>` if the user wants it running
 - `merged` → done, ignore
 
@@ -195,10 +199,10 @@ Map categories to actions:
 |------|--------|----------------------|
 | `pr_exists` | A PR was created | Run `capy pr <id> --json` first |
 | `pr_open` | PR is open or merged | PR was closed. Check why. May need a new PR. |
-| `ci` | CI checks are green | Retry: `capy retry <id> --fix="CI failing: <list failing checks>"` |
-| `greptile` | No unaddressed code review issues | If "still processing": wait 60s, re-review. If issues listed: retry with issues in `--fix` |
-| `threads` | No unresolved GitHub review threads | Retry with the unresolved comments in `--fix` |
-| `tests` | Diff includes test files | Retry: `capy retry <id> --fix="Add tests for the changes"` |
+| `ci` | CI checks are green | Resume: `capy captain --resume <id> --fix="CI failing: <list failing checks>"` |
+| `greptile` | No unaddressed code review issues | If "still processing": wait 60s, re-review. If issues listed: resume with issues in `--fix` |
+| `threads` | No unresolved GitHub review threads | Resume with the unresolved comments in `--fix` |
+| `tests` | Diff includes test files | Resume: `capy captain --resume <id> --fix="Add tests for the changes"` |
 
 ## Commands reference
 
@@ -207,10 +211,15 @@ All commands support `--json` for structured output. All errors return `{ "error
 ### Start work
 
 ```bash
-capy captain "<prompt>" --json          # → { id, url } — default, use for almost everything
-capy build "<prompt>" --json            # → { id, identifier, status } — small isolated tasks only
+capy captain "<prompt>" --json                        # → { id, projectId, status, title, url, createdAt }
+capy captain --resume <id> --fix="..." --json         # → { originalTask, threadId, resumed, model }
+capy build "<prompt>" --json                          # → { id, identifier, status, url, createdAt }
+capy build --resume <id> --fix="..." --json           # → { originalTask, newTask, model }
+capy retry <id> --fix="..." --json                    # → alias for captain --resume
 ```
 
+`--resume` messages the existing Captain thread directly (Captain already has full context). If the task has no parent thread (standalone Build), it falls back to creating a new thread with gathered context. If the previous task is still `in_progress`, it stops it first.
+
 Model shortcuts: `--opus`, `--sonnet`, `--mini`, `--fast`, `--kimi`, `--gemini`, `--grok`, `--qwen`, or `--model=<id>`.
 
 ### Wait and monitor
@@ -228,9 +237,8 @@ capy status --json                      # → { threads, tasks, watches }
 
 ```bash
 capy pr <id> [--draft] [--description="..."] --json   # → { url, number, title }
-capy review <id> --json                                # → { task, quality: { pass, gates }, diff }
+capy review <id> --json                                # → { task, quality: { pass, passed, total, gates, summary }, diff, unaddressed, reviewProvider }
 capy approve <id> [--force] --json                     # → { task, quality, approved }
-capy retry <id> --fix="..." --json                     # → { originalTask, newThread, model }
 capy start <id> --json                                 # → task object
 capy stop <id> --json                                  # → task/thread object
 capy msg <id> "<text>" --json                          # → { id, sent: true }

package/src/api.ts

@@ -15,6 +15,7 @@ function fail(code: string, message: string): never {
 }
 
 const RETRYABLE_STATUS = new Set([429, 500, 502, 503, 504]);
+const SAFE_METHODS = new Set(["GET", "HEAD"]);
 const MAX_RETRIES = 3;
 
 async function rawRequest(apiKey: string, server: string, method: string, path: string, body?: unknown): Promise<any> {
@@ -27,12 +28,14 @@ async function rawRequest(apiKey: string, server: string, method: string, path:
     headers["Content-Type"] = "application/json";
   }
 
+  const isSafe = SAFE_METHODS.has(method.toUpperCase());
   let lastError: Error | null = null;
 
   for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
     if (attempt > 0) {
-      const delay = Math.min(1000 * 2 ** (attempt - 1), 8000);
-      await new Promise(r => setTimeout(r, delay));
+      const base = Math.min(1000 * 2 ** (attempt - 1), 8000);
+      const jitter = Math.random() * base * 0.5;
+      await new Promise(r => setTimeout(r, base + jitter));
     }
 
     let res: Response;
@@ -44,11 +47,12 @@ async function rawRequest(apiKey: string, server: string, method: string, path:
       });
     } catch (e: unknown) {
       lastError = e as Error;
-      if (attempt < MAX_RETRIES) continue;
-      fail("network_error", `request failed after ${MAX_RETRIES + 1} attempts — ${lastError.message}`);
+      if (isSafe && attempt < MAX_RETRIES) continue;
+      fail("network_error", `request failed after ${attempt + 1} attempts — ${lastError.message}`);
     }
 
-    if (RETRYABLE_STATUS.has(res.status) && attempt < MAX_RETRIES) {
+    const canRetryStatus = res.status === 429 || (isSafe && RETRYABLE_STATUS.has(res.status));
+    if (canRetryStatus && attempt < MAX_RETRIES) {
       continue;
     }
 

package/src/commands/_shared.ts

@@ -17,6 +17,10 @@ export const jsonArg = {
   json: { type: "boolean", description: "Machine-readable JSON output", default: false },
 } as const satisfies ArgsDef;
 
+export function shellEscape(s: string): string {
+  return "'" + s.replace(/'/g, "'\\''") + "'";
+}
+
 export function isThreadId(id: string): boolean {
   return id.length > 20 || (id.length > 10 && !id.match(/^[A-Z]+-\d+$/));
 }

package/src/commands/agents.ts

@@ -4,7 +4,9 @@ import { modelArgs, jsonArg, resolveModel } from "./_shared.js";
 export const captain = defineCommand({
   meta: { name: "captain", description: "Start Captain thread", alias: "plan" },
   args: {
-    prompt: { type: "positional", description: "Task prompt", required: true },
+    prompt: { type: "positional", description: "Task prompt", required: false },
+    resume: { type: "string", description: "Resume from a previous task ID (messages the existing thread)" },
+    fix: { type: "string", description: "Specific fix instructions (used with --resume)" },
     ...modelArgs,
     ...jsonArg,
   },
@@ -16,10 +18,32 @@ export const captain = defineCommand({
 
     const cfg = config.load();
     const model = resolveModel(args) || cfg.defaultModel;
+
+    if (args.resume) {
+      const { resumeTask } = await import("../resume.js");
+      const r = await resumeTask(args.resume, { prompt: args.prompt, fix: args.fix, model, mode: "captain" });
+
+      if (IS_JSON) { out({ originalTask: r.originalTask, threadId: r.threadId, resumed: r.resumed, model }); return; }
+      if (r.resumed) {
+        log.success(`Messaged existing thread for ${r.originalTask}: https://capy.ai/project/${cfg.projectId}/captain/${r.threadId}`);
+      } else {
+        log.success(`Resumed ${r.originalTask} (new thread): https://capy.ai/project/${cfg.projectId}/captain/${r.threadId}`);
+      }
+      log.info(`Thread: ${r.threadId}  Model: ${model}`);
+      return;
+    }
+
+    if (!args.prompt) {
+      if (IS_JSON) { out({ error: { code: "missing_prompt", message: "Prompt is required (or use --resume <id>)" } }); process.exit(1); }
+      console.error("capy: prompt is required (or use --resume <id>)");
+      process.exit(1);
+    }
+
     const data = await api.createThread(args.prompt, model);
+    const url = `https://capy.ai/project/${cfg.projectId}/captain/${data.id}`;
 
-    if (IS_JSON) { out(data); return; }
-    log.success(`Captain started: https://capy.ai/project/${cfg.projectId}/captain/${data.id}`);
+    if (IS_JSON) { out({ ...data, url }); return; }
+    log.success(`Captain started: ${url}`);
     log.info(`Thread: ${data.id}  Model: ${model}`);
   },
 });
@@ -27,7 +51,9 @@ export const captain = defineCommand({
 export const build = defineCommand({
   meta: { name: "build", description: "Start Build agent (isolated)", alias: "run" },
   args: {
-    prompt: { type: "positional", description: "Task prompt", required: true },
+    prompt: { type: "positional", description: "Task prompt", required: false },
+    resume: { type: "string", description: "Resume from a previous task ID" },
+    fix: { type: "string", description: "Specific fix instructions (used with --resume)" },
     ...modelArgs,
     ...jsonArg,
   },
@@ -39,10 +65,28 @@ export const build = defineCommand({
 
     const cfg = config.load();
     const model = resolveModel(args) || cfg.defaultModel;
+
+    if (args.resume) {
+      const { resumeTask } = await import("../resume.js");
+      const r = await resumeTask(args.resume, { prompt: args.prompt, fix: args.fix, model, mode: "build" });
+
+      if (IS_JSON) { out({ originalTask: r.originalTask, newTask: r.threadId, model }); return; }
+      log.success(`Resumed ${r.originalTask}: https://capy.ai/project/${cfg.projectId}/tasks/${r.threadId}`);
+      log.info(`ID: ${r.threadId}  Model: ${model}`);
+      return;
+    }
+
+    if (!args.prompt) {
+      if (IS_JSON) { out({ error: { code: "missing_prompt", message: "Prompt is required (or use --resume <id>)" } }); process.exit(1); }
+      console.error("capy: prompt is required (or use --resume <id>)");
+      process.exit(1);
+    }
+
     const data = await api.createTask(args.prompt, model);
+    const url = `https://capy.ai/project/${cfg.projectId}/tasks/${data.id}`;
 
-    if (IS_JSON) { out(data); return; }
-    log.success(`Build started: https://capy.ai/project/${cfg.projectId}/tasks/${data.id}`);
+    if (IS_JSON) { out({ ...data, url }); return; }
+    log.success(`Build started: ${url}`);
     log.info(`ID: ${data.identifier}  Model: ${model}`);
   },
 });

package/src/commands/monitoring.ts

@@ -78,6 +78,8 @@ export const wait = defineCommand({
     const start = Date.now();
     if (!args.json) process.stderr.write(`Waiting for ${args.id} (${isThread ? "thread" : "task"})...`);
 
+    const PERMANENT_ERRORS = new Set(["no_api_key", "not_found", "unauthorized", "forbidden"]);
+
     let lastStatus = "unknown";
     while (Date.now() - start < timeoutMs) {
       try {
@@ -88,8 +90,13 @@ export const wait = defineCommand({
           console.log(`\n${isThread ? "Thread" : "Task"} ${data.status}.`);
           return;
         }
-      } catch {
-        // transient error during poll, keep trying
+      } catch (e: unknown) {
+        const { CapyError } = await import("../api.js");
+        if (e instanceof CapyError && PERMANENT_ERRORS.has(e.code)) {
+          if (args.json) { fmt.out({ error: { code: e.code, message: e.message } }); process.exit(1); }
+          console.error(`\ncapy: ${e.message}`);
+          process.exit(1);
+        }
       }
       if (!args.json) process.stderr.write(".");
       await new Promise(r => setTimeout(r, intervalMs));

package/src/commands/quality.ts

@@ -210,10 +210,11 @@ export const approve = defineCommand({
       if (approveCmd) {
         try {
           const { execSync } = await import("node:child_process");
+          const { shellEscape } = await import("./_shared.js");
           const expanded = approveCmd
-            .replace("{task}", task.identifier || task.id)
-            .replace("{title}", (task.title || "").replace(/'/g, "'\\''"))
-            .replace("{pr}", String(task.pullRequest?.number || ""));
+            .replace("{task}", shellEscape(task.identifier || task.id))
+            .replace("{title}", shellEscape(task.title || ""))
+            .replace("{pr}", shellEscape(String(task.pullRequest?.number || "")));
           execSync(expanded, { timeout: 15000, stdio: "pipe" });
           log.info("Post-approve hook ran.");
         } catch {}
@@ -223,7 +224,7 @@ export const approve = defineCommand({
 });
 
 export const retry = defineCommand({
-  meta: { name: "retry", description: "Retry with failure context" },
+  meta: { name: "retry", description: "Alias for: capy captain --resume <id> --fix='...'" },
   args: {
     id: { type: "positional", description: "Task ID", required: true },
     fix: { type: "string", description: "Specific fix instructions" },
@@ -231,96 +232,25 @@ export const retry = defineCommand({
     ...jsonArg,
   },
   async run({ args }) {
-    const api = await import("../api.js");
     const config = await import("../config.js");
-    const github = await import("../github.js");
-    const greptileApi = await import("../greptile.js");
+    const { resumeTask } = await import("../resume.js");
     const fmt = await import("../output.js");
     const { log } = await import("@clack/prompts");
 
-    const task = await api.getTask(args.id);
     const cfg = config.load();
-
-    let context = `Previous attempt: ${task.identifier} "${task.title}" [${task.status}]\n`;
-
-    try {
-      const d = await api.getDiff(args.id);
-      if (d.stats?.files && d.stats.files > 0) {
-        context += `\nPrevious diff: +${d.stats.additions} -${d.stats.deletions} in ${d.stats.files} files\n`;
-        context += `Files changed: ${(d.files || []).map(f => f.path).join(", ")}\n`;
-      } else {
-        context += `\nPrevious diff: empty (agent produced no changes)\n`;
-      }
-    } catch { context += "\nPrevious diff: unavailable\n"; }
-
-    if (task.pullRequest?.number) {
-      const repo = task.pullRequest.repoFullName || cfg.repos[0]?.repoFullName || "";
-      const prNum = task.pullRequest.number;
-      const defaultBranch = cfg.repos.find(r => r.repoFullName === repo)?.branch || "main";
-      const reviewComments = github.getPRReviewComments(repo, prNum);
-      const ci = github.getCIStatus(repo, prNum);
-
-      const reviewProvider = cfg.quality?.reviewProvider || "greptile";
-      const hasGreptileKey = !!(cfg.greptileApiKey || process.env.GREPTILE_API_KEY);
-
-      if (reviewProvider === "greptile" && hasGreptileKey) {
-        const unaddressed = await greptileApi.getUnaddressedIssues(repo, prNum, defaultBranch);
-        if (unaddressed.length > 0) {
-          context += `\nUnaddressed Greptile issues (${unaddressed.length}):\n`;
-          unaddressed.forEach(u => {
-            context += `  ${u.file}:${u.line}: ${u.body}\n`;
-            if (u.suggestedCode) context += `    Suggested fix: ${u.suggestedCode.slice(0, 200)}\n`;
-          });
-        } else {
-          context += `\nGreptile: all issues addressed\n`;
-        }
-      } else {
-        const issueComments = github.getPRIssueComments(repo, prNum);
-        const greptileReview = github.parseGreptileReview(issueComments);
-        if (greptileReview) {
-          context += `\nGreptile review: ${greptileReview.score}/5 (stale, may not reflect latest)\n`;
-        }
-      }
-
-      if (ci && !ci.allGreen) {
-        context += `\nCI failures: ${ci.failing.map(f => f.name).join(", ")}\n`;
-      }
-      if (reviewComments.length) {
-        context += `\nReview comments (${reviewComments.length}):\n`;
-        reviewComments.slice(0, 5).forEach((c: any) => {
-          context += `  ${c.path}:${c.line || "?"}: ${(c.body || "").slice(0, 150)}\n`;
-        });
-      }
-    }
-
-    const originalPrompt = task.prompt || task.title;
-    let retryPrompt = `RETRY: This is a retry of a previous attempt that had issues.\n\n`;
-    retryPrompt += `Original task: ${originalPrompt}\n\n`;
-    retryPrompt += `--- CONTEXT FROM PREVIOUS ATTEMPT ---\n${context}\n`;
-
-    if (args.fix) {
-      retryPrompt += `--- SPECIFIC FIX REQUESTED ---\n${args.fix}\n\n`;
-    }
-
-    retryPrompt += `--- INSTRUCTIONS ---\n`;
-    retryPrompt += `Fix the issues from the previous attempt. Do not repeat the same mistakes.\n`;
-    retryPrompt += `Include tests. Run tests before completing. Verify CI will pass.\n`;
-
-    if (task.status === "in_progress") {
-      await api.stopTask(args.id, "Retrying with fixes");
-      if (!args.json) log.info(`Stopped ${task.identifier}.`);
-    }
-
     const model = resolveModel(args) || cfg.defaultModel;
-    const data = await api.createThread(retryPrompt, model);
+    const r = await resumeTask(args.id, { fix: args.fix, model, mode: "captain" });
 
     if (args.json) {
-      fmt.out({ originalTask: task.identifier, newThread: data.id, model, contextLines: context.split("\n").length });
+      fmt.out({ originalTask: r.originalTask, threadId: r.threadId, resumed: r.resumed, model });
       return;
     }
 
-    log.success(`Retry started: https://capy.ai/project/${cfg.projectId}/captain/${data.id}`);
-    log.info(`Thread: ${data.id}  Model: ${model}`);
-    log.info(`Context included: ${context.split("\n").length} lines from previous attempt.`);
+    if (r.resumed) {
+      log.success(`Messaged existing thread for ${r.originalTask}: https://capy.ai/project/${cfg.projectId}/captain/${r.threadId}`);
+    } else {
+      log.success(`Retry started (new thread): https://capy.ai/project/${cfg.projectId}/captain/${r.threadId}`);
+    }
+    log.info(`Thread: ${r.threadId}  Model: ${model}`);
   },
 });

package/src/commands/setup.ts

@@ -203,8 +203,8 @@ export const tools = defineCommand({
     const { log } = await import("@clack/prompts");
 
     const all: Record<string, { args: string; desc: string }> = {
-      captain:    { args: "<prompt>",              desc: "Start Captain thread" },
-      build:      { args: "<prompt>",              desc: "Start Build agent (isolated)" },
+      captain:    { args: "<prompt> [--resume <id>]", desc: "Start Captain thread (or resume)" },
+      build:      { args: "<prompt> [--resume <id>]", desc: "Start Build agent (or resume)" },
       threads:    { args: "[list|get|msg|stop]",   desc: "Manage threads" },
       triage:     { args: "[id,...]",               desc: "Actionable triage with diffs + recs" },
       status:     { args: "",                      desc: "Dashboard" },
@@ -218,7 +218,7 @@ export const tools = defineCommand({
       review:     { args: "<id>",                  desc: "Quality gates check" },
       "re-review":{ args: "<id>",                  desc: "Trigger Greptile re-review" },
       approve:    { args: "<id>",                  desc: "Approve if gates pass" },
-      retry:      { args: "<id> [--fix=...]",      desc: "Retry with failure context" },
+      retry:      { args: "<id> [--fix=...]",      desc: "Alias for captain --resume" },
       wait:       { args: "<id>",                  desc: "Block until done" },
       watch:      { args: "<id>",                  desc: "Poll + notify on completion" },
       unwatch:    { args: "<id>",                  desc: "Stop watching" },

package/src/commands/triage.ts

@@ -64,13 +64,14 @@ export const triage = defineCommand({
       results = await enrichTasks(api, tasks, cfg, brief);
     }
 
-    // Cross-ref PR state with GitHub
-    for (const r of results) {
-      if (r.pr && r.pr.state === "closed") {
+    // Cross-ref closed PRs with GitHub to detect merged state (skip in brief mode)
+    if (!brief) {
+      const closed = results.filter(r => r.pr && r.pr.state === "closed");
+      for (const r of closed) {
         const repo = r._raw?.pullRequest?.repoFullName || cfg.repos[0]?.repoFullName;
         if (repo) {
-          const ghPR = github.getPR(repo, r.pr.number);
-          if (ghPR) r.pr.state = ghPR.state.toLowerCase();
+          const ghPR = github.getPR(repo, r.pr!.number);
+          if (ghPR) r.pr!.state = ghPR.state.toLowerCase();
         }
       }
     }
@@ -86,13 +87,11 @@ export const triage = defineCommand({
         category = "merged";
       } else if (r.pr && r.pr.state === "open") {
         category = "ready";
-      } else if (r.diff && r.diff.files > 0 && !r.pr) {
-        category = "needs_pr";
-      } else if (r.status === "needs_review" && !r.pr && (!r.diff || r.diff.files === 0)) {
-        category = brief ? "needs_pr" : "stuck";
       } else if (r.status === "needs_review" && r.pr) {
         category = "ready";
       } else if (r.status === "needs_review" && !r.pr) {
+        category = (!brief && (!r.diff || r.diff.files === 0)) ? "stuck" : "needs_pr";
+      } else if (r.diff && r.diff.files > 0 && !r.pr) {
         category = "needs_pr";
       } else {
         category = "stuck";
@@ -217,23 +216,46 @@ export const triage = defineCommand({
   },
 });
 
+function pLimit(concurrency: number) {
+  let active = 0;
+  const queue: (() => void)[] = [];
+  return <T>(fn: () => Promise<T>): Promise<T> =>
+    new Promise<T>((resolve, reject) => {
+      const run = () => { active++; fn().then(resolve, reject).finally(() => { active--; queue.length && queue.shift()!(); }); };
+      active < concurrency ? run() : queue.push(run);
+    });
+}
+
 async function enrichTasks(api: typeof import("../api.js"), tasks: any[], cfg: any, brief = false) {
-  const enriched = await Promise.all(tasks.map(async (task) => {
+  if (brief) {
+    // Brief mode: listTasks already returns status + pullRequest, no extra fetches needed
+    return tasks.map(task => ({
+      identifier: task.identifier || task.id,
+      title: task.title || "",
+      status: task.status,
+      labels: task.labels || [],
+      createdAt: task.createdAt,
+      updatedAt: task.updatedAt,
+      pr: task.pullRequest?.number ? {
+        number: task.pullRequest.number,
+        state: task.pullRequest.state || "?",
+        url: task.pullRequest.url,
+      } : null,
+      diff: null,
+      jam: null,
+      _raw: task,
+    }));
+  }
+
+  const limit = pLimit(5);
+  const enriched = await Promise.all(tasks.map(task => limit(async () => {
     const id = task.identifier || task.id;
-    let detail: any = task;
-    let diff: any = null;
-
-    try {
-      if (!task.jams) {
-        detail = await api.getTask(id);
-      }
-    } catch {}
 
-    if (!brief) {
-      try {
-        diff = await api.getDiff(id);
-      } catch {}
-    }
+    // Fetch detail + diff in parallel
+    const [detail, diff] = await Promise.all([
+      task.jams ? task : api.getTask(id).catch(() => task),
+      api.getDiff(id).catch(() => null),
+    ]);
 
     const lastJam = (detail.jams || []).at(-1);
     const credits = lastJam?.credits;
@@ -265,7 +287,7 @@ async function enrichTasks(api: typeof import("../api.js"), tasks: any[], cfg: a
       } : null,
       _raw: detail,
     };
-  }));
+  })));
 
   return enriched;
 }

package/src/mcp.ts

@@ -10,6 +10,16 @@ import { isThreadId } from "./commands/_shared.js";
 const require = createRequire(import.meta.url);
 const { version } = require("../package.json");
 
+function pLimit(concurrency: number) {
+  let active = 0;
+  const queue: (() => void)[] = [];
+  return <T>(fn: () => Promise<T>): Promise<T> =>
+    new Promise<T>((resolve, reject) => {
+      const run = () => { active++; fn().then(resolve, reject).finally(() => { active--; queue.length && queue.shift()!(); }); };
+      active < concurrency ? run() : queue.push(run);
+    });
+}
+
 const server = new McpServer({ name: "capy", version });
 
 function err(e: unknown) {
@@ -30,41 +40,59 @@ function structured(data: Record<string, unknown>) {
 // --- Orchestration ---
 
 server.registerTool("capy_captain", {
-  description: "Start a Captain thread to delegate coding work to a Capy agent",
+  description: "Start a Captain thread. Use resume to continue from a previous task with auto-gathered context (diff, CI, reviews).",
   inputSchema: {
-    prompt: z.string().describe("What the agent should do. Be specific: files, functions, acceptance criteria."),
+    prompt: z.string().optional().describe("What the agent should do. Required unless using resume."),
     model: z.string().optional().describe("Model ID override (default: config defaultModel)"),
+    resume: z.string().optional().describe("Task ID to resume from. Auto-gathers context from previous attempt."),
+    fix: z.string().optional().describe("Specific fix instructions (used with resume)"),
   },
   outputSchema: {
     threadId: z.string(),
     url: z.string(),
   },
   annotations: { openWorldHint: true },
-}, async ({ prompt, model }) => {
+}, async ({ prompt, model, resume, fix }) => {
   try {
     const cfg = config.load();
+    if (resume) {
+      const { resumeTask } = await import("./resume.js");
+      const r = await resumeTask(resume, { prompt, fix, model, mode: "captain" });
+      return structured({ threadId: r.threadId, url: `https://capy.ai/project/${cfg.projectId}/captain/${r.threadId}`, originalTask: r.originalTask, resumed: r.resumed });
+    }
+    if (!prompt) return err(new Error("prompt is required (or use resume with a task ID)"));
     const data = await api.createThread(prompt, model);
     return structured({ threadId: data.id, url: `https://capy.ai/project/${cfg.projectId}/captain/${data.id}` });
   } catch (e) { return err(e); }
 });
 
 server.registerTool("capy_build", {
-  description: "Start a Build agent for small isolated tasks (single-file fixes, scripts)",
+  description: "Start a Build agent for small isolated tasks. Use resume to continue from a previous task.",
   inputSchema: {
-    prompt: z.string().describe("What to build. Be specific."),
+    prompt: z.string().optional().describe("What to build. Required unless using resume."),
     model: z.string().optional().describe("Model ID override"),
     title: z.string().optional().describe("Short task title"),
+    resume: z.string().optional().describe("Task ID to resume from."),
+    fix: z.string().optional().describe("Specific fix instructions (used with resume)"),
   },
   outputSchema: {
     id: z.string(),
     identifier: z.string(),
     status: z.string(),
+    url: z.string(),
   },
   annotations: { openWorldHint: true },
-}, async ({ prompt, model, title }) => {
+}, async ({ prompt, model, title, resume, fix }) => {
   try {
+    const cfg = config.load();
+    if (resume) {
+      const { resumeTask } = await import("./resume.js");
+      const r = await resumeTask(resume, { prompt, fix, model, mode: "build" });
+      return structured({ id: r.threadId, identifier: r.originalTask, status: "in_progress", url: `https://capy.ai/project/${cfg.projectId}/tasks/${r.threadId}`, originalTask: r.originalTask });
+    }
+    if (!prompt) return err(new Error("prompt is required (or use resume with a task ID)"));
     const data = await api.createTask(prompt, model, { title, start: true });
-    return structured({ id: data.id, identifier: data.identifier, status: data.status });
+    return structured({ id: data.id, identifier: data.identifier, status: data.status, url: `https://capy.ai/project/${cfg.projectId}/tasks/${data.id}` });
   } catch (e) { return err(e); }
 });
 
@@ -91,8 +119,10 @@ server.registerTool("capy_wait", {
       try {
         lastData = isThread ? await api.getThread(id) : await api.getTask(id);
         if (terminal.has(lastData.status)) return text(lastData);
-      } catch {
-        // transient error during poll, keep trying
+      } catch (e) {
+        if (e instanceof CapyError && ["not_found", "unauthorized", "forbidden", "no_api_key"].includes(e.code)) {
+          return err(e);
+        }
       }
       await new Promise(r => setTimeout(r, intervalMs));
     }
@@ -146,10 +176,11 @@ server.registerTool("capy_approve", {
     if (approved && cfg.approveCommand) {
       try {
         const { execSync } = await import("node:child_process");
+        const { shellEscape } = await import("./commands/_shared.js");
         const expanded = cfg.approveCommand
-          .replace("{task}", task.identifier || task.id)
-          .replace("{title}", (task.title || "").replace(/'/g, "'\\''"))
-          .replace("{pr}", String(task.pullRequest?.number || ""));
+          .replace("{task}", shellEscape(task.identifier || task.id))
+          .replace("{title}", shellEscape(task.title || ""))
+          .replace("{pr}", shellEscape(String(task.pullRequest?.number || "")));
         execSync(expanded, { timeout: 15000, stdio: "pipe" });
       } catch {}
     }
@@ -159,7 +190,7 @@ server.registerTool("capy_approve", {
 });
 
 server.registerTool("capy_retry", {
-  description: "Retry a failed task with context from previous attempt. Creates a new Captain thread.",
+  description: "Alias for capy_captain with resume. Retry a failed task with auto-gathered context.",
   inputSchema: {
     id: z.string().describe("Task ID to retry"),
     fix: z.string().optional().describe("Specific fix instructions"),
@@ -167,34 +198,17 @@ server.registerTool("capy_retry", {
   },
   outputSchema: {
     originalTask: z.string(),
-    newThread: z.string(),
+    threadId: z.string(),
     model: z.string(),
   },
   annotations: { openWorldHint: true },
 }, async ({ id, fix, model }) => {
   try {
-    const task = await api.getTask(id);
+    const { resumeTask } = await import("./resume.js");
     const cfg = config.load();
-
-    let context = `Previous attempt: ${task.identifier} "${task.title}" [${task.status}]\n`;
-    try {
-      const d = await api.getDiff(id);
-      if (d.stats?.files && d.stats.files > 0) {
-        context += `\nPrevious diff: +${d.stats.additions} -${d.stats.deletions} in ${d.stats.files} files\n`;
-      }
-    } catch {}
-
-    let retryPrompt = `RETRY: This is a retry of a previous attempt that had issues.\n\nOriginal task: ${task.prompt || task.title}\n\n--- CONTEXT ---\n${context}\n`;
-    if (fix) retryPrompt += `--- FIX ---\n${fix}\n\n`;
-    retryPrompt += `Fix the issues. Include tests. Run tests before completing.\n`;
-
-    if (task.status === "in_progress") {
-      await api.stopTask(id, "Retrying with fixes");
-    }
-
     const m = model || cfg.defaultModel;
-    const data = await api.createThread(retryPrompt, m);
-    return structured({ originalTask: task.identifier, newThread: data.id, model: m });
+    const r = await resumeTask(id, { fix, model: m, mode: "captain" });
+    return structured({ originalTask: r.originalTask, threadId: r.threadId, model: m, resumed: r.resumed });
   } catch (e) { return err(e); }
 });
 
@@ -218,48 +232,73 @@ server.registerTool("capy_triage", {
       tasks = data.items || [];
     }
 
-    const enriched = await Promise.all(tasks.map(async (task: any) => {
-      const id = task.identifier || task.id;
-      let detail: any = task;
-      let diff: any = null;
-      try { if (!task.jams) detail = await api.getTask(id); } catch {}
-      if (!brief) { try { diff = await api.getDiff(id); } catch {} }
+    function categorize(status: string, pr: any, diffStats: any, brief: boolean) {
+      if (status === "backlog") return "backlog";
+      if (status === "in_progress") return "in_progress";
+      if (pr?.state === "merged") return "merged";
+      if (pr && pr.state === "open") return "ready";
+      if (status === "needs_review" && pr) return "ready";
+      if (status === "needs_review" && !pr) return (!brief && (!diffStats || diffStats.files === 0)) ? "stuck" : "needs_pr";
+      if (diffStats && diffStats.files > 0 && !pr) return "needs_pr";
+      return "stuck";
+    }
 
-      if (detail.pullRequest?.number && detail.pullRequest.state === "closed") {
-        const repo = detail.pullRequest.repoFullName || cfg.repos[0]?.repoFullName;
-        if (repo) {
-          const ghPR = github.getPR(repo, detail.pullRequest.number);
-          if (ghPR) detail.pullRequest.state = ghPR.state.toLowerCase();
+    let enriched: any[];
+    if (brief) {
+      enriched = tasks.map((task: any) => {
+        if (task.pullRequest?.number && task.pullRequest.state === "closed") {
+          const repo = task.pullRequest.repoFullName || cfg.repos[0]?.repoFullName;
+          if (repo) {
+            const ghPR = github.getPR(repo, task.pullRequest.number);
+            if (ghPR) task.pullRequest.state = ghPR.state.toLowerCase();
+          }
+        }
+        const pr = task.pullRequest?.number ? { number: task.pullRequest.number, state: task.pullRequest.state || "?", url: task.pullRequest.url } : null;
+        return {
+          identifier: task.identifier || task.id,
+          title: task.title || "",
+          status: task.status,
+          labels: task.labels || [],
+          category: categorize(task.status, pr, null, true),
+          pr,
+          diff: null,
+          jam: null,
+        };
+      });
+    } else {
+      const limit = pLimit(5);
+      enriched = await Promise.all(tasks.map((task: any) => limit(async () => {
+        const id = task.identifier || task.id;
+        const [detail, diff] = await Promise.all([
+          task.jams ? task : api.getTask(id).catch(() => task),
+          api.getDiff(id).catch(() => null),
+        ]);
+
+        if (detail.pullRequest?.number && detail.pullRequest.state === "closed") {
+          const repo = detail.pullRequest.repoFullName || cfg.repos[0]?.repoFullName;
+          if (repo) {
+            const ghPR = github.getPR(repo, detail.pullRequest.number);
+            if (ghPR) detail.pullRequest.state = ghPR.state.toLowerCase();
+          }
         }
-      }
 
-      const lastJam = (detail.jams || []).at(-1);
-      const credits = lastJam?.credits;
-      const pr = detail.pullRequest?.number ? { number: detail.pullRequest.number, state: detail.pullRequest.state || "?", url: detail.pullRequest.url } : null;
-      const diffStats = diff?.stats ? { files: diff.stats.files || 0, additions: diff.stats.additions || 0, deletions: diff.stats.deletions || 0 } : null;
-
-      let category: string;
-      if (detail.status === "backlog") category = "backlog";
-      else if (detail.status === "in_progress") category = "in_progress";
-      else if (pr?.state === "merged") category = "merged";
-      else if (pr && pr.state === "open") category = "ready";
-      else if (diffStats && diffStats.files > 0 && !pr) category = "needs_pr";
-      else if (detail.status === "needs_review" && !pr && (!diffStats || diffStats.files === 0)) category = brief ? "needs_pr" : "stuck";
-      else if (detail.status === "needs_review" && pr) category = "ready";
-      else if (detail.status === "needs_review" && !pr) category = "needs_pr";
-      else category = "stuck";
-
-      return {
-        identifier: detail.identifier || id,
-        title: detail.title || "",
-        status: detail.status,
-        labels: detail.labels || [],
-        category,
-        pr,
-        diff: diffStats,
-        jam: lastJam ? { model: lastJam.model || "?", status: lastJam.status || "?", credits: { llm: typeof credits === "object" ? (credits?.llm ?? 0) : (credits || 0), vm: typeof credits === "object" ? (credits?.vm ?? 0) : 0 } } : null,
-      };
-    }));
+        const lastJam = (detail.jams || []).at(-1);
+        const credits = lastJam?.credits;
+        const pr = detail.pullRequest?.number ? { number: detail.pullRequest.number, state: detail.pullRequest.state || "?", url: detail.pullRequest.url } : null;
+        const diffStats = diff?.stats ? { files: diff.stats.files || 0, additions: diff.stats.additions || 0, deletions: diff.stats.deletions || 0 } : null;
+
+        return {
+          identifier: detail.identifier || id,
+          title: detail.title || "",
+          status: detail.status,
+          labels: detail.labels || [],
+          category: categorize(detail.status, pr, diffStats, false),
+          pr,
+          diff: diffStats,
+          jam: lastJam ? { model: lastJam.model || "?", status: lastJam.status || "?", credits: { llm: typeof credits === "object" ? (credits?.llm ?? 0) : (credits || 0), vm: typeof credits === "object" ? (credits?.vm ?? 0) : 0 } } : null,
+        };
+      })));
+    }
 
     const summary = {
       total: enriched.length,
@@ -485,12 +524,15 @@ server.registerTool("capy_project", {
     id: z.string(),
     name: z.string(),
     taskCode: z.string(),
+    repos: z.array(z.object({ repoFullName: z.string(), branch: z.string() })),
+    createdAt: z.string().optional(),
+    updatedAt: z.string().optional(),
   },
   annotations: { readOnlyHint: true, idempotentHint: true },
 }, async ({ id }) => {
   try {
     const data = await api.getProject(id);
-    return structured({ id: data.id, name: data.name, taskCode: data.taskCode, repos: data.repos as unknown as Record<string, unknown>, createdAt: data.createdAt, updatedAt: data.updatedAt });
+    return structured({ id: data.id, name: data.name, taskCode: data.taskCode, repos: data.repos as unknown as Record<string, unknown>[], createdAt: data.createdAt, updatedAt: data.updatedAt });
   } catch (e) { return err(e); }
 });
 

package/src/resume.ts

@@ -0,0 +1,139 @@
+export interface ResumeResult {
+  threadId: string;
+  originalTask: string;
+  resumed: boolean;
+}
+
+export async function resumeTask(taskId: string, opts: {
+  prompt?: string;
+  fix?: string;
+  model?: string;
+  mode: "captain" | "build";
+}): Promise<ResumeResult> {
+  const api = await import("./api.js");
+  const config = await import("./config.js");
+
+  const task = await api.getTask(taskId);
+  const cfg = config.load();
+  const model = opts.model || cfg.defaultModel;
+
+  if (task.status === "in_progress") {
+    await api.stopTask(taskId, "Resuming with fixes");
+  }
+
+  // Find parent Captain thread by searching recent threads for this task
+  if (opts.mode === "captain") {
+    const parentThreadId = await findParentThread(api, taskId, task.id);
+    if (parentThreadId) {
+      const message = buildMessage(task, opts.prompt, opts.fix);
+      await api.messageThread(parentThreadId, message, { model });
+      return { threadId: parentThreadId, originalTask: task.identifier, resumed: true };
+    }
+  }
+
+  // Fallback: no parent thread found (standalone build task, or old task)
+  const context = await gatherContext(taskId, task, cfg);
+  const fullPrompt = buildNewPrompt(task, context, opts.prompt, opts.fix);
+
+  if (opts.mode === "build") {
+    const data = await api.createTask(fullPrompt, model);
+    return { threadId: data.id, originalTask: task.identifier, resumed: false };
+  }
+
+  const data = await api.createThread(fullPrompt, model);
+  return { threadId: data.id, originalTask: task.identifier, resumed: false };
+}
+
+async function findParentThread(api: typeof import("./api.js"), taskIdentifier: string, taskUuid: string): Promise<string | null> {
+  try {
+    const threads = await api.listThreads({ limit: 50 });
+    for (const thread of threads.items || []) {
+      if (thread.tasks?.some(t => t.identifier === taskIdentifier || t.id === taskUuid)) {
+        return thread.id;
+      }
+    }
+  } catch {}
+  return null;
+}
+
+function buildMessage(task: any, prompt?: string, fix?: string): string {
+  let msg = "";
+  if (fix) msg += fix;
+  if (prompt && prompt !== (task.prompt || task.title)) {
+    msg += (msg ? "\n\n" : "") + prompt;
+  }
+  if (!msg) msg = "Fix the issues from the previous attempt. Include tests. Run tests before completing.";
+  return msg;
+}
+
+async function gatherContext(taskId: string, task: any, cfg: any): Promise<string> {
+  const api = await import("./api.js");
+  const github = await import("./github.js");
+  const greptileApi = await import("./greptile.js");
+
+  let context = `Previous attempt: ${task.identifier} "${task.title}" [${task.status}]\n`;
+
+  try {
+    const d = await api.getDiff(taskId);
+    if (d.stats?.files && d.stats.files > 0) {
+      context += `\nPrevious diff: +${d.stats.additions} -${d.stats.deletions} in ${d.stats.files} files\n`;
+      context += `Files changed: ${(d.files || []).map((f: any) => f.path).join(", ")}\n`;
+    } else {
+      context += `\nPrevious diff: empty (agent produced no changes)\n`;
+    }
+  } catch { context += "\nPrevious diff: unavailable\n"; }
+
+  if (task.pullRequest?.number) {
+    const repo = task.pullRequest.repoFullName || cfg.repos[0]?.repoFullName || "";
+    const prNum = task.pullRequest.number;
+    const defaultBranch = cfg.repos.find((r: any) => r.repoFullName === repo)?.branch || "main";
+    const reviewComments = github.getPRReviewComments(repo, prNum);
+    const ci = github.getCIStatus(repo, prNum);
+
+    const reviewProvider = cfg.quality?.reviewProvider || "greptile";
+    const hasGreptileKey = !!(cfg.greptileApiKey || process.env.GREPTILE_API_KEY);
+
+    if ((reviewProvider === "greptile" || reviewProvider === "both") && hasGreptileKey) {
+      const unaddressed = await greptileApi.getUnaddressedIssues(repo, prNum, defaultBranch);
+      if (unaddressed.length > 0) {
+        context += `\nUnaddressed Greptile issues (${unaddressed.length}):\n`;
+        unaddressed.forEach((u: any) => {
+          context += `  ${u.file}:${u.line}: ${u.body}\n`;
+          if (u.suggestedCode) context += `    Suggested fix: ${u.suggestedCode.slice(0, 200)}\n`;
+        });
+      } else {
+        context += `\nGreptile: all issues addressed\n`;
+      }
+    } else {
+      const issueComments = github.getPRIssueComments(repo, prNum);
+      const greptileReview = github.parseGreptileReview(issueComments);
+      if (greptileReview) {
+        context += `\nGreptile review: ${greptileReview.score}/5 (stale, may not reflect latest)\n`;
+      }
+    }
+
+    if (ci && !ci.allGreen) {
+      context += `\nCI failures: ${ci.failing.map((f: any) => f.name).join(", ")}\n`;
+    }
+    if (reviewComments.length) {
+      context += `\nReview comments (${reviewComments.length}):\n`;
+      reviewComments.slice(0, 5).forEach((c: any) => {
+        context += `  ${c.path}:${c.line || "?"}: ${(c.body || "").slice(0, 150)}\n`;
+      });
+    }
+  }
+
+  return context;
+}
+
+function buildNewPrompt(task: any, context: string, prompt?: string, fix?: string): string {
+  let p = `RESUME: Continuing from a previous attempt.\n\n`;
+  p += `Original task: ${task.prompt || task.title}\n\n`;
+  p += `--- CONTEXT FROM PREVIOUS ATTEMPT ---\n${context}\n`;
+  if (fix) p += `--- SPECIFIC FIX REQUESTED ---\n${fix}\n\n`;
+  if (prompt && prompt !== (task.prompt || task.title)) p += `--- UPDATED INSTRUCTIONS ---\n${prompt}\n\n`;
+  p += `--- INSTRUCTIONS ---\n`;
+  p += `Fix the issues from the previous attempt. Do not repeat the same mistakes.\n`;
+  p += `Include tests. Run tests before completing. Verify CI will pass.\n`;
+  return p;
+}

package/src/watch.ts

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { execSync, execFileSync } from "node:child_process";
 import * as config from "./config.js";
+import { shellEscape } from "./commands/_shared.js";
 import type { WatchEntry } from "./types.js";
 
 function getCrontab(): string {
@@ -54,7 +55,7 @@ export function notify(text: string): boolean {
   const cmd = cfg.notifyCommand;
   if (!cmd) return false;
   try {
-    execSync(cmd.replace("{text}", text.replace(/'/g, "'\\''")), {
+    execSync(cmd.replace("{text}", shellEscape(text)), {
       timeout: 15000, stdio: "pipe",
     });
     return true;