capyai 0.4.1 → 0.5.1

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,6 +24,7 @@ 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),

package/package.json

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

package/skills/capy/SKILL.md

@@ -3,101 +3,281 @@ 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.1"
+  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
+
+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:**
 
-```bash
-npm i -g capyai
-capy init
 ```
+[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
+```
+
+`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
 
-Or set env vars directly:
 ```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).
 
-- **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
+| 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"` |
 
-Configure which run via `capy config quality.reviewProvider greptile|capy|both|none`.
+## Commands reference
 
-## JSON output
+All commands support `--json` for structured output. All errors return `{ "error": { "code": "...", "message": "..." } }`.
 
-Every command returns structured JSON with `--json`. Errors return `{ "error": { "code": "...", "message": "..." } }`.
+### Start work
 
-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)
+```bash
+capy captain "<prompt>" --json          # → { id, url }
+capy build "<prompt>" --json            # → { id, identifier, status }
+```
+
+Model shortcuts: `--opus`, `--sonnet`, `--mini`, `--fast`, `--kimi`, `--gemini`, `--grok`, `--qwen`, or `--model=<id>`.
+
+### 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."
+Captain and Build need different prompting styles.
+
+**Captain** has full codebase context and plans its own approach. Tell it WHAT to accomplish, not HOW. Link the issue, set the quality bar, get out of its way.
+
+Bad: `"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/."`
+
+Good: `"We have a CI failure on the crypto-trading pack — missing changeset. Fix it. Reference: PLW-201. Don't finish until CI is green and tests pass."`
+
+Good: `"https://linear.app/plaw/issue/PLW-201 — get this done. Make sure all tests pass, CI is green, and code review comes back clean."`
+
+Captain prompts should include:
+- What the problem or goal is (natural language)
+- A link to the issue if one exists (GitHub, Linear)
+- The quality bar ("tests pass", "CI green", "code review clean")
+
+Do NOT include specific files, specific commands, or implementation details. Captain figures that out.
+
+**Build** is isolated and has no codebase context. Be specific. Name the files, the commands, the acceptance criteria.
 
-Specific files, specific functions, specific acceptance criteria.
+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."`
 
 ## 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}`);

package/src/commands/monitoring.ts

@@ -1,5 +1,5 @@
 import { defineCommand } from "citty";
