capyai 0.4.0 → 0.5.0

package/AGENTS.md

@@ -81,7 +81,7 @@ Config file locations:
 - Claude Desktop: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
 - Cursor: `.cursor/mcp.json`
 
-21 MCP tools with full API parity:
+25 MCP tools with full API parity:
 
 | Tool | What it does | Annotations |
 |------|-------------|-------------|
@@ -104,8 +104,12 @@ Config file locations:
 | `capy_models` | List models | readOnly, idempotent |
 | `capy_pool_status` | Warm pool config + VM status | readOnly, idempotent |
 | `capy_pool_update` | Update warm pool config | openWorld |
+| `capy_pool_test` | Test VM boot with setup commands | openWorld |
 | `capy_pool_instances` | List warm pool VMs | readOnly, idempotent |
 | `capy_pool_clear` | Clear/refresh warm pool | destructive |
+| `capy_projects` | List all projects | readOnly, idempotent |
+| `capy_project` | Get project details (repos, code, config) | readOnly, idempotent |
+| `capy_triage` | Actionable triage with categories + recs (brief mode available) | readOnly |
 
 Tools with predictable outputs (`capy_captain`, `capy_build`, `capy_review`, `capy_approve`, `capy_retry`) declare `outputSchema` for typed structured content per the 2025-03-26 MCP spec.
 
@@ -123,128 +127,12 @@ capy models --json
 
 You are now fully configured.
 
----
+## Usage
 
-## How to use capyai
-
-### Delegate work
-
-```bash
-capy captain "Implement feature X. Files: src/foo.ts. Tests required." --json
-```
-
-Returns `{ "threadId": "...", "url": "..." }`. Save the `threadId`.
-
-### Wait for completion
+For the full operating manual (commands, workflows, decision trees, guardrails), install the capy skill:
 
 ```bash
-capy wait <threadId> --timeout=600 --json
-```
-
-Blocks until the thread reaches a terminal state. Returns the full thread object with `tasks` array. Each task has an `identifier` (like `SCO-1`).
-
-### Review quality
-
-```bash
-capy review <taskId> --json
-```
-
-Returns `{ "task": "SCO-1", "quality": { "pass": true, "passed": 5, "total": 5, "gates": [...] } }`.
-
-Read `quality.pass`. If `true`, approve. If `false`, read `quality.gates` for what failed.
-
-### Approve or retry
-
-```bash
-# If quality.pass is true:
-capy approve <taskId> --json
-
-# If quality.pass is false:
-capy retry <taskId> --fix="describe what to fix" --json
-```
-
-`retry` returns `{ "newThread": "..." }`. Wait on that new thread ID, then review again.
-
-### The full loop
-
-```bash
-THREAD=$(capy captain "your prompt" --json | jq -r '.threadId')
-capy wait "$THREAD" --timeout=600 --json
-
-TASK=$(capy threads get "$THREAD" --json | jq -r '.tasks[0].identifier')
-QUALITY=$(capy review "$TASK" --json)
-PASS=$(echo "$QUALITY" | jq -r '.quality.pass')
-
-while [ "$PASS" != "true" ]; do
-  GATES=$(echo "$QUALITY" | jq -r '.quality.gates[] | select(.pass == false) | .name + ": " + .detail')
-  NEW=$(capy retry "$TASK" --fix="Fix these failures: $GATES" --json | jq -r '.newThread')
-  capy wait "$NEW" --timeout=600 --json
-  TASK=$(capy threads get "$NEW" --json | jq -r '.tasks[0].identifier')
-  QUALITY=$(capy review "$TASK" --json)
-  PASS=$(echo "$QUALITY" | jq -r '.quality.pass')
-done
-
-capy approve "$TASK" --json
-```
-
-### Background monitoring
-
-For async fire-and-forget work. Sets a cron job that polls and runs your notification command when done.
-
-```bash
-capy watch <threadId>
-capy config notifyCommand "<your notification command> {text}"
+npx skills add yazcaleb/capy-cli
 ```
 
