@synap-core/cli 1.12.2 → 1.13.0

package/dist/index.js

@@ -115,7 +115,7 @@ program
     .option("--api-key <key>", "Hub Protocol API key")
     .option("--name <name>", "Pod profile to use (default: active pod)")
     .option("--list", "List what can be connected and exit")
-    .option("--with-mcp", "Raycast only: also install the full 56-tool MCP server via mcp-remote (names overlap @synap)")
+    .addOption(new Option("--with-mcp", "deprecated, ignored: Raycast always gets the pod's MCP server").hideHelp())
     .option("--target <name>", "Legacy spelling of <thing>")
     .option("--pin-workspace <id>", "Legacy spelling of --workspace")
     .option("--pin-project <id>", "Legacy spelling of --project")
@@ -157,7 +157,8 @@ pods
     .option("--yes", "Non-interactive: skip prompts (won't recreate a rejected key)")
     .action(async (name, url, opts) => {
     const { podsUpdate } = await import("./commands/pods.js");
-    await podsUpdate(name, url, { url: opts.url, yes: opts.yes });
+    if (!(await podsUpdate(name, url, { url: opts.url, yes: opts.yes })))
+        process.exitCode = 1;
 });
 pods
     .command("remove <name>")
@@ -188,6 +189,7 @@ program
     .option("--json", "Output as JSON")
     .option("--fix", "Fix key problems: finish a pending approval, give this computer its own key, or rewrite stale copies — then verify over MCP")
     .option("-v, --verbose", "Every check with its details, ids and addresses")
+    .option("--pod-url <url>", "Probe this pod URL (works with no pod configured)")
     .action(async (opts) => {
     const { doctor } = await import("./commands/doctor.js");
     await doctor(opts);
@@ -468,7 +470,7 @@ program
             }
         }
         else {
-            console.log(chalk.dim("  Later: synap login  ·  or  synap login --token <token>  (synap.live/account/tokens)"));
+            console.log(chalk.dim("  Later: synap login  (prints a link you can open on any device)"));
         }
     }
     const { renderNextSteps, FLOW } = await import("./lib/next-steps.js");
@@ -1041,11 +1043,12 @@ program
     .requiredOption("--agent <name>", "The named agent this machine works as (its key comes from ~/.synap)")
     .option("--interval <dur>", "How often to check for handed sessions (e.g. 30s, 2m)", "30s")
     .option("--once", "Check once, run what is handed, wait for it, exit")
-    .option("--cwd <dir>", "Where the launched Claude Code works (default ~/Documents/Code/synap)")
+    .option("--cwd <dir>", "Where code sessions' Claude Code works (default ~/Documents/Code/synap)")
+    .option("--work-root <dir>", "Where playbook runs over pod data (no repo) get a folder each, <dir>/<session id> (default ~/synap-work)")
     .option("--max-parallel <n>", "Runs at the same time", "1")
     .option("--claude-bin <path>", "The claude binary", "claude")
     .option("--claude-config-dir <dir>", "CLAUDE_CONFIG_DIR for launched runs — picks which Claude subscription they use")
-    .option("--mcp-server <name>", "Claude Code MCP server name for this pod (detected from ~/.claude.json by default)")
+    .option("--accounts <file>", "Claude accounts to rotate across ({version:1, reserve, accounts:[{id,label,token,design?}]}, mode 600); default ~/.config/synap-worker/accounts.json when it exists, else the environment's login")
     .option("--allowed-tools <list>", "Comma-separated Claude tools allowed without asking (the pod MCP server is always added)")
     .option("--skip-permissions", "Launch with --dangerously-skip-permissions instead of an allow-list")
     .option("--dry-run", "Claim and log what would launch, without launching Claude")
@@ -1053,6 +1056,27 @@ program
     const { workerCommand } = await import("./commands/worker.js");
     await workerCommand(opts);
 });