-import { jsonArg } from "./_shared.js";
+import { jsonArg, isThreadId } from "./_shared.js";
 
 export const watch = defineCommand({
   meta: { name: "watch", description: "Poll + notify on completion" },
@@ -14,7 +14,7 @@ export const watch = defineCommand({
     const fmt = await import("../output.js");
 
     const interval = Math.max(1, Math.min(parseInt(args.interval) || config.load().watchInterval, 30));
-    const type = (args.id.length > 20 || (args.id.length > 10 && !args.id.match(/^[A-Z]+-\d+$/))) ? "thread" : "task";
+    const type = isThreadId(args.id) ? "thread" : "task";
     const added = w.add(args.id, type, interval);
 
     if (args.json) { fmt.out({ id: args.id, type, interval, added }); return; }
@@ -70,7 +70,7 @@ export const wait = defineCommand({
 
     const timeoutMs = Math.max(10, parseInt(args.timeout) || 300) * 1000;
     const intervalMs = Math.max(5, Math.min(parseInt(args.interval) || 10, 60)) * 1000;
-    const isThread = args.id.length > 20 || (args.id.length > 10 && !args.id.match(/^[A-Z]+-\d+$/));
+    const isThread = isThreadId(args.id);
     const terminalTask = new Set(["needs_review", "archived", "completed", "failed"]);
     const terminalThread = new Set(["idle", "archived", "completed"]);
     const terminal = isThread ? terminalThread : terminalTask;
@@ -78,19 +78,25 @@ export const wait = defineCommand({
     const start = Date.now();
     if (!args.json) process.stderr.write(`Waiting for ${args.id} (${isThread ? "thread" : "task"})...`);
 
+    let lastStatus = "unknown";
     while (Date.now() - start < timeoutMs) {
-      const data = isThread ? await api.getThread(args.id) : await api.getTask(args.id);
-      if (terminal.has(data.status)) {
-        if (args.json) { fmt.out(data); return; }
-        console.log(`\n${isThread ? "Thread" : "Task"} ${data.status}.`);
-        return;
+      try {
+        const data = isThread ? await api.getThread(args.id) : await api.getTask(args.id);
+        lastStatus = data.status;
+        if (terminal.has(data.status)) {
+          if (args.json) { fmt.out(data); return; }
+          console.log(`\n${isThread ? "Thread" : "Task"} ${data.status}.`);
+          return;
+        }
+      } catch {
+        // transient error during poll, keep trying
       }
       if (!args.json) process.stderr.write(".");
       await new Promise(r => setTimeout(r, intervalMs));
     }
 
-    if (args.json) { fmt.out({ error: { code: "timeout", message: `Timed out after ${args.timeout}s` } }); process.exit(1); }
-    console.error(`\ncapy: timed out after ${args.timeout}s`);
+    if (args.json) { fmt.out({ error: { code: "timeout", message: `Timed out after ${args.timeout}s`, lastStatus } }); process.exit(1); }
+    console.error(`\ncapy: timed out after ${args.timeout}s (last status: ${lastStatus})`);
     process.exit(1);
   },
 });

package/src/commands/quality.ts

@@ -209,13 +209,12 @@ export const approve = defineCommand({
       const approveCmd = cfg.approveCommand;
       if (approveCmd) {
         try {
-          const { execFileSync } = await import("node:child_process");
-          const parts = approveCmd
+          const { execSync } = await import("node:child_process");
+          const expanded = approveCmd
             .replace("{task}", task.identifier || task.id)
-            .replace("{title}", task.title || "")
-            .replace("{pr}", String(task.pullRequest?.number || ""))
-            .split(/\s+/);
-          execFileSync(parts[0], parts.slice(1), { encoding: "utf8", timeout: 15000, stdio: "pipe" });
+            .replace("{title}", (task.title || "").replace(/'/g, "'\\''"))
+            .replace("{pr}", String(task.pullRequest?.number || ""));
+          execSync(expanded, { timeout: 15000, stdio: "pipe" });
           log.info("Post-approve hook ran.");
         } catch {}
       }

package/src/commands/setup.ts

@@ -133,6 +133,50 @@ export const config = defineCommand({
   },
 });
 
+const projectsList = defineCommand({
+  meta: { name: "list", description: "List projects" },
+  args: { ...jsonArg },
+  async run({ args }) {
+    const api = await import("../api.js");
+    const fmt = await import("../output.js");
+
+    const projects = await api.listProjectsAuth();
+    if (args.json) { fmt.out(projects); return; }
+    if (!projects.length) { console.log("No projects."); return; }
+    fmt.table(["ID", "NAME", "CODE", "REPOS"], projects.map(p => [
+      p.id.slice(0, 16), p.name, p.taskCode, String(p.repos.length),
+    ]));
+  },
+});
+
+const projectsGet = defineCommand({
+  meta: { name: "get", description: "Project details" },
+  args: {
+    id: { type: "positional", required: false, description: "Project ID (defaults to current)" },
+    ...jsonArg,
+  },
+  async run({ args }) {
+    const api = await import("../api.js");
+    const fmt = await import("../output.js");
+    const { log } = await import("@clack/prompts");
+
+    const data = await api.getProject(args.id);
+    if (args.json) { fmt.out(data); return; }
+    log.info(`Project: ${data.name}\nID:      ${data.id}\nCode:    ${data.taskCode}`);
+    if (data.repos.length) {
+      console.log(`Repos:`);
+      data.repos.forEach(r => console.log(`  ${r.repoFullName} (${r.branch})`));
+    }
+    if (data.createdAt) console.log(`Created: ${data.createdAt}`);
+  },
+});
+
+export const projects = defineCommand({
+  meta: { name: "projects", description: "List and manage projects" },
+  default: "list",
+  subCommands: { list: projectsList, get: projectsGet },
+});
+
 export const models = defineCommand({
   meta: { name: "models", description: "List available models" },
   args: { ...jsonArg },
@@ -179,6 +223,7 @@ export const tools = defineCommand({
       watch:      { args: "<id>",                  desc: "Poll + notify on completion" },
       unwatch:    { args: "<id>",                  desc: "Stop watching" },
       watches:    { args: "",                      desc: "List watches" },
+      projects:   { args: "[list|get]",              desc: "List/get projects" },
       pool:       { args: "[status|set|test|...]", desc: "Manage warm pool VMs" },
       models:     { args: "",                      desc: "List models" },
       tools:      { args: "",                      desc: "This list" },

package/src/commands/tasks.ts

@@ -5,14 +5,16 @@ export const list = defineCommand({
   meta: { name: "list", description: "List tasks", alias: "ls" },
   args: {
     status: { type: "positional", required: false, description: "Filter by status" },
+    limit: { type: "string", description: "Max results (default 30)" },
+    cursor: { type: "string", description: "Pagination cursor from previous response" },
     ...jsonArg,
   },
   async run({ args }) {
     const api = await import("../api.js");
     const fmt = await import("../output.js");
 
-    const data = await api.listTasks({ status: args.status });
-    if (args.json) { fmt.out(data.items || []); return; }
+    const data = await api.listTasks({ status: args.status, limit: args.limit ? parseInt(args.limit) : undefined, cursor: args.cursor });
+    if (args.json) { fmt.out({ items: data.items || [], nextCursor: data.nextCursor, hasMore: data.hasMore }); return; }
     if (!data.items?.length) { console.log("No tasks."); return; }
     fmt.table(["ID", "STATUS", "TITLE", "PR"], data.items.map(t => [
       t.identifier,

package/src/commands/threads.ts

@@ -3,13 +3,17 @@ import { jsonArg } from "./_shared.js";
 
 const list = defineCommand({
   meta: { name: "list", description: "List threads" },
-  args: { ...jsonArg },
+  args: {
+    limit: { type: "string", description: "Max results (default 10)" },
+    cursor: { type: "string", description: "Pagination cursor from previous response" },
+    ...jsonArg,
+  },
   async run({ args }) {
     const api = await import("../api.js");
     const fmt = await import("../output.js");
 
-    const data = await api.listThreads();
-    if (args.json) { fmt.out(data.items || []); return; }
+    const data = await api.listThreads({ limit: args.limit ? parseInt(args.limit) : undefined, cursor: args.cursor });
+    if (args.json) { fmt.out({ items: data.items || [], nextCursor: data.nextCursor, hasMore: data.hasMore }); return; }
     if (!data.items?.length) { console.log("No threads."); return; }
     fmt.table(["ID", "STATUS", "TITLE"], data.items.map(t => [
       t.id.slice(0, 16), t.status, (t.title || "(untitled)").slice(0, 40),

package/src/commands/triage.ts

@@ -24,6 +24,7 @@ export const triage = defineCommand({
   meta: { name: "triage", description: "Actionable status for all tasks with diffs, PR state, and recommendations" },
   args: {
     ids: { type: "positional", required: false, description: "Specific task IDs (comma-separated or space-separated)" },
+    brief: { type: "boolean", description: "Fast mode: skip diff fetching, just categorize by status + PR state", default: false },
     ...jsonArg,
   },
   async run({ args }) {
@@ -52,13 +53,15 @@ export const triage = defineCommand({
     }
 
     // Fetch detail + diff in parallel for all tasks
+    const brief = !!args.brief;
+    let results: Awaited<ReturnType<typeof enrichTasks>>;
     if (!args.json) {
       const s = spinner();
-      s.start(`Loading ${tasks.length} tasks (details + diffs)...`);
-      var results = await enrichTasks(api, tasks, cfg);
+      s.start(`Loading ${tasks.length} tasks${brief ? "" : " (details + diffs)"}...`);
+      results = await enrichTasks(api, tasks, cfg, brief);
       s.stop(`${tasks.length} tasks loaded`);
     } else {
-      var results = await enrichTasks(api, tasks, cfg);
+      results = await enrichTasks(api, tasks, cfg, brief);
     }
 
     // Cross-ref PR state with GitHub
@@ -85,10 +88,12 @@ export const triage = defineCommand({
         category = "ready";
       } else if (r.diff && r.diff.files > 0 && !r.pr) {
         category = "needs_pr";
-      } else if (r.status === "needs_review" && (!r.diff || r.diff.files === 0)) {
-        category = "stuck";
+      } 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 = "needs_pr";
       } else {
         category = "stuck";
       }
@@ -212,23 +217,23 @@ export const triage = defineCommand({
   },
 });
 
-async function enrichTasks(api: typeof import("../api.js"), tasks: any[], cfg: any) {
-  // Fetch full details and diffs in parallel batches
+async function enrichTasks(api: typeof import("../api.js"), tasks: any[], cfg: any, brief = false) {
   const enriched = await Promise.all(tasks.map(async (task) => {
     const id = task.identifier || task.id;
     let detail: any = task;
     let diff: any = null;
 
     try {
-      // Only fetch detail if list response (no jams field)
       if (!task.jams) {
         detail = await api.getTask(id);
       }
     } catch {}
 
-    try {
-      diff = await api.getDiff(id);
-    } catch {}
+    if (!brief) {
+      try {
+        diff = await api.getDiff(id);
+      } catch {}
+    }
 
     const lastJam = (detail.jams || []).at(-1);
     const credits = lastJam?.credits;

package/src/config.ts

@@ -13,10 +13,8 @@ const DEFAULTS: CapyConfig = {
   repos: [],
   defaultModel: "gpt-5.4",
   quality: {
-    minReviewScore: 4,
     requireCI: true,
     requireTests: true,
-    requireLinearLink: true,
     reviewProvider: "greptile",
   },
   watchInterval: 3,
@@ -56,7 +54,7 @@ export function load(): CapyConfig {
 
 export function save(cfg: CapyConfig): void {
   fs.mkdirSync(CONFIG_DIR, { recursive: true });
-  fs.writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2) + "\n");
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2) + "\n", { mode: 0o600 });
 }
 
 export function get(key: string): unknown {

package/src/github.ts

@@ -42,7 +42,7 @@ export function getCIStatus(repo: string, number: number, prData?: PRData | null
   const checks: StatusCheck[] = pr.statusCheckRollup || [];
   const total = checks.length;
   const passing = checks.filter(c =>
-    c.conclusion === "SUCCESS" || c.conclusion === "NEUTRAL" || c.status === "COMPLETED"
+    c.conclusion === "SUCCESS" || c.conclusion === "NEUTRAL"
   ).length;
   const failing = checks.filter(c =>
     c.conclusion === "FAILURE" || c.conclusion === "ERROR" || c.conclusion === "TIMED_OUT"

package/src/mcp.ts

@@ -5,6 +5,7 @@ import { createRequire } from "node:module";
 import * as api from "./api.js";
 import { CapyError } from "./api.js";
 import * as config from "./config.js";
+import { isThreadId } from "./commands/_shared.js";
 
 const require = createRequire(import.meta.url);
 const { version } = require("../package.json");
@@ -26,10 +27,6 @@ function structured(data: Record<string, unknown>) {
   return { structuredContent: data, content: [{ type: "text" as const, text: JSON.stringify(data) }] };
 }
 
-function isThreadId(id: string): boolean {
-  return id.length > 20 || (id.length > 10 && !id.match(/^[A-Z]+-\d+$/));
-}
-
 // --- Orchestration ---
 
 server.registerTool("capy_captain", {
@@ -89,12 +86,17 @@ server.registerTool("capy_wait", {
       : new Set(["needs_review", "archived", "completed", "failed"]);
 
     const start = Date.now();
+    let lastData: any = null;
     while (Date.now() - start < timeoutMs) {
-      const data = isThread ? await api.getThread(id) : await api.getTask(id);
-      if (terminal.has(data.status)) return text(data);
+      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
+      }
       await new Promise(r => setTimeout(r, intervalMs));
     }
-    return { content: [{ type: "text" as const, text: JSON.stringify({ error: { code: "timeout", message: `Timed out after ${timeout || 300}s` } }) }], isError: true as const };
+    return { content: [{ type: "text" as const, text: JSON.stringify({ error: { code: "timeout", message: `Timed out after ${timeout || 300}s`, lastStatus: lastData?.status || "unknown" } }) }], isError: true as const };
   } catch (e) { return err(e); }
 });
 
@@ -103,15 +105,6 @@ server.registerTool("capy_review", {
   inputSchema: {
     id: z.string().describe("Task ID"),
   },
-  outputSchema: {
-    task: z.string(),
-    quality: z.object({
-      pass: z.boolean(),
-      passed: z.number(),
-      total: z.number(),
-      summary: z.string(),
-    }),
-  },
   annotations: { readOnlyHint: true },
 }, async ({ id }) => {
   try {
@@ -134,6 +127,12 @@ server.registerTool("capy_approve", {
   outputSchema: {
     task: z.string(),
     approved: z.boolean(),
+    quality: z.object({
+      pass: z.boolean(),
+      passed: z.number(),
+      total: z.number(),
+      summary: z.string(),
+    }),
   },
   annotations: { openWorldHint: true },
 }, async ({ id, force }) => {
@@ -146,13 +145,12 @@ server.registerTool("capy_approve", {
 
     if (approved && cfg.approveCommand) {
       try {
-        const { execFileSync } = await import("node:child_process");
-        const parts = cfg.approveCommand
+        const { execSync } = await import("node:child_process");
+        const expanded = cfg.approveCommand
           .replace("{task}", task.identifier || task.id)
-          .replace("{title}", task.title || "")
-          .replace("{pr}", String(task.pullRequest?.number || ""))
-          .split(/\s+/);
-        execFileSync(parts[0], parts.slice(1), { encoding: "utf8", timeout: 15000, stdio: "pipe" });
+          .replace("{title}", (task.title || "").replace(/'/g, "'\\''"))
+          .replace("{pr}", String(task.pullRequest?.number || ""));
+        execSync(expanded, { timeout: 15000, stdio: "pipe" });
       } catch {}
     }
 
@@ -201,12 +199,13 @@ server.registerTool("capy_retry", {
 });
 
 server.registerTool("capy_triage", {
-  description: "Actionable triage of all tasks. Fetches details + diffs in parallel. Categorizes into: merged, ready, needs_pr, stuck, backlog, in_progress. Includes diff stats, PR state, credit usage, and recommendations.",
+  description: "Actionable triage of all tasks. Categorizes into: merged, ready, needs_pr, stuck, backlog, in_progress. Use brief=true for fast mode (skips diff fetching, ~2x faster).",
   inputSchema: {
     ids: z.array(z.string()).optional().describe("Specific task IDs to triage. Omit for all tasks."),
+    brief: z.boolean().optional().describe("Skip diff fetching for speed. Categories based on status + PR state only."),
   },
   annotations: { readOnlyHint: true },
-}, async ({ ids }) => {
+}, async ({ ids, brief }) => {
   try {
     const github = await import("./github.js");
     const cfg = config.load();
@@ -224,7 +223,7 @@ server.registerTool("capy_triage", {
       let detail: any = task;
       let diff: any = null;
       try { if (!task.jams) detail = await api.getTask(id); } catch {}
-      try { diff = await api.getDiff(id); } catch {}
+      if (!brief) { try { diff = await api.getDiff(id); } catch {} }
 
       if (detail.pullRequest?.number && detail.pullRequest.state === "closed") {
         const repo = detail.pullRequest.repoFullName || cfg.repos[0]?.repoFullName;
@@ -245,7 +244,9 @@ server.registerTool("capy_triage", {
       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" && (!diffStats || diffStats.files === 0)) category = "stuck";
+      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 {
@@ -464,6 +465,35 @@ server.registerTool("capy_re_review", {
   } catch (e) { return err(e); }
 });
 
+server.registerTool("capy_projects", {
+  description: "List all projects accessible with the current API key",
+  inputSchema: {},
+  annotations: { readOnlyHint: true, idempotentHint: true },
+}, async () => {
+  try {
+    const data = await api.listProjectsAuth();
+    return text(data);
+  } catch (e) { return err(e); }
+});
+
+server.registerTool("capy_project", {
+  description: "Get project details (repos, task code, config)",
+  inputSchema: {
+    id: z.string().optional().describe("Project ID (defaults to current project)"),
+  },
+  outputSchema: {
+    id: z.string(),
+    name: z.string(),
+    taskCode: z.string(),
+  },
+  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 });
+  } catch (e) { return err(e); }
+});
+
 server.registerTool("capy_models", {
   description: "List available AI models",
   inputSchema: {},
@@ -505,6 +535,17 @@ server.registerTool("capy_pool_update", {
   } catch (e) { return err(e); }
 });
 
+server.registerTool("capy_pool_test", {
+  description: "Test warm pool VM boot with setup commands",
+  inputSchema: {},
+  annotations: { openWorldHint: true },
+}, async () => {
+  try {
+    const data = await api.testWarmPool();
+    return text(data);
+  } catch (e) { return err(e); }
+});
+
 server.registerTool("capy_pool_instances", {
   description: "List warm pool VM instances",
   inputSchema: {

package/src/types.ts

@@ -1,8 +1,6 @@
 export interface QualityConfig {
-  minReviewScore: number;
   requireCI: boolean;
   requireTests: boolean;
-  requireLinearLink: boolean;
   reviewProvider: string;
 }
 

package/src/watch.ts

@@ -51,11 +51,11 @@ export function list(): WatchEntry[] {
 
 export function notify(text: string): boolean {
   const cfg = config.load();
-  const cmd = cfg.notifyCommand || "openclaw system event --text {text} --mode now";
+  const cmd = cfg.notifyCommand;
+  if (!cmd) return false;
   try {
-    const parts = cmd.replace("{text}", text).split(/\s+/);
-    execFileSync(parts[0], parts.slice(1), {
-      encoding: "utf8", timeout: 15000, stdio: "pipe",
+    execSync(cmd.replace("{text}", text.replace(/'/g, "'\\''")), {
+      timeout: 15000, stdio: "pipe",
     });
     return true;
   } catch { return false; }