-`{text}` is replaced with a summary when the task completes. Examples:
-- `openclaw system event --text {text} --mode now`
-- `echo {text} >> ~/capy-notifications.log`
-
-List watches: `capy watches --json`. Remove: `capy unwatch <id>`.
-
-### All commands
-
-Every command supports `--json` for structured output. Errors always return `{ "error": { "code": "...", "message": "..." } }`.
-
-| Command | What it does |
-|---------|-------------|
-| `capy captain "<prompt>"` | Start Captain thread |
-| `capy build "<prompt>"` | Start Build agent (small isolated tasks) |
-| `capy start <id>` | Start/resume a backlog task |
-| `capy stop <id> [reason]` | Stop a running task |
-| `capy msg <id> "<text>"` | Message a running task |
-| `capy wait <id> --timeout=N` | Block until terminal state |
-| `capy review <id>` | Run quality gates (pass/fail) |
-| `capy re-review <id>` | Trigger fresh Greptile review |
-| `capy approve <id>` | Approve if gates pass |
-| `capy retry <id> --fix="..."` | Retry with context from failure |
-| `capy status` | Dashboard (all threads + tasks) |
-| `capy list [status]` | List tasks (filter: in_progress, needs_review, backlog, archived) |
-| `capy get <id>` | Task details (jams, PR state, credits) |
-| `capy diff <id>` | View diff (file-by-file with patches) |
-| `capy pr <id> [title]` | Create PR for a task |
-| `capy watch <id>` | Cron poll + notify on completion |
-| `capy unwatch <id>` | Stop watching |
-| `capy watches` | List active watches |
-| `capy threads list` | List Captain threads |
-| `capy threads get <id>` | Thread details (tasks, PRs) |
-| `capy threads msg <id> "<text>"` | Message a thread |
-| `capy threads stop <id>` | Stop a thread |
-| `capy threads messages <id>` | Read thread conversation history |
-| `capy pool` | Warm pool status |
-| `capy pool set --size=N --age=M` | Update warm pool config |
-| `capy pool test` | Test VM boot |
-| `capy pool instances [status]` | List pool VMs |
-| `capy pool instance <id>` | VM detail + logs |
-| `capy pool clear [--replenish]` | Clear/refresh pool |
-| `capy config [key] [value]` | Get/set config |
-| `capy models` | List available models |
-| `capy tools` | Show all commands + env vars |
-
-### Prompting tips
-
-Bad: `"Fix the CI issue"`
-
-Good: `"Fix CI for crypto-trading pack. The changeset file is missing. Add a changeset entry for @veto/crypto-trading. Run changeset validation. Reference: PLW-201."`
-
-Always include: specific files, specific functions, acceptance criteria, references to related tasks/issues.
+This loads `skills/capy/SKILL.md` into your context with everything you need to orchestrate Capy agents.

package/README.md

@@ -54,6 +54,8 @@ Every command supports `--json` for machine-readable output.
 | `capy pr <id>` | Create PR for task |
 | `capy watch <id>` | Cron poll + notify on completion |
 | `capy threads [list\|get\|msg\|stop\|messages]` | Manage Captain threads |
+| `capy projects [list\|get]` | List/get projects |
+| `capy triage [ids] [--brief]` | Actionable triage with categories + recommendations |
 | `capy pool [status\|set\|test\|instances\|clear]` | Manage warm pool VMs |
 | `capy models` | List available models |
 | `capy config [key] [value]` | Get/set config |