+// ─── box ──────────────────────────────────────────────────────────────────────
+// Run THIS computer as a run box provisioner: lease the box runs queued on the
+// pod, run each in a fresh isolated LXC, hand back the evidence. See src/commands/box.ts.
+const box = program.command("box").description("Run scripts in fresh isolated boxes on this computer (run box provisioner)");
+box
+    .command("serve")
+    .description("Lease queued box runs from the pod and run each in a fresh box")
+    .option("--config <file>", "Provisioner config", "/etc/synap-box/config.json")
+    .option("--once", "Lease at most one run, work it, exit")
+    .action(async (opts) => {
+    const { boxServeCommand } = await import("./commands/box.js");
+    await boxServeCommand(opts);
+});
+box
+    .command("reap")
+    .description("Destroy every box no run holds (after a crash)")
+    .option("--config <file>", "Provisioner config", "/etc/synap-box/config.json")
+    .action(async (opts) => {
+    const { boxReapCommand } = await import("./commands/box.js");
+    await boxReapCommand(opts);
+});
 // ─── session ──────────────────────────────────────────────────────────────────
 // Focus sessions — goal-bound work rooms tracked on the pod.
 // AI agents: use start_session to begin, update_session to report progress,
@@ -1068,7 +1092,7 @@ session
     .option("--workspace <id>", "Workspace that owns the session")
     .option("--project <id>", "Project that owns the session (defaults to the active project lens; the pod accepts a workspace OR a project)")
     .option("--task-id <id>", "Link session to an existing task entity")
-    .option("--track <id>", "Born inside a track (a project's lasting goal) — implies its project")
+    .option("--track <id>", "Born inside a track (a project's goal) — implies its project")
     .option("--template <id>", "Start from a playbook (seeds currentStage from its stages)")
     .option("--no-template", "Opt out of auto-matching a playbook — start ad-hoc")
     .option("--parent <id>", "Push from another session — records session --spawned_from--> session (the parent stays open)")
@@ -1136,6 +1160,8 @@ session
     // TERMINAL_SESSION_STATUSES. Re-listing them here would be a second copy of
     // an enum this CLI cannot import — the hand-mirrored-vocabulary defect.
     .option("--as <status>", "How it ended: closed (default, finished) | cancelled (abandoned) | failed (could not complete)")
+    .option("--withdraw <messageId=note>", "An open question you asked that your work overtook, with why (repeatable)", collect, [])
+    .option("--keep-owed <messageId>", "An open question the person still owes you an answer to after this session (repeatable)", collect, [])
     .option("--json", "Output full pack (or close result) as JSON")
     .option("--pod-url <url>", "Pod URL override")
     .option("--api-key <key>", "API key override")
@@ -1195,19 +1221,55 @@ session
     await evaluateSession(opts);
 });
 session
-    .command("wait <sessionId>")
-    .description("Block until the human replies in the session room, then print the reply. Exit 0 replied · 1 timeout · 2 failure (auth/network/broken read)")
-    .option("--since <iso>", "Only answers strictly after this ISO timestamp (default: now — skips anything that predates this wait)")
+    .command("wait [sessionId]")
+    .description("Block until the human replies in the session room (or, with --events, until the session changes), then print it. Session: the argument, else the one attached to this terminal. Exit 0 replied · 1 timeout · 2 failure (auth/network/broken read); with --hook: 2 wake · 0 anything else")
+    .option("--since <iso>", "Only events strictly after this ISO timestamp (default: now — skips anything that predates this wait; with --events: the unread ones)")
+    .option("--events <kinds>", "Wait on the session change feed: comma list of answer, proposal_decided, stage_moved, owner_message, session_message (a message from another session's agent), or all")
+    .option("--wake-only", "Stop only on what should wake an agent: answers, owner messages, and agent messages the pod marked wake (the rest is read and skipped)")
+    .option("--once", "One read, no waiting loop")
+    .option("--peek", "Mark nothing picked up or read (a watcher that is not the agent doing the work)")
+    .option("--hook", "Run as a Claude Code asyncRewake Stop hook: wait for a wake-worthy event, print it on stderr, exit 2 (see: synap hooks install-wake)")
     .option("--timeout <duration>", "Give up after this long (e.g. 30m, 2h)", "30m")
-    .option("--interval <duration>", "Delay between checks (e.g. 10s)", "10s")
-    .option("--limit <n>", "Max answers per page, 1-100", "20")
-    .option("--json", "Output the reply(ies) — or the timeout — as JSON")
+    .option("--interval <duration>", "Delay between checks of the answer-only wait (e.g. 10s)", "10s")
+    .option("--limit <n>", "Max answers / events per page, 1-100", "20")
+    .option("--json", "Output the reply(ies) or events — or the timeout — as JSON")
     .option("--pod-url <url>", "Pod URL override")
     .option("--api-key <key>", "API key override")
     .action(async (sessionId, opts) => {
     const { waitSessionCommand } = await import("./commands/session-wait.js");
     await waitSessionCommand(sessionId, opts);
 });
