shadok-ai 0.8.7 → 0.8.8

package/context/agents-skill/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: shadok-ai-agents
+description: Create and drive isolated Claude Code agents through the shadok-ai server (git worktrees, prompts, dialogs, diff). Use when the user wants to delegate a task to a shadok-ai agent, launch agents in parallel, or inspect/drive existing shadok-ai sessions.
+---
+
+# Driving shadok-ai agents
+
+Every operation goes through the thin client shipped with this skill:
+
+```bash
+node ~/.claude/skills/shadok-ai-agents/pilotctl.mjs <command> …
+```
+
+Each command prints ONE JSON object on stdout (exit 1 + `{error}` on failure)
+and automatically starts the shadok-ai server when it is not running (port
+3789, or `$SHADOK_PORT`). Sessions stay visible in the web UI
+(http://localhost:3789) — the user can follow along and step in.
+
+## Commands
+
+| Command | Effect |
+|---|---|
+| `spawn [--cwd DIR] [--worktree] [--profile NAME] [--resume ID] [--continue]` | creates an agent → `{sessionId, cwd, branch}`. `--worktree` isolates the agent in a git worktree (`~/.shadok-ai/worktrees/`, branch `shadok-ai/<tag>`). `--profile` gives it a role + its guardrails + its secrets (see below) |
+| `prompt <id> "text" [--timeout s]` | sends a prompt, waits for the end of the turn → `{status:"answer", text, tools}` or `{status:"dialog", question, options, multi}` or `{status:"timeout", screen}` or `{status:"pace-blocked", reason}` |
+| `dialog <id>` | queries the state → `{status:"idle"}` or the pending dialog |
+| `choose <id> <n>` | single-select dialog: picks and commits option n |
+| `toggle <id> <n>` then `confirm <id>` | multi-select dialog: check/uncheck then submit |
+| `freetext <id> <n> "text"` | the "Type something" option: a free answer |
+| `list [--cwd DIR]` | driven agents (local state + alive/dead) and resumable sessions |
+| `diff <id>` | the agent's changes (git status + diff against the worktree's base) |
+| `stop <id>` | ends the session (for ALL its clients) |
+| `screen <id>` | raw TUI screen (debug) |
+| `profile-prompt "<text>" [--name NAME] [--readonly]` | rewrites a profile's **system prompt**: your own by default; any of them (and creation with `--name`) under the lead profile |
+
+## Choosing a profile (`--profile`)
+
+A profile is a role applied at startup: system prompt, native permission
+guardrails (e.g. git writes blocked), injected secrets, an optional model.
+**Without `--profile` the agent starts as bare Claude** — no role, no guardrail,
+no secrets.
+
+The shipped profiles: `Shadok-Boss` (reads everything, delegates, read-only),
+`Shadok-dev` (code, full access), `Shadok-Marketing` and `Shadok-Support`
+(read-only). `pilotctl.mjs list` does not enumerate them — the list lives in the
+UI's Profiles panel, or behind `GET /profiles`.
+
+The profile is only applied to **new** sessions: with `--resume` or
+`--continue`, the session keeps the one it already had.
+
+## Growing your own role (`profile-prompt`)
+
+You can rewrite your profile's **system prompt** — to record what you learned
+about this repo, a convention nobody should rediscover, a trap to avoid. Under
+the lead profile you can rewrite any prompt and **mint** a role (`--name`, plus
+`--readonly` so it is born with git writes blocked).
+
+What you **cannot** touch: `deny`, `allow`, `secrets`, `model`. Those are the
+guardrails, they belong to the human and are edited from the web UI — a
+read-only agent must not be able to grant itself git writes, nor a minted role
+hand itself the vault's secrets. These fields are ignored here, not merely
+refused.
+
+Authorisation rests on `$SHADOK_SESSION_KEY`, injected into your env at startup
+— the session id would not do, `/live` publishes it.
+
+The prompt is passed to `claude` **at spawn**: a change takes effect at the
+agent's next restart, not mid-session.
+
+```bash
+node ~/.claude/skills/shadok-ai-agents/pilotctl.mjs profile-prompt "$(cat <<'TXT'
+… the complete new prompt …
+TXT
+)"
+```
+
+Write the **whole** prompt: it replaces the old one, it does not add to it.
+
+## Typical flow: delegating a task to an agent
+
+1. `spawn --worktree --profile <role> --cwd <repo>` → note `sessionId` and `branch`;
+2. `prompt <id> "<task>"` — launch it through Bash with **run_in_background**
+   (a turn can take several minutes) and read the JSON at the end;
+3. if `status:"dialog"`: answer with `choose` (single) or `toggle`+`confirm`
+   (multi) or `freetext`, which in turn return `answer` or a new `dialog`;
+4. if `status:"timeout"`: the turn CONTINUES server-side — do not resend the
+   prompt; check back later with `dialog <id>`;
+4bis. if `status:"pace-blocked"`: NOTHING was sent — usage is above the quota's
+   ideal pace (`reason` spells it out). Do not insist in a loop; tell the user;
+5. task finished: `diff <id>` and present the changes to the user. The
+   `shadok-ai/<tag>` branch and its worktree are NEVER merged or deleted
+   automatically — the user is the one who merges.
+
+Parallel agents: repeat `spawn` (one id per agent), and launch the `prompt`
+calls in the background simultaneously.
+
+## You get told: your agents report back
+
+An agent you spawn is registered as your **child**, automatically — nothing to
+pass. You then receive a message when it:
+
+- **finishes its turn** (with its own summary and a pointer to its `diff`);
+- **blocks on a question** (the question, its options, and how to answer);
+- **dies or times out** — otherwise you would wait forever for an agent that is
+  already gone.
+
+These messages arrive prefixed `🤖 [agent]`. You are told about **your** children
+and about no other channel.
+
+Practical consequence: **do not loop to watch an agent any more.** Launch the
+`prompt` in the background and move on — repeated polling costs a turn every
+time, and the information comes to you.
+
+`--parent none` spawns an agent deliberately unattached; `--parent <id>`
+attaches it elsewhere.
+
+## Guardrails
+
+- NEVER `stop` a session this conversation did not create: it may belong to the
+  user in the web UI. `stop` ends the session for all its clients.
+- Every agent consumes the Claude quota like an ordinary session. Do not
+  multiply agents without an explicit request from the user.
+- `prompt` on a session whose turn is already running → the error "a response is
+  already in progress": wait with `dialog <id>`.
+- If an agent seems stuck in a state the dialogs do not cover, look at
+  `screen <id>` (the equivalent of the UI's "engine room").
+- To resume an existing session (`spawn --resume <id>`), always pass `--cwd`
+  with the session's directory (the server would otherwise fall back to its own
+  cwd); for an agent already being driven, the local state supplies that cwd
+  automatically.
+
+## Mechanics (for debugging)
+
+The server kills the claude process when its last WS client detaches; so
+`pilotctl` keeps a small detached "holder" process per agent (the internal
+`hold` command), restarted as needed by every command. Local state:
+`~/.shadok-ai/pilotctl/<id>.json` (cwd, branch, baseSha, holderPid). Log of the
+auto-started server: `~/.shadok-ai/pilotctl/server.log`.