@@ -88,7 +90,7 @@ For agents that prefer MCP over CLI:
 }
 ```
 
-21 tools with full API parity, including warm pool management.
+25 tools with full API parity, including projects, triage, and warm pool management.
 
 ## Config
 

package/bin/capy.ts

@@ -24,9 +24,11 @@ const main = defineCommand({
     msg:         () => import("../src/commands/tasks.js").then(m => m.msg),
     diff:        () => import("../src/commands/diff-pr.js").then(m => m.diff),
     pr:          () => import("../src/commands/diff-pr.js").then(m => m.pr),
+    projects:    () => import("../src/commands/setup.js").then(m => m.projects),
     models:      () => import("../src/commands/setup.js").then(m => m.models),
     tools:       () => import("../src/commands/setup.js").then(m => m.tools),
     status:      () => import("../src/commands/setup.js").then(m => m.status),
+    triage:      () => import("../src/commands/triage.js").then(m => m.triage),
     review:      () => import("../src/commands/quality.js").then(m => m.review),
     "re-review": () => import("../src/commands/quality.js").then(m => m.reReview),
     approve:     () => import("../src/commands/quality.js").then(m => m.approve),

package/package.json

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

package/skills/capy/SKILL.md

@@ -3,101 +3,272 @@ 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.4.0"
+  version: "0.5.0"
 ---
 
 # capy
 
-Orchestrate Capy.ai coding agents. Start tasks, wait for them, enforce quality gates, approve or retry. Works with any AI agent (Claude Code, Codex, OpenClaw, Poke).
+You orchestrate Capy.ai coding agents. You start them, wait for them, gate their output on quality, then approve or retry. This skill makes you a 10x Capy orchestrator.
 
-## Install
+## When to use this skill
 
-```bash
-npm i -g capyai
-capy init
+Use capy when the user wants to:
+- Delegate coding work to an AI agent (not do it locally)
+- Check on tasks running on Capy (status, triage, review)
+- Approve, retry, or stop Capy tasks
+- Create PRs for completed Capy work
+- Manage Capy projects, warm pool VMs, or configuration
+
+Do NOT use capy when:
+- The user wants you to write code yourself (just write it)
+- The user is talking about a different CI/CD system
+- The task is too small to delegate (a one-line fix, a config change)
+
+## Core objects
+
+Understand these three objects before doing anything.
+
+**Thread** — A Captain session. You give it a prompt, it plans and may spawn multiple tasks. Threads have long opaque IDs (UUIDs). Terminal states: `idle`, `archived`, `completed`. You start threads with `capy captain`.
+
+**Task** — A single unit of coding work. Has a short identifier like `SCO-15`. A task produces a diff (code changes) and optionally a pull request. Terminal states: `needs_review`, `archived`, `completed`, `failed`. You start standalone tasks with `capy build`.
+
+**Jam** — An execution run inside a task. Each jam has a model, a status, and credit usage. A task can have multiple jams (one per retry). When `jam.status` is `"idle"` and credits are zero, that jam is finished. The task is done working. You cannot send it more messages.
+
+**Lifecycle:**
+
+```
+[you] captain/build
+  → [capy agent] in_progress (writing code, running tests)
+  → [capy agent] needs_review (agent stopped, diff may exist)
+  → [you] check diff, create PR, run quality gates
+  → [you] approve OR retry
 ```
 
-Or set env vars directly:
+`needs_review` means the agent finished working. It does NOT mean the code is ready to merge. You must still check the diff, create a PR, review quality gates, and approve.
+
+## Decision tree
+
+When you encounter a task, look at its status and act accordingly. Do exactly one thing.
+
+**If status is `in_progress`:**
+→ Wait for it. `capy wait <id> --timeout=600 --json`
+
+**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`
+3. If diff exists but no PR:
+   → Create a PR first: `capy pr <id> --json`
+   → Then review: `capy review <id> --json`
+4. If diff exists and PR exists:
+   → Review: `capy review <id> --json`
+   → If `quality.pass` is true → `capy approve <id> --json`
+   → If `quality.pass` is false → check which gates failed (see Quality Gates section)
+
+**If status is `backlog`:**
+→ Start it. `capy start <id> --json`
+
+**If status is `failed`:**
+→ Retry. `capy retry <id> --fix="..." --json`
+
+**If status is `archived`:**
+→ Ignore. This task is dead.
+
+**If PR state is `merged`:**
+→ Done. Nothing to do.
+
+## Guardrails
+
+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.
+
+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.
+
+4. **Never retry infinitely.** Cap retries at 3 attempts. After 3 failures, stop the task with `capy stop <id>` and tell the user. Each retry costs LLM and VM credits.
+
+5. **If Greptile says "Review still processing", wait and re-check.** Do NOT retry the task. The code is fine, the review just hasn't finished. Wait 60 seconds, then run `capy review <id> --json` again.
+
+6. **Captain threads can spawn multiple tasks.** After `capy wait` on a thread, check ALL tasks in the response, not just `tasks[0]`. Review and approve each one.
+
+7. **The Capy API reports merged PRs as "closed".** The CLI cross-references with GitHub to show the real state. Trust the CLI output.
+
+## Workflow: Start new work
+
 ```bash