+session
+    .command("post <toSessionId> <text...>")
+    .description("Message ANOTHER of your sessions' agent: blocked_on_you / handoff may wake it, done / fyi never do. Replying to a message that woke you? Pass its id as --cause. Exit 0 delivered · 1 pod does not deliver agent messages · 2 failure")
+    .option("--intent <intent>", "blocked_on_you | handoff | done | fyi", "fyi")
+    .option("--cause <messageId>", "The message that woke you (the id `synap session wait` printed), when this replies to it")
+    .option("--from <sessionId>", "Your session, when this terminal is not bound to it")
+    .option("--ref <kind:id[:label]>", "The state behind the message: session:<id>, blocked_by:<id>, proposal:<id>, slot:<sessionId>:<label> (repeatable)", collect, [])
+    .option("--json", "Output the pod's reply as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (toSessionId, text, opts) => {
+    const { sessionPostCommand } = await import("./commands/session-post.js");
+    await sessionPostCommand(toSessionId, text, opts);
+});
+// ─── hooks ────────────────────────────────────────────────────────────────────
+// Claude Code hooks the CLI owns. install-wake: the asyncRewake Stop hook that
+// lets another session's agent (or the person) wake an idle terminal.
+const hooksCmd = program
+    .command("hooks")
+    .description("Claude Code hooks that connect a terminal to its Synap session");
+hooksCmd
+    .command("install-wake")
+    .description("Add the wake hook (a Stop hook running `synap session wait --hook`) to this project's .claude/settings.json — idempotent, other hooks kept")
+    .option("--uninstall", "Remove the wake hook instead")
+    .option("--user", "Use ~/.claude/settings.json (every project) instead of the project's")
+    .option("--dir <path>", "The project directory (default: the current one)")
+    .option("--json", "Output the result as JSON")
+    .action(async (opts) => {
+    const { installWakeCommand } = await import("./commands/hooks.js");
+    installWakeCommand(opts);
+});
 // ─── playbook ─────────────────────────────────────────────────────────────────
 // Start a governed process in one step — the Hub door MCP synap_run_playbook
 // shares. A proposal ("queued for your review") is success.
@@ -1229,17 +1291,20 @@ playbookCmd
     await runPlaybook(ref, opts);
 });
 // ─── track ────────────────────────────────────────────────────────────────────
-// A LASTING goal inside a project, worked in sessions (`session start --track`).
-// Legacy tracks also run a method with steps. Writes are governed —
+// A goal inside a project, worked in sessions (`session start --track`); a
+// person closes it with a verdict. Legacy tracks also run a method with steps. Writes are governed —
 // "queued for your review" is success.
 const track = program
     .command("track")
-    .description("Manage tracks — the lasting goals a project pursues");
+    .description("Manage tracks — the goals a project pursues");
 track
     .command("list")
-    .description("List a project's tracks (defaults to the active project lens)")
+    .description("List a project's goals (the active project lens); with no project in scope, every goal on the pod")
     .option("--project <id>", "Project id (defaults to the active project lens)")
-    .option("--all", "Include archived tracks")
+    .option("--everywhere", "List every goal on the pod, ignoring the project lens")
+    .option("--limit <n>", "Pod-wide: page size (default 50)")
+    .option("--cursor <cursor>", "Pod-wide: the next page (printed under the last one)")
+    .option("--all", "Include dropped (archived) tracks")
     .option("--json", "Output as JSON")
     .option("--pod-url <url>", "Pod URL override")
     .option("--api-key <key>", "API key override")
@@ -1259,12 +1324,18 @@ track
 });
 track
     .command("start")
-    .description("Start a track — a lasting goal — on a project")
+    .description("Start a track — a goal — on a project")
     .option("--name <name>", "The track's name (required without --playbook)")
     .option("--direction <text>", "Where it is heading, one line")
     .option("--playbook <id>", "Legacy: a track template (project-scoped playbook with steps)")
     .option("--project <id>", "Project id (defaults to the active project lens)")
     .option("--param <key=value>", "Answer a declared param (repeatable)", collect, [])