package/context/agents-skill/pilotctl.mjs

@@ -0,0 +1,502 @@
+#!/usr/bin/env node
+// pilotctl — thin client for the shadok-ai web server. One-shot commands,
+// JSON on stdout. See ./SKILL.md.
+import { execFileSync, spawn as spawnChild } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import WebSocket from "ws";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// Only used to auto-start a server when none is reachable (a dev running pilotctl
+// inside the repo). When this skill is seeded into ~/.claude/skills so ANY agent
+// can pilot, REPO_ROOT is meaningless — ensureServer guards on it below.
+export const REPO_ROOT = path.resolve(__dirname, "..", "..", "..");
+
+export const port = () => Number(process.env.SHADOK_PORT ?? 3789);
+export const httpBase = () => `http://localhost:${port()}`;
+export const wsUrl = () => `ws://localhost:${port()}/ws`;
+// When a GUI password is set, the server injects SHADOK_AUTH=sk_auth=<token>
+// into every agent's env; loopback HTTP + WS calls must present it as the cookie
+// or the password gate 401s them — exactly what secret.py / schedule.py and the
+// Telegram bridge already do. Empty when no password is set → no change.
+export const authHeaders = () => (process.env.SHADOK_AUTH ? { cookie: process.env.SHADOK_AUTH } : {});
+export const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+export function stateDir() {
+  return process.env.SHADOK_STATE_DIR ?? path.join(os.homedir(), ".shadok-ai", "pilotctl");
+}
+
+export function readState(id) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(stateDir(), id + ".json"), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export function writeState(id, obj) {
+  fs.mkdirSync(stateDir(), { recursive: true });
+  fs.writeFileSync(path.join(stateDir(), id + ".json"), JSON.stringify(obj, null, 2));
+}
+
+export function deleteState(id) {
+  fs.rmSync(path.join(stateDir(), id + ".json"), { force: true });
+}
+
+export function pidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function parseArgs(argv) {
+  const [cmd, ...rest] = argv;
+  const flags = {};
+  const pos = [];
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === "--worktree" || a === "--continue" || a === "--readonly") flags[a.slice(2)] = true;
+    else if (a === "--cwd" || a === "--resume" || a === "--timeout" || a === "--profile" || a === "--parent") flags[a.slice(2)] = rest[++i];
+    else pos.push(a);
+  }
+  return { cmd, pos, flags };
+}
+
+function connect() {
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(wsUrl(), { headers: authHeaders() });
+    ws.once("open", () => resolve(ws));
+    ws.once("error", reject);
+  });
+}
+
+// Attaches to (or starts) a session; resolves once the server says `ready`.
+export async function openSession(startMsg) {
+  const ws = await connect();
+  const listeners = new Set();
+  const state = { lastScreen: "", busy: false, ready: null };
+  ws.on("message", (raw) => {
+    let msg;
+    try {
+      msg = JSON.parse(String(raw));
+    } catch {
+      return;
+    }
+    if (msg.type === "screen") state.lastScreen = msg.text;
+    if (msg.type === "working") state.busy = true;
+    if (msg.type === "turn-done" || msg.type === "dialog") state.busy = false;
+    for (const l of [...listeners]) l(msg);
+  });
+  ws.on("close", () => {
+    for (const l of [...listeners]) l({ type: "socket-closed" });
+  });
+  const client = {
+    ws,
+    state,
+    send: (m) => ws.send(JSON.stringify(m)),
+    on: (l) => listeners.add(l),
+    off: (l) => listeners.delete(l),
+    waitFor: (types, timeoutMs) =>
+      new Promise((resolve) => {
+        const timer = timeoutMs
+          ? setTimeout(() => {
+              listeners.delete(l);
+              resolve({ type: "timeout" });
+            }, timeoutMs)
+          : null;
+        const l = (msg) => {
+          if (!types.includes(msg.type)) return;
+          if (timer) clearTimeout(timer);
+          listeners.delete(l);
+          resolve(msg);
+        };
+        listeners.add(l);
+      }),
+  };
+  client.send({ type: "start", ...startMsg });
+  const ready = await client.waitFor(["ready", "error"], 90_000);
+  if (ready.type !== "ready") {
+    ws.close();
+    throw new Error(ready.message ?? "timeout waiting for ready");
+  }
+  state.ready = ready;
+  return client;
+}
+
+// Accumulates streamed content until the turn ends (or a dialog suspends it).
+export async function collectTurn(client, timeoutMs) {
+  const texts = [];
+  const tools = [];
+  const collector = (msg) => {
+    if (msg.type === "stream-text") texts.push(msg.text);
+    else if (msg.type === "stream-tool") tools.push({ name: msg.name, summary: msg.summary });
+  };
+  client.on(collector);
+  const end = await client.waitFor(
+    // "pace-blocked" is a refusal, not a turn: the server sent nothing to the
+    // TUI, so no turn-done will ever follow. Without it here the call would sit
+    // out the whole timeout and report an indistinguishable {status:"timeout"}.
+    ["dialog", "turn-done", "exited", "stopped", "error", "pace-blocked", "socket-closed"],
+    timeoutMs,
+  );
+  client.off(collector);
+  const text = texts.join("\n\n");
+  if (end.type === "turn-done") return { status: "answer", text, tools };
+  if (end.type === "dialog")
+    return { status: "dialog", question: end.question, options: end.options, multi: end.multi, text };
+  if (end.type === "pace-blocked")
+    return { status: "pace-blocked", reason: end.reason ?? null, text };
+  if (end.type === "timeout") return { status: "timeout", screen: client.state.lastScreen, text };
+  if (end.type === "error") return { status: "error", error: end.message };
+  return { status: "exited", code: end.code ?? null, text };
+}
+
+async function serverUp() {
+  try {
+    const r = await fetch(`${httpBase()}/sessions?cwd=${encodeURIComponent(os.homedir())}`, {
+      signal: AbortSignal.timeout(1500),
+      headers: authHeaders(),
+    });
+    return r.ok;
+  } catch {
+    return false;
+  }
+}
+
+export async function ensureServer() {
+  if (await serverUp()) return;
+  if (process.env.SHADOK_NO_AUTOSTART)
+    throw new Error(`shadok-ai server unreachable on :${port()}`);
+  // Auto-start only works from a real repo checkout. Globally seeded, REPO_ROOT
+  // is not a repo — but a piloted agent always has a running server, so this
+  // path is only a standalone dev's. Fail clearly rather than `npm build`-ing $HOME.
+  const dist = path.join(REPO_ROOT, "dist", "server.js");
+  if (!fs.existsSync(dist)) {
+    if (!fs.existsSync(path.join(REPO_ROOT, "package.json")))
+      throw new Error(`shadok-ai server unreachable on :${port()} (and no repo to auto-start one — start the server first)`);
+    execFileSync("npm", ["run", "build"], { cwd: REPO_ROOT, stdio: "ignore" });
+  }
+  fs.mkdirSync(stateDir(), { recursive: true });
+  const logPath = path.join(stateDir(), "server.log");
+  const log = fs.openSync(logPath, "a");
+  const child = spawnChild(process.execPath, [dist], {
+    cwd: REPO_ROOT,
+    detached: true,
+    stdio: ["ignore", log, log],
+    env: { ...process.env, PORT: String(port()) },
+  });
+  child.unref();
+  const deadline = Date.now() + 15_000;
+  while (Date.now() < deadline) {
+    if (await serverUp()) return;
+    await sleep(300);
+  }
+  throw new Error(`shadok-ai server did not come up on :${port()} (log: ${logPath})`);
+}
+
+// The server kills the claude process when its last WS client detaches, so a
+// detached "hold" process keeps one attachment open per piloted agent.
+export async function ensureHolder(id, cwd) {
+  if (process.env.SHADOK_NO_HOLDER) return;
+  const st = readState(id);
+  if (st?.holderPid && pidAlive(st.holderPid)) return;
+  const self = fileURLToPath(import.meta.url);
+  const args = [self, "hold", id];
+  if (cwd) args.push(cwd);
+  const child = spawnChild(process.execPath, args, {
+    detached: true,
+    stdio: ["ignore", "pipe", "ignore"],
+    env: process.env,
+  });
+  try {
+    await new Promise((resolve, reject) => {
+      const t = setTimeout(() => reject(new Error("holder failed to attach within 90s")), 90_000);
+      child.stdout.on("data", (d) => {
+        if (String(d).includes("attached")) {
+          clearTimeout(t);
+          resolve();
+        }
+      });
+      child.once("exit", () => {
+        clearTimeout(t);
+        reject(new Error("holder exited before attaching"));
+      });
+    });
+  } finally {
+    child.unref();
+  }
+  writeState(id, { ...(readState(id) ?? { sessionId: id }), cwd: cwd ?? null, holderPid: child.pid });
+}
+
+/**
+ * The `start` payload for a spawn. Pure, so the parent-linking rule is testable
+ * without a server.
+ *
+ * `SHADOK_SESSION_ID` is set by the server on every piloted session, so an agent
+ * that spawns another is identified with no extra plumbing and nothing to
+ * configure — and it is then the only channel told when that child finishes,
+ * blocks or dies. A human shell has no such variable and therefore creates a
+ * root.
+ */
+export function buildStartMsg(flags, env = process.env) {
+  const startMsg = {};
+  if (flags.cwd) startMsg.cwd = flags.cwd;
+  if (flags.worktree) startMsg.worktree = true;
+  if (flags.resume) startMsg.resume = flags.resume;
+  if (flags.continue) startMsg.continue = true;
+  // With no profile the delegated agent starts as bare Claude: no role, no
+  // guardrail, no secrets. The server only applies it to new sessions (not on a
+  // resume).
+  if (flags.profile) startMsg.profile = flags.profile;
+  // "none" is the escape hatch: spawn something deliberately unlinked.
+  if (flags.parent === "none") startMsg.parent = null;
+  else if (flags.parent) startMsg.parent = flags.parent;
+  else if (env.SHADOK_SESSION_ID) startMsg.parent = env.SHADOK_SESSION_ID;
+  return startMsg;
+}
+
+async function cmdSpawn(flags) {
+  await ensureServer();
+  const startMsg = buildStartMsg(flags);
+  const client = await openSession(startMsg);
+  const { sessionId, cwd, branch } = client.state.ready;
+  let baseSha = null;
+  if (branch) {
+    try {
+      baseSha = execFileSync("git", ["-C", cwd, "rev-parse", "HEAD"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    } catch {}
+  }
+  const prev = readState(sessionId) ?? {};
+  writeState(sessionId, {
+    ...prev,
+    sessionId,
+    cwd,
+    branch: branch ?? prev.branch ?? null,
+    baseSha: baseSha ?? prev.baseSha ?? null,
+    holderPid: prev.holderPid ?? null,
+  });
+  await ensureHolder(sessionId, cwd);
+  client.ws.close();
+  return { sessionId, cwd, branch: branch ?? null };
+}
+
+// Internal command: stays attached until the session ends.
+async function cmdHold(id, cwd) {
+  await openSession({ resume: id, cwd }).then((client) => {
+    process.stdout.write("attached\n");
+    client.on((msg) => {
+      if (msg.type === "stopped") deleteState(id);
+      if (["stopped", "exited", "socket-closed"].includes(msg.type)) process.exit(0);
+    });
+  });
+  return new Promise(() => {}); // never resolves; the WS keeps the loop alive
+}
+
+// Attaches to a piloted session and sends one protocol message, then waits
+// for the outcome of the turn (answer, dialog, timeout…).
+async function cmdTurn(id, msg, flags) {
+  await ensureServer();
+  const st = readState(id);
+  const cwd = flags.cwd ?? st?.cwd ?? undefined;
+  await ensureHolder(id, cwd);
+  const client = await openSession({ resume: id, cwd });
+  client.send(msg);
+  const result = await collectTurn(client, Number(flags.timeout ?? 600) * 1000);
+  client.ws.close();
+  if (result.status === "error") throw new Error(result.error);
+  return { ...result, sessionId: id };
+}
+
+async function cmdDialog(id, flags) {
+  // `settle` is silently ignored server-side while a turn is in flight, and
+  // triggers a dialog/turn-done broadcast when idle — safe to always send.
+  const r = await cmdTurn(id, { type: "settle" }, flags);
+  if (r.status === "answer") return { status: "idle", sessionId: id, text: r.text };
+  return r;
+}
+
+async function cmdList(flags) {
+  await ensureServer();
+  const cwd = flags.cwd ?? process.cwd();
+  const r = await fetch(`${httpBase()}/sessions?cwd=${encodeURIComponent(cwd)}`, { headers: authHeaders() });
+  const resumable = await r.json();
+  const dir = stateDir();
+  const agents = !fs.existsSync(dir)
+    ? []
+    : fs
+        .readdirSync(dir)
+        .filter((f) => f.endsWith(".json"))
+        .map((f) => JSON.parse(fs.readFileSync(path.join(dir, f), "utf8")))
+        .map((s) => ({ ...s, live: !!(s.holderPid && pidAlive(s.holderPid)) }));
+  return { agents, resumable };
+}
+
+async function cmdDiff(id) {
+  await ensureServer();
+  const r = await fetch(`${httpBase()}/diff?session=${encodeURIComponent(id)}`, { headers: authHeaders() });
+  const body = await r.json();
+  if (!body.error) return body;
+  // Session no longer live server-side: diff the worktree locally against
+  // the baseSha recorded at spawn time.
+  const st = readState(id);
+  if (!st?.cwd) throw new Error(`no live session and no local state for ${id}`);
+  const git = (args) =>
+    execFileSync("git", ["-C", st.cwd, ...args], { encoding: "utf8" }).trimEnd();
+  let diff = git(["diff", st.baseSha ?? "HEAD"]);
+  // Include untracked files (diff doesn't show them) — mirrors gitDiff in src/worktree.ts.
+  const untracked = git(["ls-files", "--others", "--exclude-standard"])
+    .split("\n")
+    .filter(Boolean);
+  if (untracked.length) {
+    const shown = untracked.map((f) => {
+      try {
+        return git(["diff", "--no-index", "/dev/null", f]);
+      } catch (e) {
+        // --no-index exits non-zero when files differ; its stdout has the diff.
+        return e?.stdout ? String(e.stdout).trimEnd() : `+++ ${f} (untracked)`;
+      }
+    });
+    diff = [diff, ...shown].filter(Boolean).join("\n");
+  }
+  return {
+    status: git(["status", "--short"]),
+    diff,
+    branch: st.branch ?? null,
+    fallback: true,
+  };
+}
+
+async function cmdStop(id) {
+  await ensureServer();
+  const st = readState(id);
+  const holderLive = !!(st?.holderPid && pidAlive(st.holderPid));
+  if (!holderLive) {
+    // No holder → we never kept this session alive; don't resurrect it just
+    // to stop it (it may belong to a browser client). Clear local state only.
+    deleteState(id);
+    return { stopped: false, sessionId: id, note: "no live holder; local state cleared" };
+  }
+  let client;
+  try {
+    client = await openSession({ resume: id, cwd: st?.cwd ?? undefined });
+  } catch (err) {
+    // Holder pid is alive but session is dead (zombie holder, dead server session).
+    // Kill the holder and clean up state.
+    if (st.holderPid !== process.pid && pidAlive(st.holderPid)) {
+      try {
+        process.kill(st.holderPid);
+      } catch {}
+    }
+    deleteState(id);
+    const msg = err instanceof Error ? err.message : String(err);
+    return { stopped: false, sessionId: id, note: `session not reattachable (${msg}); holder killed and local state cleared` };
+  }
+  client.send({ type: "stop" });
+  const result = await client.waitFor(["stopped", "socket-closed"], 30_000);
+  client.ws.close();
+  if (result.type === "timeout") {
+    // Stop was not confirmed within 30s; don't kill holder or delete state (leave for retry).
+    return { stopped: false, sessionId: id, note: "stop not confirmed within 30s; session may still be running" };
+  }
+  if (st.holderPid !== process.pid && pidAlive(st.holderPid)) {
+    try {
+      process.kill(st.holderPid);
+    } catch {}
+  }
+  deleteState(id);
+  return { stopped: true, sessionId: id };
+}
+
+/**
+ * Rewrite a profile's SYSTEM PROMPT — your own by default, any one if you run
+ * under the lead profile (which may also mint a new role with --name/--readonly).
+ *
+ * Guardrails (deny/allow/secrets/model) are NOT touchable here by design: they
+ * are the human's, edited from the web UI. Authorization is SHADOK_SESSION_KEY,
+ * injected into your env at spawn — the session id would not do, it is public.
+ *
+ * The prompt is passed to claude at spawn, so a change lands at the agent's
+ * next restart, not mid-session.
+ */
+async function cmdProfilePrompt(text, flags) {
+  const key = process.env.SHADOK_SESSION_KEY;
+  if (!key) throw new Error("no SHADOK_SESSION_KEY in env — not running as a piloted agent");
+  if (!text || !text.trim()) throw new Error("a system prompt is required");
+  const body = { key, systemPrompt: text };
+  if (flags.name) body.name = flags.name;
+  if (flags.readonly) body.readOnly = true;
+  const r = await fetch(`${httpBase()}/profiles/prompt`, {
+    method: "PUT",
+    headers: { "Content-Type": "application/json", ...authHeaders() },
+    body: JSON.stringify(body),
+  });
+  const out = await r.json();
+  if (!r.ok) throw new Error(out.error ?? `HTTP ${r.status}`);
+  return out;
+}
+
+async function cmdScreen(id, flags) {
+  await ensureServer();
+  const st = readState(id);
+  const cwd = flags.cwd ?? st?.cwd ?? undefined;
+  await ensureHolder(id, cwd);
+  const client = await openSession({ resume: id, cwd });
+  if (!client.state.lastScreen) await client.waitFor(["screen"], 5000);
+  client.ws.close();
+  return { sessionId: id, screen: client.state.lastScreen };
+}
+
+const HELP =
+  "usage: pilotctl <spawn|prompt|dialog|choose|toggle|confirm|freetext|list|diff|stop|screen|profile-prompt> …";
+
+export async function run(argv) {
+  const { cmd, pos, flags } = parseArgs(argv);
+  switch (cmd) {
+    case "spawn":
+      return cmdSpawn(flags);
+    case "hold":
+      return cmdHold(pos[0], pos[1]);
+    case "prompt":
+      return cmdTurn(pos[0], { type: "prompt", text: pos[1] }, flags);
+    case "dialog":
+      return cmdDialog(pos[0], flags);
+    case "choose":
+      return cmdTurn(pos[0], { type: "choose", n: Number(pos[1]) }, flags);
+    case "toggle":
+      return cmdTurn(pos[0], { type: "toggle", n: Number(pos[1]) }, flags);
+    case "confirm":
+      return cmdTurn(pos[0], { type: "confirm" }, flags);
+    case "freetext":
+      return cmdTurn(pos[0], { type: "freetext", n: Number(pos[1]), text: pos[2] }, flags);
+    case "list":
+      return cmdList(flags);
+    case "diff":
+      return cmdDiff(pos[0]);
+    case "stop":
+      return cmdStop(pos[0]);
+    case "screen":
+      return cmdScreen(pos[0], flags);
+    case "profile-prompt":
+      return cmdProfilePrompt(pos[0], flags);
+    default:
+      throw new Error(HELP);
+  }
+}
+
+// CLI entry point — not triggered when imported by tests.
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  run(process.argv.slice(2))
+    .then((r) => {
+      console.log(JSON.stringify(r));
+      process.exit(r?.error || r?.status === "error" ? 1 : 0);
+    })
+    .catch((e) => {
+      console.log(JSON.stringify({ error: e instanceof Error ? e.message : String(e) }));
+      process.exit(1);
+    });
+}