-export CAPY_API_KEY=capy_...
-export CAPY_PROJECT_ID=...
+# 1. Start a Captain thread
+RESULT=$(capy captain "Implement feature X. Files: src/foo.ts, src/bar.ts. Include tests. Run tests before finishing." --json)
+THREAD_ID=$(echo "$RESULT" | jq -r '.id')
+
+# 2. Wait for completion (use 600s for Captain, 300s for Build)
+WAIT_RESULT=$(capy wait "$THREAD_ID" --timeout=600 --json)
+
+# 3. Check if wait timed out
+if echo "$WAIT_RESULT" | jq -e '.error' > /dev/null 2>&1; then
+  echo "Timed out. Last status: $(echo "$WAIT_RESULT" | jq -r '.error.lastStatus')"
+  # Decide: wait longer, or stop the thread
+  exit 1
+fi
+
+# 4. Get task identifiers from the thread
+TASKS=$(echo "$WAIT_RESULT" | jq -r '.tasks[].identifier')
+
+# 5. For each task: create PR if needed, review, approve/retry
+for TASK in $TASKS; do
+  # Check if PR exists
+  HAS_PR=$(capy get "$TASK" --json | jq -r '.pullRequest.number // empty')
+  if [ -z "$HAS_PR" ]; then
+    capy pr "$TASK" --json
+  fi
+
+  # Review quality
+  QUALITY=$(capy review "$TASK" --json)
+  PASS=$(echo "$QUALITY" | jq -r '.quality.pass')
+
+  # Retry 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')
+
+    capy wait "$NEW_THREAD" --timeout=600 --json
+    TASK=$(capy threads get "$NEW_THREAD" --json | jq -r '.tasks[0].identifier')
+
+    HAS_PR=$(capy get "$TASK" --json | jq -r '.pullRequest.number // empty')
+    [ -z "$HAS_PR" ] && capy pr "$TASK" --json
+
+    QUALITY=$(capy review "$TASK" --json)
+    PASS=$(echo "$QUALITY" | jq -r '.quality.pass')
+    ATTEMPTS=$((ATTEMPTS + 1))
+  done
+
+  if [ "$PASS" = "true" ]; then
+    capy approve "$TASK" --json
+  else
+    echo "Task $TASK failed after $ATTEMPTS retries"
+  fi
+done
 ```
 
-## Agent workflow
+## Workflow: Triage existing work
 
-The core loop for any agent:
+When the user asks "what's the status" or you need to check on existing tasks:
 
 ```bash
-# 1. Start work
-capy captain "Implement feature X. Files: src/foo.ts. Tests required." --json
+# Fast overview (no diff fetching, 2x faster, good enough for status checks)
+capy triage --brief --json
 
-# 2. Wait for completion (blocks until done)
-capy wait <thread-id> --timeout=600 --json
+# Full detail with diff stats (use when you need to decide actions)
+capy triage --json
 
-# 3. Check quality gates
-capy review <task-id> --json
-# Parse quality.pass boolean
-
-# 4a. If pass: approve
-capy approve <task-id> --json
+# Check specific tasks
+capy triage SCO-15,SCO-24 --json
+```
 
-# 4b. If fail: retry with context
-capy retry <task-id> --fix="fix the failing CI check" --json
-# Go back to step 2
+Triage returns:
+```json
+{
+  "summary": { "total": 26, "merged": 7, "ready": 2, "needs_pr": 11, "stuck": 3, "backlog": 3, "in_progress": 0 },
+  "tasks": [{ "identifier": "SCO-15", "category": "needs_pr", "title": "...", "pr": null, "diff": { "files": 5, "additions": 494 } }],
+  "recommendations": ["Create PRs: SCO-15, SCO-24", "Retry or stop: SCO-21, SCO-22"]
+}
 ```
 
-## Commands
-
-| Command | What it does |
-|---------|-------------|
-| `capy captain "<prompt>"` | Start Captain thread (primary agent) |
-| `capy build "<prompt>"` | Start Build agent (isolated, small tasks) |
-| `capy wait <id>` | Block until task/thread reaches terminal state |
-| `capy review <id>` | Run quality gates (pr_exists, ci, greptile, threads, tests) |
-| `capy approve <id>` | Approve if all gates pass |
-| `capy retry <id> --fix="..."` | Retry with failure context from previous attempt |
-| `capy status` | Dashboard of all threads and tasks |
-| `capy list [status]` | List tasks, optionally filtered |
-| `capy get <id>` | Task or thread details |
-| `capy diff <id>` | View diff from task |
-| `capy pr <id>` | Create PR for task |
-| `capy threads list` | List Captain threads |
-| `capy threads get <id>` | Thread details |
-| `capy threads msg <id> <text>` | Message a thread |
-| `capy threads stop <id>` | Stop a thread |
-| `capy threads messages <id>` | View thread messages |
-
-All commands support `--json` for machine-readable output.
+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>`
+- `backlog` → `capy start <id>` if the user wants it running
+- `merged` → done, ignore
 
 ## Quality gates
 