+    .option("--end-state <text>", "What done looks like, in your words")
+    .option("--criterion <text>", "How it is judged done — '[measured|judged|handed_over|learning|decided_outside|certified:] statement'; give 0 or 2-5 (repeatable)", collect, [])
+    .option("--drop-condition <text>", "When to stop pursuing it (repeatable, at most 5)", collect, [])
+    .option("--kind <kind>", "Kind of work: project|flow|operation|investigation|incident|commission|pathway (a proposal until you confirm)")
+    .option("--uncertainty <level>", "How well the way is known: clear|complicated|complex|chaotic|unknown")
+    .option("--loop <on|off|n>", "Let the goal propose its next session: on, off, or n sessions a week")
     .option("--reason <text>", "Why — shown to the reviewer")
     .option("--json", "Output as JSON")
     .option("--pod-url <url>", "Pod URL override")
@@ -1273,6 +1344,37 @@ track
     const { startTrack } = await import("./commands/tracks.js");
     await startTrack(opts);
 });
+track
+    .command("update <id>")
+    .description("Set a goal's direction, KPI and what it holds (each field is written whole; kpi is merged)")
+    .option("--direction <text>", "Where it is heading, one line")
+    .option("--kpi-current <n>", "The KPI's latest value (stated, never measured)")
+    .option("--kpi-target <n>", "Move the KPI's target")
+    .option("--end-state <text>", "What done looks like, in your words")
+    .option("--criterion <text>", "How it is judged done — '[measured|judged|handed_over|learning|decided_outside|certified:] statement'; give 0 or 2-5 (repeatable)", collect, [])
+    .option("--drop-condition <text>", "When to stop pursuing it (repeatable, at most 5)", collect, [])
+    .option("--kind <kind>", "Kind of work: project|flow|operation|investigation|incident|commission|pathway (a proposal until you confirm)")
+    .option("--uncertainty <level>", "How well the way is known: clear|complicated|complex|chaotic|unknown")
+    .option("--loop <on|off|n>", "Let the goal propose its next session: on, off, or n sessions a week")
+    .option("--reason <text>", "Why — shown to the reviewer")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (id, opts) => {
+    const { updateTrack } = await import("./commands/tracks.js");
+    await updateTrack(id, opts);
+});
+track
+    .command("accept <id> <criterion> <decision>")
+    .description("The goal's judge decides a claimed criterion: accepted | changes_asked | rejected (a person's act)")
+    .option("--note <text>", "What to change, or why it was rejected")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (id, criterion, decision, opts) => {
+    const { acceptCriterion } = await import("./commands/tracks.js");
+    await acceptCriterion(id, criterion, decision, opts);
+});
 track
     .command("advance <id> <stage>")
     .description("Legacy (tracks with steps): move a track to a step; prints the session that step offers")
@@ -1286,7 +1388,12 @@ track
 });
 track
     .command("status <id> <status>")
-    .description("Pause, resume or archive a track (active|paused|archived)")
+    .description("Move a track: proposed|agreed|ready|active|paused|completed (Closed)|archived (Dropped). " +
+    "Closing needs --verdict met|partly_met|not_met (an operation closes retired, and only one does); dropping should carry " +
+    "no_longer_needed|impossible|replaced|mistake (impossible and replaced need --verdict-reason). " +
+    "Both are final — reopen makes a new version.")
+    .option("--verdict <verdict>", "How the goal ended (required to close; advised to drop)")
+    .option("--verdict-reason <text>", "Why — required for impossible and replaced")
     .option("--reason <text>", "Why — shown to the reviewer")
     .option("--json", "Output as JSON")
     .option("--pod-url <url>", "Pod URL override")
@@ -1295,6 +1402,34 @@ track
     const { setTrackStatus } = await import("./commands/tracks.js");
     await setTrackStatus(id, status, opts);
 });