-`capy review` checks pass/fail gates:
+`capy review <id> --json` returns `quality.pass` (boolean) and `quality.gates` (array of gate results).
+
+| Gate | Checks | When it fails, do this |
+|------|--------|----------------------|
+| `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"` |
+
+## Commands reference
 
-- **pr_exists** — PR was created
-- **pr_open** — PR is OPEN or MERGED
-- **ci** — CI checks passing
-- **greptile** — No unaddressed Greptile issues
-- **threads** — No unresolved GitHub review threads
-- **tests** — Diff includes test files
+All commands support `--json` for structured output. All errors return `{ "error": { "code": "...", "message": "..." } }`.
 
-Configure which run via `capy config quality.reviewProvider greptile|capy|both|none`.
+### Start work
 
-## JSON output
+```bash
+capy captain "<prompt>" --json          # → { id, url }
+capy build "<prompt>" --json            # → { id, identifier, status }
+```
 
-Every command returns structured JSON with `--json`. Errors return `{ "error": { "code": "...", "message": "..." } }`.
+Model shortcuts: `--opus`, `--sonnet`, `--mini`, `--fast`, `--kimi`, `--gemini`, `--grok`, `--qwen`, or `--model=<id>`.
 
-Key fields for agents:
-- `capy review --json` → `quality.pass` (boolean), `quality.gates` (array)
-- `capy wait --json` → full task/thread object on completion, `error.code: "timeout"` on timeout
-- `capy retry --json` → `newThread` (thread ID to wait on)
+### Wait and monitor
+
+```bash
+capy wait <id> --timeout=600 --json     # → full object on success, { error: { code: "timeout", lastStatus } } on timeout
+capy triage [ids] [--brief] --json      # → { summary, tasks, recommendations }
+capy get <id> --json                    # → full task or thread object
+capy list [status] [--limit=N] --json   # → { items, nextCursor, hasMore }
+capy diff <id> --json                   # → { stats: { files, additions, deletions }, files: [...] }
+capy status --json                      # → { threads, tasks, watches }
+```
+
+### Take action
+
+```bash
+capy pr <id> [--draft] [--description="..."] --json   # → { url, number, title }
+capy review <id> --json                                # → { task, quality: { pass, gates }, diff }
+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 }
+capy re-review <id> --json                             # → triggers fresh Greptile review
+```
+
+### Threads
+
+```bash
+capy threads list [--limit=N] --json    # → { items, nextCursor, hasMore }
+capy threads get <id> --json            # → thread with tasks[] and pullRequests[]
+capy threads msg <id> "<text>" --json   # → message result
+capy threads stop <id> --json           # → stop result
+capy threads messages <id> --json       # → conversation history
+```
+
+### Admin
+
+```bash
+capy projects --json                    # → list of projects
+capy projects get [id] --json           # → project details (defaults to current)
+capy models --json                      # → available models
+capy config [key] [value]               # → get/set config
+capy pool [status|set|test|instances|instance|clear]  # → warm pool management
+```
 
 ## Prompting tips
 
-Bad: "Fix the CI issue"
-Good: "Fix CI for crypto-trading pack. The changeset file is missing. Add a changeset entry for @veto/crypto-trading. Run changeset validation. Reference: PLW-201."
+When writing prompts for `capy captain` or `capy build`, be specific. The Capy agent is another AI. Vague prompts produce vague results.
+
+Bad: `"Fix the CI issue"`
+
+Good: `"Fix CI for crypto-trading pack. The changeset file is missing. Add a changeset entry for @veto/crypto-trading with patch bump. Run 'npx changeset status' to validate. Files: packages/crypto-trading/. Reference: PLW-201."`
 
-Specific files, specific functions, specific acceptance criteria.
+Always include:
+- Which files to touch
+- What the acceptance criteria are
+- What commands to run to verify
+- References to related issues or tasks
 
 ## Triggers
 
-Keywords: capy, captain, build agent, quality gates, delegate coding, orchestrate agents, send to capy, approve task, retry task
+Keywords: capy, captain, build agent, quality gates, delegate coding, orchestrate agents, send to capy, approve task, retry task, triage tasks, check capy status, review PR, what's the status

package/src/api.ts

@@ -14,36 +14,58 @@ function fail(code: string, message: string): never {
   throw new CapyError(code, message);
 }
 
+const RETRYABLE_STATUS = new Set([429, 500, 502, 503, 504]);
+const MAX_RETRIES = 3;
+
 async function rawRequest(apiKey: string, server: string, method: string, path: string, body?: unknown): Promise<any> {
   const url = `${server}${path}`;
   const headers: Record<string, string> = {
     "Authorization": `Bearer ${apiKey}`,
     "Accept": "application/json",
   };
-  const init: RequestInit = { method, headers };
   if (body) {
     headers["Content-Type"] = "application/json";
-    init.body = JSON.stringify(body);
   }
 
-  let res: Response;
-  try {
-    res = await fetch(url, init);
-  } catch (e: unknown) {
-    fail("network_error", `request failed — ${(e as Error).message}`);
+  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));
+    }
+
+    let res: Response;
+    try {
+      res = await fetch(url, {
+        method,
+        headers,
+        ...(body ? { body: JSON.stringify(body) } : {}),
+      });
+    } 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 (RETRYABLE_STATUS.has(res.status) && attempt < MAX_RETRIES) {
+      continue;
+    }
+
+    const text = await res.text();
+    let data: any;
+    try {
+      data = JSON.parse(text);
+    } catch {
+      fail("bad_response", `bad API response: ${text.slice(0, 200)}`);
+    }
+    if (data.error) {
+      fail(data.error.code || "api_error", data.error.message || "unknown API error");
+    }
+    return data;
   }
 
-  const text = await res.text();
-  let data: any;
-  try {
-    data = JSON.parse(text);
-  } catch {
-    fail("bad_response", `bad API response: ${text.slice(0, 200)}`);
-  }
-  if (data.error) {
-    fail(data.error.code || "api_error", data.error.message || "unknown API error");
-  }
-  return data;
+  fail("network_error", `request failed after ${MAX_RETRIES + 1} attempts — ${lastError?.message || "unknown"}`);
 }
 
 async function request(method: string, path: string, body?: unknown): Promise<any> {
@@ -73,6 +95,11 @@ export async function listModelsWithKey(apiKey: string, server = "https://capy.a
   return data.models || [];
 }
 
+export async function listProjectsAuth(): Promise<Project[]> {
+  const data = await request("GET", "/projects");
+  return data.items || [];
+}
+
 export async function getProject(id?: string): Promise<Project & { createdAt?: string; updatedAt?: string }> {
   const pid = id || config.load().projectId;
   return request("GET", `/projects/${pid}`);

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 isThreadId(id: string): boolean {
+  return id.length > 20 || (id.length > 10 && !id.match(/^[A-Z]+-\d+$/));
+}
+
 export function resolveModel(args: Record<string, unknown>): string | null {
   if (args.model) return String(args.model);
   if (args.opus)   return "claude-opus-4-6";

package/src/commands/diff-pr.ts

@@ -30,6 +30,8 @@ export const pr = defineCommand({
   args: {
     id: { type: "positional", description: "Task ID", required: true },
     title: { type: "positional", required: false, description: "PR title" },
+    description: { type: "string", description: "PR body/description" },
+    draft: { type: "boolean", description: "Create as draft PR", default: false },
     ...jsonArg,
   },
   async run({ args }) {
@@ -37,7 +39,10 @@ export const pr = defineCommand({
     const fmt = await import("../output.js");
     const { log } = await import("@clack/prompts");
 
-    const body = args.title ? { title: args.title } : {};
+    const body: Record<string, unknown> = {};
+    if (args.title) body.title = args.title;
+    if (args.description) body.description = args.description;
+    if (args.draft) body.draft = true;
     const data = await api.createPR(args.id, body);
     if (args.json) { fmt.out(data); return; }
     log.success(`PR: ${data.url}`);