+track
+    .command("reopen <id>")
+    .description("Reopen a closed or dropped goal as a NEW version (the old one keeps its verdict)")
+    .option("--name <name>", "A new name (default: the old one's)")
+    .option("--reason <text>", "Why — shown to the reviewer")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (id, opts) => {
+    const { reopenTrack } = await import("./commands/tracks.js");
+    await reopenTrack(id, opts);
+});
+const goal = program
+    .command("goal")
+    .description("Goals — what people call a track");
+goal
+    .command("convert <entityId>")
+    .description("Make a goal, objective or OKR entity a goal (once; the entity is kept and linked)")
+    .option("--project <id>", "The goal's project — only when the entity is filed in none or several")
+    .option("--name <name>", "A name other than the entity's title")
+    .option("--reason <text>", "Why — shown to the reviewer")
+    .option("--json", "Output as JSON")
+    .option("--pod-url <url>", "Pod URL override")
+    .option("--api-key <key>", "API key override")
+    .action(async (entityId, opts) => {
+    const { convertToGoal } = await import("./commands/tracks.js");
+    await convertToGoal(entityId, opts);
+});
 track
     .command("params <id> <pairs...>")
     .description("Answer the method's params as key=value (merged; key=null clears one)")
@@ -1352,6 +1487,7 @@ skillCmd
 skillCmd
     .command("get <slug>")
     .description("Fetch a skill from the knowledge base by slug and print its body")
+    .option("--raw", "Print only the stored body, exactly (for scripts)")
     .option("--pod-url <url>", "Pod URL override")
     .option("--api-key <key>", "API key override")
     .action(async (slug, opts) => {
@@ -1444,7 +1580,7 @@ const observe = program
 observe
     .command("write <text>", { isDefault: true })
     .description("Record an observation about the user (pod-scoped, AI-maintained)")
-    .option("--category <cat>", "working_style | communication | focus | technical | preference", "preference")
+    .option("--category <cat>", "working_style | communication | focus | preferences | habits | technical", "preferences")
     .option("--confidence <n>", "Confidence score 0-1", "0.5")
     .option("--json", "Output as JSON")
     .option("--pod-url <url>", "Pod URL override")
@@ -1573,7 +1709,7 @@ agents
     .option("--role <role>", "Workspace role: admin | editor | viewer (default: editor)")
     .option("--workspace <id>", "Focus on one workspace (default: pod-wide)")
     .option("--project <id>", "Focus on one project (composable with --workspace)")
-    .option("--with-mcp", "Raycast only: also install the full MCP server via mcp-remote")
+    .addOption(new Option("--with-mcp", "deprecated, ignored: Raycast always gets the pod's MCP server").hideHelp())
     .option("--api-key <key>", "Register a key you already hold, on this machine only (mints nothing)")
     .option("--label <label>", "Human-readable description")
     .action(async (kind, opts) => {
@@ -2092,12 +2228,12 @@ Examples:
 // ─── artifact ─────────────────────────────────────────────────────────────────
 const artifact = program
     .command("artifact")
-    .description("Create and manage HTML artifacts as Synap documents");
+    .description("Create HTML artifacts as Synap cells: an HTML/JS page that opens in the desktop app and can read pod data");
 artifact
     .command("create")
-    .description("Create an HTML artifact from a local file")
+    .description("Define a cell from a local HTML file (governed: an agent key files a proposal)")
     .requiredOption("--html <file>", "HTML file to upload")
-    .option("--name <name>", "Document title (default: filename)")
+    .option("--name <name>", "Cell name (default: filename)")
     .option("--workspace <id>", "Workspace context")
     .option("--open", "Open in the Synap desktop app after creation")
     .option("--json", "JSON output")
@@ -2665,14 +2801,15 @@ sync
     await capabilitySyncStatus(provider, opts);
 });
 // ─── raycast (hidden power-user escape) ───────────────────────────────────────
-// Prefer the native Synap Raycast extension (@synap). Capability verbs there go
-// through list-actions / run-action. Script Commands are a per-verb escape hatch.
+// Prefer Raycast AI on the pod's MCP server (`synap connect raycast`), where
+// capability verbs run through synap_run_capability. Script Commands are a
+// per-verb escape hatch.
 const raycast = program
     .command("raycast", { hidden: true })
     .description("(hidden) Power-user escape: generate Raycast Script Commands per capability verb");
 raycast
     .command("generate")
-    .description("Power-user escape: emit a Script Command per enabled verb (extension uses list-actions/run-action)")
+    .description("Power-user escape: emit a Script Command per enabled verb (Raycast AI uses the pod's MCP server)")
     .option("--out <dir>", "Output directory (default: ~/.synap/raycast-commands)")
     .option("--workspace <id>", "Workspace context")
     .action(async (opts) => {