commandmate 0.49.3 → 0.50.0

package/dist/cli/docs/agent-operations.d.ts

@@ -5,7 +5,7 @@
  * This content is embedded as a string constant so that it's available
  * even when installed via `npm install -g commandmate` (where docs/ is not included).
  */
-export declare const AGENT_OPERATIONS_GUIDE = "# CLI Agent Operations Guide\n\nOperate agent sessions from the CommandMate CLI.\nThese commands enable coding agents (Claude Code, Codex, etc.) to orchestrate other agents in parallel.\n\n## Prerequisites\n\n- CommandMate server must be running: commandmate start --daemon\n- Target worktrees must be registered (visible in browser UI sidebar)\n- Connection target is resolved as: exported CM_PORT > ~/.commandmate/.env CM_PORT > 3000\n  (CM_BIND and the CM_HTTPS_CERT + CM_HTTPS_KEY pair are honoured the same way)\n- Use CM_AUTH_TOKEN env var for authenticated servers\n\n## Commands\n\n### commandmate ls\n  List worktrees with status.\n\n  commandmate ls                          # Table format (ID, NAME, STATUS, REASON, DEFAULT, AUTO_YES)\n  commandmate ls --json                   # JSON output (for agent consumption)\n  commandmate ls --quiet                  # IDs only, one per line (for piping)\n  commandmate ls --branch <prefix>        # Filter by branch name prefix\n  commandmate ls --id <prefix>            # Filter by worktree id prefix\n\n  Worktree ids are <repo>-<branch> slugs (e.g. anvil-develop). --id / --branch\n  front-match is case-sensitive and does NOT guarantee uniqueness (e.g.\n  --id anvil-develop also matches anvil-develop-2). --branch and --id combine\n  as AND. Use --id to disambiguate the same branch across repositories.\n\n  STATUS values:\n    idle     - Session not started\n    ready    - Session running, waiting for input (task completed)\n    running  - Agent executing a task\n    waiting  - Confirmation prompt active (Yes/No, etc.)\n\n  REASON values (Issue #1926):\n    The evidence behind the STATUS beside it. '<reason> (no evidence)' marks a\n    frame the detection layer could not classify, so the STATUS is a fallback\n    rather than a reading. '-' means the server gives no reason: it predates\n    #1926, the session is not running, or the tool has two or more instances and\n    the per-tool aggregate dropped it. 'commandmate ls --json' keeps the\n    per-tool rows under sessionStatusByCli.<tool>.\n\n  AUTO_YES values (Issue #2575):\n    Time left on the instance that will lose Auto-Yes FIRST, among the instances\n    that explain this row's STATUS (waiting: the ones waiting; running: the ones\n    processing; ready: the ones running; idle: the ones that exited -- a bare\n    idle row falls back to every armed instance).\n\n    MM:SS    - time left, under an hour (e.g. 42:10)\n    H:MM:SS  - time left, an hour or more (e.g. 1:05:33)\n    on       - armed, with no expiry the server named\n    off      - at least one of those instances is NOT armed, so a prompt on this\n               row waits for a human. 'waiting' + 'off' is a confirmation\n               prompt nobody is going to answer -- the cell to look for\n    blocked  - armed, but the contract running on that instance sets\n               autoYes.mode: off, so nothing is answered there either\n               (Issue #3723; --json: autoYesByInstance.<id>.blockedByContract)\n    off(restart) - off, because the server restarted while the grant was live\n               (Issue #3730; --json: autoYesStopReasonByInstance.<id>)\n    -        - not known: the server predates #2512, or this row is not idle and\n               no instance explains its STATUS\n\n    A trailing ' (<instanceId>)' names the instance the cell is about, printed\n    when that is not the default agent's primary. Pass it to capture / send /\n    respond as --instance verbatim.\n\n    Time left is a fact about Auto-Yes, not a promise that the prompt gets\n    answered: a contract autoYes policy can withhold the answer, and a free-text\n    prompt has none to give. 'commandmate capture <id> --json --instance <id>'\n    carries autoYes.lastSuppression and autoYes.stopReason; 'commandmate wait'\n    returns exit 10 for a prompt no agent is going to clear.\n\n    Nothing here is derived in --json: it carries sessionStatusByInstance and\n    autoYesByInstance raw, which is where the per-instance breakdown is.\n\n### commandmate sync\n  Ask the server to re-scan repositories and sync worktrees to its database\n  (same endpoint as the GUI sync button). Run it after 'git worktree add' so the\n  new worktree appears in 'commandmate ls' without opening the GUI (Issue #1680).\n\n  commandmate sync                        # Prints the server's summary message\n  commandmate sync --json                 # Full API response (worktreeCount,\n                                          # repositoryCount, repositories,\n                                          # deletedCount, cleanupWarnings)\n\n### commandmate send <worktree-id> \"<message>\"\n  Send a message to an agent (async). Starts session automatically if not running.\n\n  Options:\n    --instance <id>        Agent instance ID: <agent> or <agent>-<n> (e.g. claude-2, or codex\n                           for the codex primary instance). The recommended way to name a\n                           target: send / wait / respond / capture / auto-yes all take it.\n    --agent <id>           Ad-hoc CLI tool for an instance the roster does not know:\n                           claude (default), codex, gemini, vibe-local, opencode, copilot, antigravity\n    --register             Register the --instance session into the agent-instance roster\n    --auto-yes             Enable auto-yes before sending (session-wide, no policy\n                           guard -- for unattended runs prefer --contract with an\n                           autoYes policy: mode / denyPatterns)\n    --auto-yes-answer-mode <m>\n                           With --auto-yes: recommended (questions answered with the\n                           recommended option, else the default) or careful\n                           (questions left to you). See auto-yes below\n    --duration <d>         Auto-yes duration: 1h-24h, whole hours, e.g. 1h, 3h, 8h\n                           (default: 1h)\n    --stop-pattern <p>     Auto-yes stop condition (regex; matches terminal output,\n                           cannot block commands -- see auto-yes below)\n    --ignore-structured-prompt\n                           Send even if only the agent's hooks report an open dialog.\n                           For a session whose pane looks idle but keeps refusing;\n                           a dialog visible in the terminal is still refused.\n    --reply-to <target>    Deliver the target session's reply into <target>'s composer\n                           when the turn ends: <worktree-id>[@<instance-id|alias>], or\n                           'self' for the session running the command. Nothing blocks --\n                           there is no wait to run and no pane to scrape.\n    --allow-relay-chain    Permit --reply-to while answering a message that itself\n                           arrived over a relay. Refused by default (exit 2); chains\n                           still stop at 3 hops.\n\n  Refused while the agent is waiting on a prompt (exit 2). Keystrokes sent to\n  an open dialog never reach the agent -- they pile up in the dialog's own\n  input line, and the next respond then carries that text along as a message\n  instead of an answer. Nudging a stalled worker is how this gets worse.\n  Answer first: commandmate respond <id> <answer>. respond, special keys and\n  prompt-response are never refused -- they are the way out. Timer-fired sends\n  ARE refused (same service layer) and record [prompt_waiting] as their reason.\n  It fails open if the pane cannot be read, so treat it as a narrowing, not a\n  guarantee.\n\n  Two layers can report the dialog: the terminal scraper, and the agent's own\n  hooks. Either one is enough to refuse -- the dialog the scraper cannot read is\n  exactly the one that caused this. A frame neither layer classifies is still\n  wait's \"unclassified\" case instead.\n\n  A hook-reported dialog is released by the agent's next event, and hooks are\n  fail-open, so the record can outlive its dialog. It therefore stops blocking\n  sends 5 minutes after it was reported -- and immediately with\n  --ignore-structured-prompt, or CM_STRUCTURED_SEND_GUARD=off for the server.\n  A session nobody can send to is worse than a missed guard. Both bypasses are\n  narrow: a prompt on screen is still refused, and the payload still reports it\n  (wait and the UI do not go quiet).\n\n  Message length: up to 48 KiB and 240 lines arrives whole on claude, codex,\n  command-code and antigravity (verified, Issue #2464). Over 512 bytes the\n  message is pasted as one bracketed paste and Enter waits until the agent's\n  composer shows all of it; if it never does, nothing is submitted and send\n  exits 99 (\"Message body did not arrive intact\"). Put a longer brief in a\n  file and send a message that names it ('commandmate docs --section delegation').\n\n  Finding worktree IDs:\n    WT=$(commandmate ls --branch feature/101 --quiet)\n    WT=$(commandmate ls --id anvil- --quiet)   # disambiguate by repo (id prefix)\n    commandmate send \"$WT\" \"Implement this\"\n\n  Targeting a non-default agent (Issue #1638): pass --instance, not --agent. Only\n  --instance is accepted by every command -- 'wait --agent' does not exist -- so a\n  workflow that names the agent on 'send' and nothing on 'wait' waits on the wrong\n  session in silence.\n    commandmate send \"$WT\" \"Implement this\" --instance codex\n    commandmate wait \"$WT\" --instance codex\n\n  Delegating without blocking (--reply-to):\n    commandmate send \"$WT\" \"Implement this\" --instance codex --reply-to self\n    # ... keep working. When codex finishes, its answer arrives in your composer as\n    # [from Codex 2 / <worktree>] <reply>, saved in History as a 'relay' message.\n    commandmate relays                       # what is still outstanding\n\n  The relay is refused (exit 2, nothing sent) when the message you are answering\n  arrived over a relay itself (pass --allow-relay-chain), when the chain would\n  exceed 3 hops, or when an open relay between the two sessions already exists.\n  If the target stops on a confirmation you are told, once, and the relay stays\n  open -- answer the dialog on that session and the reply still arrives. A relay\n  nobody could deliver expires after 24h with a single line of notice.\n  The relay is tied to this send (Issue #3957): only a turn that ends after the\n  message started going in is delivered, and a reply that may share a turn with\n  another request carries one '[CommandMate relay] ... (overlap=...)' line under\n  the header. When the send's outcome is unknown the relay is left open, nothing\n  is resent, and 'commandmate relays --id <relay-id>' shows why it is held.\n\n### commandmate relays\n  List the standing delegations this session is waiting on and owes.\n\n    commandmate relays                      # the session running the command\n    commandmate relays --worktree <id> --instance codex-2\n    commandmate relays --json               # owed / awaiting / open / counts\n    commandmate relays --id <relay-id>      # one relay, closed too: send= overlap= hold=\n    commandmate relays cancel <relay-id>    # withdraw one; nothing is delivered\n\n  States: pending (the worker has not finished), prompt (it stopped on a\n  confirmation and the requester was told; still open), delivered, expired,\n  cancelled.\n\n  'relays cancel' cannot withdraw a relay that is being delivered right now\n  (a reply or a prompt notice): the server answers 409 and the command exits\n  2. The delivery usually goes through; if it fails, the relay stays open and\n  can be cancelled again once that attempt is over. A relay that is already\n  closed (delivered, expired, cancelled) exits 2 too.\n\n  A reply is held rather than delivered while the requesting session is\n  generating -- typing into a running composer interrupts the turn -- and is\n  delivered as soon as it is idle again.\n\n### commandmate wait <worktree-id...>\n  Block until agent completes or prompt is detected.\n\n  Options:\n    --timeout <seconds>        Maximum wait time\n    --on-prompt <mode>         agent (default) or human\n    --stall-timeout <seconds>  Max time without output change\n    --instance <id>            Agent instance to wait on. There is no --agent here.\n    --verify                   After completion, run every verification gate\n    --require-work             After completion, run only the work-evidence gate\n    --auto-yes-grace <seconds> With the target's Auto-Yes on, how long a prompt may\n                               stay open before exit 10 (default 30; 0 = at once)\n\n  Exit codes:\n    0   - Completed (agent idle/ready), and verified when --verify was given\n    10  - Prompt detected (--on-prompt agent mode)\n    20  - A verification gate failed (--verify)\n    21  - Nothing to verify: no commits, no uncommitted changes\n    124 - Timeout exceeded\n\n  --on-prompt modes:\n    agent  - Returns exit 10 with prompt JSON on stdout: at once, or after the\n             Auto-Yes grace below when the target's Auto-Yes is on\n    human  - Keeps blocking until human responds via browser UI\n\n  Auto-Yes on the target (Issue #2463): in agent mode a prompt on a session\n  whose Auto-Yes is on is held, not reported, for up to --auto-yes-grace\n  seconds (default 30) -- Auto-Yes answers it within seconds, and an exit 10\n  would stop a delegation for a prompt nobody had to see. One stderr line says\n  so; stdout stays empty. If the prompt clears, wait goes on judging completion\n  as usual ('ask' does the same). It still exits 10 when the grace runs out,\n  and at once when the Auto-Yes policy withheld the answer -- the payload then\n  carries autoYesSuppression. --auto-yes-grace 0 restores the immediate exit.\n\n  Prompt JSON output (exit 10):\n    {\"worktreeId\":\"...\",\"cliToolId\":\"claude\",\"type\":\"yes_no\",\"question\":\"...\",\"options\":[\"yes\",\"no\"],\"status\":\"pending\"}\n    The payload IS the prompt -- read it from stdout before falling back to\n    capture. Since Issue #3755 it also carries \"observation\", the payload\n    \"commandmate prompt --json\" prints, read off the same capture. For type \"selection_list\", options is empty by design and the\n    question field carries the reason.\n\n    Three \"type\" values share exit 10; only the first is answerable with\n    respond:\n      yes_no / multiple_choice  a parsed prompt        -> commandmate respond\n      selection_list            arrow-key menu         -> special keys\n      unclassified              the frame is interactive but detection could\n                                not parse it, and it has stayed that way for\n                                60s -> look at the pane: capture <id> --pane\n    \"unclassified\" exists because a frame that slips past detection disables\n    auto-yes, the contract's autoYes policy and this exit 10 all at once. It\n    needs the dwell: a capture taken mid-repaint can raise the flag once.\n    --on-prompt human keeps waiting for it, same as the other two.\n\n    On opencode the commonest cause has a name and a one-key fix. If its\n    sidebar is on -- ctrl+x b, or \"Show sidebar\" in its ctrl+p palette -- it\n    shares screen rows with the transcript, covers the marker that ends a\n    turn, and every frame after that reads running/unknown_frame. wait says\n    so on stderr (paneObstruction=opencode_sidebar) and capture --json\n    publishes the same field. Press ctrl+x b in the pane to close it; Escape\n    does not.\n\n    An opencode DIALOG is the other one, and it exits 10 as selection_list\n    rather than waiting out the dwell. Its session list (ctrl+x l), agent list\n    (ctrl+x a), timeline (ctrl+x g), command palette (ctrl+p) and pickers are\n    painted over the transcript, so the marker of the previous turn is still\n    on the pane behind them -- which is what used to make wait report a\n    blocked pane as Completed. sessionStatusReason is opencode_modal_overlay\n    and Escape closes all of them.\n\n  --verify turns \"the agent stopped\" into \"the work passes the repository's own\n  checks\". Verification only runs when completion was detected: a prompt (10) or\n  a timeout (124) is reported as-is and never verified. With several worktrees,\n  gates run one worktree at a time because the server caps concurrent runs.\n\n### commandmate verify <worktree-id>\n  Run the gates declared in .commandmate/verify.yaml against a worktree.\n\n  Options:\n    --gates <id1,id2>     Gate ids to run (default: work-evidence + all declared)\n    --instance <id>       Attribute the run to an agent instance\n    --timeout <seconds>   Stop polling after N seconds (exit 124)\n    --json                Print the run and its gate results as JSON on stdout\n\n  Exit codes:\n    0   - Every gate passed\n    20  - A gate failed, timed out, or errored\n    21  - work-evidence found nothing to verify (no commits, no changes)\n    99  - The run produced no verdict (bad verify.yaml, gates skipped, cancelled)\n    124 - --timeout elapsed while the run was still going\n\n  Output (progress on stderr, verdict on stdout):\n    GATE work-evidence PASS (commits=3, uncommitted=2)\n    GATE lint PASS (exit=0, 12.3s)\n    GATE unit FAIL (exit=1, 45.0s)\n    RESULT failed\n\n  Gates run in the worktree's own directory. Gates are skipped (run status 99,\n  never 0) in the checkout the server itself runs from when verify.yaml sets\n  options.skipInPrimaryCheckout, so a 'build' gate cannot replace the assets the\n  live app is serving.\n\n### commandmate verify init\n  Draft .commandmate/verify.yaml from this repository's own CI definitions\n  (Issue #2061). Reads every 'run:' step in .github/workflows/*.yml plus the\n  canonical package.json scripts, and declares the ones that are safe to re-run.\n\n  Options:\n    --cwd <path>          Repository to draft for (default: current directory)\n    --dry-run             Print the proposal on stdout and write nothing\n    --json                Print gates, refusals and scanned files as JSON\n\n  Exit codes:\n    0   - Wrote (or, with --dry-run, proposed) the config\n    2   - The config already exists, or nothing draftable was found\n\n  NEVER overwrites. An existing verify.yaml is the repository's own judgement of\n  what passing means, usually with the reasoning for each gate beside it, so\n  there is no --force: \"throw it away\" is spelled by deleting the file.\n\n  The only verify subcommand that needs no server: it is what you run BEFORE the\n  repository has anything to verify.\n\n  Commands that are found and NOT declared are reported with a reason on stderr\n  (setup, network, release, container, mutating, long-running, multi-line,\n  multi-command, runner-specific, not-a-check, interactive, redundant,\n  unquotable, reserved-id). A gate must be safe to run any number of times, so\n  'npm ci', 'npm publish', 'npm audit' and e2e suites never become gates.\n\n  The draft is a draft: it mirrors what CI already runs, not what the repository\n  considers sufficient. Read it, then run it once and confirm RESULT passed.\n\n### commandmate verify history / commandmate verify show <run-id>\n  Read past verification runs. Both are read-only and never start a run, so\n  neither returns 20 or 21 \u2014 those mean \"this tree failed verification\", and a\n  question about history is not a verdict on the current tree.\n\n  commandmate verify history                          # every worktree, newest 50\n  commandmate verify history --worktree <id>          # one worktree\n  commandmate verify history --days 14 --limit 100    # window and page size\n  commandmate verify history --json                   # JSON array on stdout\n  commandmate verify show 42                          # gates + log tails\n  commandmate verify show 42 --json\n\n  history options:\n    --worktree <id>       Restrict to one worktree (default: all)\n    --days <n>            Look back n days, 1..90 (default: no lower bound)\n    --limit <n>           Maximum runs, 1..500 (default: 50)\n\n  One run per line. The leading #<run-id> is what \"verify show\" takes:\n    #42  2026-07-31T04:12:00.000Z  myrepo-feature-101  manual  failed  failed: unit,build\n\n  The listing carries gate verdicts but NOT gate log bodies \u2014 logTail is absent\n  from the JSON, not null. Use \"verify show <run-id>\" when you need the log.\n\n  Exit codes:\n    0   - Read succeeded (also when nothing matched: stderr note, or [] in JSON)\n    2   - Bad argument (--days/--limit out of range, bad worktree or run id)\n    99  - No such run (404), or an unexpected failure\n\n### commandmate prompt <worktree-id> --instance <id> [--json]\n  Observe, once, the screen an agent is stopped on (Issue #3755): its kind,\n  question, options, current selection, approval target, how it is answered,\n  a short-lived observation token, and Auto-Yes as two separate items -- the\n  poller's last record and the contract's policy re-evaluated now. The token\n  is single use and bound to this appearance of the screen and its highlighted\n  option; none is issued for unknown or when the session generation is not\n  known (\"tokenWithheld\" says which).\n\n  Kinds: antigravity-trust, antigravity-model-picker, antigravity-permission,\n  antigravity-slash-menu, composer / none (nothing asks), unknown (something\n  waits and no measured reading names it -- look at capture <id> --pane).\n  A missing poller record does NOT mean Auto-Yes can answer.\n\n  Exit codes:\n    0  - The screen was read (also composer / none / unknown)\n    21 - No running session: nothing to read\n\n### commandmate respond <worktree-id> \"<answer>\"\n  Respond to an agent's prompt.\n\n  commandmate respond <id> \"yes\"          # Yes/No\n  commandmate respond <id> \"2\"            # Multiple choice (number)\n  commandmate respond <id> \"custom text\"  # Free text\n  commandmate respond <id> \"yes\" --instance codex-2   # Specific instance\n\n  Exit codes:\n    0  - Response sent\n    99 - Prompt already dismissed (prompt_no_longer_active)\n    99 - answer_not_delivered: nothing was typed, safe to respond again\n    99 - answer_input_lost: may be partly typed; capture --pane that target before answering again\n         (read from the 500's reason on a server declaring prompt-answer-reason; older: the error text)\n\n  Strict mode (Issue #3756) -- answer only the screen you observed:\n    commandmate prompt <id> --instance antigravity --json      # kind, token, approvalTarget\n    commandmate respond <id> \"Yes\" --instance antigravity \\\n      --expect-screen antigravity-trust --observation <token> \\\n      --expect-target \"<approvalTarget>\" --json\n  The server re-captures the pane and sends nothing unless the kind, the token\n  (pane, generation, appearance, options, highlight) and, on a trust screen,\n  the folder still match. Own endpoint (prompt-response/strict); an older\n  server is a stop, never a fallback. Kinds: antigravity-trust,\n  antigravity-permission. Unnumbered screens (trust) take a label only, sent as\n  Up/Down + Enter: a number, --default, a label matching two options and an\n  option off screen are refused. While the instance's Auto-Yes is on,\n  antigravity-permission is refused (auto_yes_active): run auto-yes <id>\n  --disable first (the trust screen is answered either way). Retry with the\n  same --operation-id and arguments to read the result instead of sending\n  twice; other arguments under a used id are operation_id_conflict (41).\n  answeredBy in the record is self-reported by the CLI. Residual race: keys typed at the pane\n  between the last check and a key are not seen. NOT a way to get auto mode's\n  permission for an approval.\n    0  - Answered (outcome advanced / next-prompt / session-ended)\n    40 - Nothing was sent (mismatch, unreadable, old server): observe again\n    41 - Keys sent, result not confirmed: do NOT send again\n\n### commandmate interrupt <worktree-id>\n  Interrupt the turn an agent is generating (the GUI's interrupt button).\n  Not 'stop' -- that stops the CommandMate server.\n\n  commandmate interrupt <id>                    # Every running session of the worktree\n  commandmate interrupt <id> --instance codex-2 # Only that instance\n  commandmate interrupt <id> --json             # { success, message, interrupted[] }\n\n  Omitting --instance is a broadcast, not \"the primary instance\": the route\n  interrupts every session that is running. There is no --agent (wait's rule:\n  a tool name does not say which session).\n\n  Exit codes:\n    0  - At least one session was interrupted\n    30 - The worktree exists but nothing was running (nothing was interrupted)\n    99 - No such worktree\n\n### commandmate capture <worktree-id>\n  Get current terminal output.\n\n  commandmate capture <id>                   # Plain text\n  commandmate capture <id> --json            # JSON with status info\n  commandmate capture <id> --instance codex  # Specific instance\n\n### commandmate reply <worktree-id>\n  Print the latest reply a session wrote, read from its transcript (no pane).\n  Use it to read a turn you did not send with 'ask' (e.g. \"stop and report\").\n\n  commandmate reply <id> --instance cc-1                          # Reply body\n  commandmate reply <id> --instance cc-1 --since 2026-09-30T12:00:00Z --json\n\n  Only transcript-reader rows (<tool>-turn:<id>) count, as in 'ask'. No reply\n  yet: exit 0, empty stdout, one line on stderr; --json prints \"reply\": null.\n\n### commandmate auto-yes <worktree-id>\n  Control auto-yes (automatic prompt response).\n\n  commandmate auto-yes <id> --enable                    # Enable (default 1h)\n  commandmate auto-yes <id> --enable --duration 3h      # With duration\n  commandmate auto-yes <id> --enable --stop-pattern \"error\"\n  commandmate auto-yes <id> --disable                   # Disable\n  commandmate auto-yes <id> --enable --instance codex-2 # Scoped to one instance\n  commandmate auto-yes <id> --enable --answer-mode careful  # Questions are yours\n\n  --answer-mode (Issue #3863) decides how a question the agent asks (claude's\n  AskUserQuestion, command-code's question) is treated: recommended (the\n  default) answers it with the option whose title ends in (Recommended) /\n  \uFF08\u63A8\u5968\uFF09 / (\u63A8\u5968), else the default option, and leaves it to you when that\n  cannot be told (recommended-option-unidentified); careful leaves every such\n  question to you (question-left-to-human). Permissions are answered alike\n  (allow this call once), and the Submit/Cancel confirm page, OpenCode V2's\n  questions and whatever the contract withholds are never answered. Omitted,\n  a new grant is recommended and a grant that is on keeps its mode. The mode\n  shows as autoYesAnswerMode in capture --json / instances --json.\n\n  --stop-pattern matches new terminal output, not the commands an agent runs.\n  It cannot block a command; a build log that merely prints the pattern\n  (e.g. \"rm -rf\" in an npm script) also triggers it and stops auto-yes.\n  To suppress auto-responses for risky prompts, use the task contract's\n  autoYes.denyPatterns instead (docs/design/task-contract.md).\n\n  When the contract running on the instance sets autoYes.mode: off, --enable\n  (and send --auto-yes) print a 'Warning:' line on stderr and still exit 0:\n  Auto-Yes is armed but answers nothing there. safe / allow-listed add one\n  'Note:' line naming what is answered (Issue #3723).\n\n  A server restart turns every grant OFF and never turns one back on. After a\n  graceful stop (SIGINT / SIGTERM, e.g. /rebuild or 'commandmate stop') each\n  instance whose grant was live reports why, until that grant's own deadline or\n  the next --enable / --disable (Issue #3730): 'capture --json' autoYes.stopReason\n  = 'server-restart', 'ls' AUTO_YES 'off(restart)', 'instances' AUTO_YES\n  'no(restart)', a 'wait' exit 10 adds a stderr line, and the UI toggle reads\n  \"Released by restart\". Re-enable with --enable --instance <that instance> (a\n  bare --enable arms the default primary). A SIGKILL or a crash records\n  nothing: those grants come back as a plain off.\n\n### commandmate instances <worktree-id> [action] [args]\n  Discover and manage a worktree's agent-instance roster (1 agent, multiple sessions).\n\n  commandmate instances <id>                            # List roster + running/auto-yes status\n  commandmate instances <id> --json                     # JSON output\n  commandmate instances <id> add --agent codex          # Add an instance (auto-generates ID, e.g. codex-2)\n  commandmate instances <id> add --agent codex --alias \"Review\" --id codex-3\n  commandmate instances <id> remove <instance-id>       # Remove from roster\n  commandmate instances <id> remove <instance-id> --kill  # Remove and kill its session\n  commandmate instances <id> alias <instance-id> \"New Name\"\n  commandmate instances <id> kill <instance-id>         # Kill only that instance's session\n\n  See \"Multi-Session\" below for the ID convention and roster semantics.\n\n### commandmate skill <subcommand>\n  Manage official Agent Skills. Every subcommand is a thin client over the same\n  APIs the browser UI uses: the CLI never downloads, extracts, writes or deletes\n  anything itself, and never sends a filesystem path, artifact URL, file list or\n  checksum (the API rejects those outright).\n\n  commandmate skill list [--json] [--prerelease]\n  commandmate skill info <skill-id> [--version <v>] [--json]\n  commandmate skill plan <skill-id> --worktree <id> [--version <v>] [--json]\n  commandmate skill install <skill-id> --worktree <id> --version <exact> [--dry-run] [--yes] [--ack-risk <id>@<version>] [--json]\n  commandmate skill uninstall <skill-id> --worktree <id> [--dry-run] [--yes] [--json]\n  commandmate skill status <skill-id> --worktree <id> [--json]\n\n  Confirmation contract (writes = install / uninstall):\n    - A plan is always built and shown first. --dry-run stops there.\n    - Without a TTY, a write REQUIRES --yes. A missing --yes is refused, never\n      assumed: an environment that cannot prompt must not install silently.\n    - A high-risk Skill additionally requires --ack-risk <skill-id>@<version>\n      with the exact id and version. --yes alone never carries a high-risk\n      install, in a TTY or out of one.\n\n  Exit codes:\n    0   success\n    1   the server or the Catalog could not be reached (retryable)\n    2   invalid arguments, unknown Skill or unknown version\n    11  the worktree refused it (local change, conflict, lock, plan drift)\n    12  the write was never confirmed (no --yes, declined, or missing --ack-risk)\n    13  files changed but the operation needs reconciliation\n\n  --json prints the API response body verbatim on stdout; diagnostics, prompts\n  and errors always go to stderr, so a failed --json run leaves stdout empty.\n\n  'skill status' reports one Skill in one worktree, read from the install\n  receipt on disk. There is no per-worktree listing endpoint yet, so <skill-id>\n  is required.\n\n## Multi-Session (1 agent, multiple sessions)\n\n  A worktree can run several sessions of the same CLI tool concurrently. Each\n  session is an \"instance\" identified by an instance ID:\n    <agent>        - the agent's primary instance (e.g. \"claude\")\n    <agent>-<n>    - an additional instance, n >= 2 (e.g. \"claude-2\", \"claude-3\")\n\n  --instance is accepted by send / wait / respond / capture / auto-yes.\n  send --instance auto-starts the session if it is not already running.\n\n  --instance alone is the recommended way to name a target (Issue #1638). It is\n  the only flag all five commands share: --agent is rejected by 'wait'. A\n  rostered instance already carries its CLI tool (Issue #1629), and an instance\n  id that is itself a tool id resolves to that tool's primary instance even\n  without a roster entry, so '--instance codex' needs no --agent.\n\n  --agent remains accepted by send / respond / capture / auto-yes as the\n  supplement for ad-hoc instances the roster does not know -- notably\n  '--register', which cannot infer the tool from an id like codex-3. Passing an\n  --agent that contradicts the roster is an error (exit 2), not an override.\n\n  The roster (visible in the browser UI's Agent panel) is the list of known\n  instances with aliases and display order. Ad-hoc sessions started via\n  'send --instance' do NOT appear in the roster unless registered:\n    commandmate send <id> \"...\" --instance claude-2 --register\n  Without --register, the session still runs and responds to CLI commands,\n  but it will not show up in the UI sidebar/roster until added there or via\n  'commandmate instances <id> add'.\n\n  Per-instance auto-yes: --instance scopes --auto-yes/--duration/--stop-pattern\n  to that specific session, independent of other instances of the same agent.\n\n  --instance also accepts the ALIAS shown in the ALIAS column of\n  'commandmate instances <id>' and in the browser UI's Agent panel\n  (Issue #2376), e.g. --instance \"Codex 2\". An alias two roster rows answer to\n  is refused with exit 2 and both candidates listed; ids always win over aliases.\n\n  commandmate instances <id>                        # discover valid --instance values\n  commandmate send <id> \"task\" --instance codex-2 --auto-yes\n  commandmate wait <id> --instance codex-2 --timeout 600\n  commandmate capture <id> --instance codex-2\n\n  Asking ANOTHER session something and getting its reply is one command, not\n  three -- and waiting for it is optional ('ask --async' / 'send --reply-to',\n  Issue #2377): see 'commandmate docs --section delegation'.\n\n## All Exit Codes\n\n  0   SUCCESS          - Completed successfully\n  1   DEPENDENCY_ERROR - Server not running\n  2   CONFIG_ERROR     - Validation error (invalid agent, duration, etc.)\n  10  PROMPT_DETECTED  - Prompt detected during wait\n  20  VERIFY_FAILED    - A verification gate failed (verify, wait --verify)\n  21  NOT_STARTED      - Nothing to verify: no commits, no uncommitted changes\n  30  NO_ACTIVE_SESSIONS - interrupt found no running session to interrupt\n  99  UNEXPECTED_ERROR - Unexpected error / resource not found / no verdict\n  124 TIMEOUT          - Wait or verification timeout exceeded\n\n  When one 'wait' covers several worktrees, the reported code is the highest\n  priority one observed: 10 > 20 > 21 > 124.\n\n## Troubleshooting\n\n  Server not running:\n    commandmate start --daemon\n    CM_PORT=3011 commandmate ls        # Different port\n\n  Worktree not found:\n    commandmate ls --quiet             # Check registered IDs\n    commandmate sync                   # Sync new worktrees (e.g. after git worktree add)\n    commandmate status                 # Confirm 'ls' and 'status' report the same Port\n                                       # (with several servers running, an exported CM_PORT\n                                       #  points 'ls' at a different one)\n\n  Authentication:\n    CM_AUTH_TOKEN=your-token commandmate ls\n";
+export declare const AGENT_OPERATIONS_GUIDE = "# CLI Agent Operations Guide\n\nOperate agent sessions from the CommandMate CLI.\nThese commands enable coding agents (Claude Code, Codex, etc.) to orchestrate other agents in parallel.\n\n## Prerequisites\n\n- CommandMate server must be running: commandmate start --daemon\n- Target worktrees must be registered (visible in browser UI sidebar)\n- Connection target is resolved as: exported CM_PORT > ~/.commandmate/.env CM_PORT > 3000\n  (CM_BIND and the CM_HTTPS_CERT + CM_HTTPS_KEY pair are honoured the same way)\n- Use CM_AUTH_TOKEN env var for authenticated servers\n\n## Commands\n\n### commandmate ls\n  List worktrees with status.\n\n  commandmate ls                          # Table format (ID, NAME, STATUS, REASON, DEFAULT, AUTO_YES)\n  commandmate ls --json                   # JSON output (for agent consumption)\n  commandmate ls --quiet                  # IDs only, one per line (for piping)\n  commandmate ls --branch <prefix>        # Filter by branch name prefix\n  commandmate ls --id <prefix>            # Filter by worktree id prefix\n\n  Worktree ids are <repo>-<branch> slugs (e.g. anvil-develop). --id / --branch\n  front-match is case-sensitive and does NOT guarantee uniqueness (e.g.\n  --id anvil-develop also matches anvil-develop-2). --branch and --id combine\n  as AND. Use --id to disambiguate the same branch across repositories.\n\n  STATUS values:\n    idle     - Session not started\n    ready    - Session running, waiting for input (task completed)\n    running  - Agent executing a task\n    waiting  - Confirmation prompt active (Yes/No, etc.)\n\n  REASON values (Issue #1926):\n    The evidence behind the STATUS beside it. '<reason> (no evidence)' marks a\n    frame the detection layer could not classify, so the STATUS is a fallback\n    rather than a reading. '-' means the server gives no reason: it predates\n    #1926, the session is not running, or the tool has two or more instances and\n    the per-tool aggregate dropped it. 'commandmate ls --json' keeps the\n    per-tool rows under sessionStatusByCli.<tool>.\n\n  AUTO_YES values (Issue #2575):\n    Time left on the instance that will lose Auto-Yes FIRST, among the instances\n    that explain this row's STATUS (waiting: the ones waiting; running: the ones\n    processing; ready: the ones running; idle: the ones that exited -- a bare\n    idle row falls back to every armed instance).\n\n    MM:SS    - time left, under an hour (e.g. 42:10)\n    H:MM:SS  - time left, an hour or more (e.g. 1:05:33)\n    on       - armed, with no expiry the server named\n    off      - at least one of those instances is NOT armed, so a prompt on this\n               row waits for a human. 'waiting' + 'off' is a confirmation\n               prompt nobody is going to answer -- the cell to look for\n    blocked  - armed, but the contract running on that instance sets\n               autoYes.mode: off, so nothing is answered there either\n               (Issue #3723; --json: autoYesByInstance.<id>.blockedByContract)\n    off(restart) - off, because the server restarted while the grant was live\n               (Issue #3730; --json: autoYesStopReasonByInstance.<id>)\n    -        - not known: the server predates #2512, or this row is not idle and\n               no instance explains its STATUS\n\n    A trailing ' (<instanceId>)' names the instance the cell is about, printed\n    when that is not the default agent's primary. Pass it to capture / send /\n    respond as --instance verbatim.\n\n    Time left is a fact about Auto-Yes, not a promise that the prompt gets\n    answered: a contract autoYes policy can withhold the answer, and a free-text\n    prompt has none to give. 'commandmate capture <id> --json --instance <id>'\n    carries autoYes.lastSuppression and autoYes.stopReason; 'commandmate wait'\n    returns exit 10 for a prompt no agent is going to clear.\n\n    Nothing here is derived in --json: it carries sessionStatusByInstance and\n    autoYesByInstance raw, which is where the per-instance breakdown is.\n\n### commandmate sync\n  Ask the server to re-scan repositories and sync worktrees to its database\n  (same endpoint as the GUI sync button). Run it after 'git worktree add' so the\n  new worktree appears in 'commandmate ls' without opening the GUI (Issue #1680).\n\n  commandmate sync                        # Prints the server's summary message\n  commandmate sync --json                 # Full API response (worktreeCount,\n                                          # repositoryCount, repositories,\n                                          # deletedCount, cleanupWarnings)\n\n### commandmate send <worktree-id> \"<message>\"\n  Send a message to an agent (async). Starts session automatically if not running.\n\n  Options:\n    --instance <id>        Agent instance ID: <agent> or <agent>-<n> (e.g. claude-2, or codex\n                           for the codex primary instance). The recommended way to name a\n                           target: send / wait / respond / capture / auto-yes all take it.\n    --agent <id>           Ad-hoc CLI tool for an instance the roster does not know:\n                           claude (default), codex, gemini, vibe-local, opencode, copilot, antigravity\n    --register             Register the --instance session into the agent-instance roster\n    --auto-yes             Enable auto-yes before sending (session-wide, no policy\n                           guard -- for unattended runs prefer --contract with an\n                           autoYes policy: mode / denyPatterns)\n    --auto-yes-answer-mode <m>\n                           With --auto-yes: recommended (questions answered with the\n                           recommended option, else the default) or careful\n                           (questions left to you). See auto-yes below\n    --duration <d>         Auto-yes duration: 1h-24h, whole hours, e.g. 1h, 3h, 8h\n                           (default: 1h)\n    --stop-pattern <p>     Auto-yes stop condition (regex; matches terminal output,\n                           cannot block commands -- see auto-yes below)\n    --ignore-structured-prompt\n                           Send even if only the agent's hooks report an open dialog.\n                           For a session whose pane looks idle but keeps refusing;\n                           a dialog visible in the terminal is still refused.\n    --reply-to <target>    Deliver the target session's reply into <target>'s composer\n                           when the turn ends: <worktree-id>[@<instance-id|alias>], or\n                           'self' for the session running the command. Nothing blocks --\n                           there is no wait to run and no pane to scrape.\n    --allow-relay-chain    Permit --reply-to while answering a message that itself\n                           arrived over a relay. Refused by default (exit 2); chains\n                           still stop at 3 hops.\n\n  Refused while the agent is waiting on a prompt (exit 2). Keystrokes sent to\n  an open dialog never reach the agent -- they pile up in the dialog's own\n  input line, and the next respond then carries that text along as a message\n  instead of an answer. Nudging a stalled worker is how this gets worse.\n  Answer first: commandmate respond <id> <answer>. respond, special keys and\n  prompt-response are never refused -- they are the way out. Timer-fired sends\n  ARE refused (same service layer) and record [prompt_waiting] as their reason.\n  It fails open if the pane cannot be read, so treat it as a narrowing, not a\n  guarantee.\n\n  Two layers can report the dialog: the terminal scraper, and the agent's own\n  hooks. Either one is enough to refuse -- the dialog the scraper cannot read is\n  exactly the one that caused this. A frame neither layer classifies is still\n  wait's \"unclassified\" case instead.\n\n  A hook-reported dialog is released by the agent's next event, and hooks are\n  fail-open, so the record can outlive its dialog. It therefore stops blocking\n  sends 5 minutes after it was reported -- and immediately with\n  --ignore-structured-prompt, or CM_STRUCTURED_SEND_GUARD=off for the server.\n  A session nobody can send to is worse than a missed guard. Both bypasses are\n  narrow: a prompt on screen is still refused, and the payload still reports it\n  (wait and the UI do not go quiet).\n\n  Message length: up to 48 KiB and 240 lines arrives whole on claude, codex,\n  command-code and antigravity (verified, Issue #2464). Over 512 bytes the\n  message is pasted as one bracketed paste and Enter waits until the agent's\n  composer shows all of it; if it never does, nothing is submitted and send\n  exits 99 (\"Message body did not arrive intact\"). Put a longer brief in a\n  file and send a message that names it ('commandmate docs --section delegation').\n\n  Finding worktree IDs:\n    WT=$(commandmate ls --branch feature/101 --quiet)\n    WT=$(commandmate ls --id anvil- --quiet)   # disambiguate by repo (id prefix)\n    commandmate send \"$WT\" \"Implement this\"\n\n  Targeting a non-default agent (Issue #1638): pass --instance, not --agent. Only\n  --instance is accepted by every command -- 'wait --agent' does not exist -- so a\n  workflow that names the agent on 'send' and nothing on 'wait' waits on the wrong\n  session in silence.\n    commandmate send \"$WT\" \"Implement this\" --instance codex\n    commandmate wait \"$WT\" --instance codex\n\n  Delegating without blocking (--reply-to):\n    commandmate send \"$WT\" \"Implement this\" --instance codex --reply-to self\n    # ... keep working. When codex finishes, its answer arrives in your composer as\n    # [from Codex 2 / <worktree>] <reply>, saved in History as a 'relay' message.\n    commandmate relays                       # what is still outstanding\n\n  The relay is refused (exit 2, nothing sent) when the message you are answering\n  arrived over a relay itself (pass --allow-relay-chain), when the chain would\n  exceed 3 hops, or when an open relay between the two sessions already exists.\n  If the target stops on a confirmation you are told, once, and the relay stays\n  open -- answer the dialog on that session and the reply still arrives. A relay\n  nobody could deliver expires after 24h with a single line of notice.\n  The relay is tied to this send (Issue #3957): only a turn that ends after the\n  message started going in is delivered, and a reply that may share a turn with\n  another request carries one '[CommandMate relay] ... (overlap=...)' line under\n  the header. When the send's outcome is unknown the relay is left open, nothing\n  is resent, and 'commandmate relays --id <relay-id>' shows why it is held.\n\n### commandmate relays\n  List the standing delegations this session is waiting on and owes.\n\n    commandmate relays                      # the session running the command\n    commandmate relays --worktree <id> --instance codex-2\n    commandmate relays --json               # owed / awaiting / open / counts\n    commandmate relays --id <relay-id>      # one relay, closed too: send= overlap= hold=\n    commandmate relays cancel <relay-id>    # withdraw one; nothing is delivered\n\n  States: pending (the worker has not finished), prompt (it stopped on a\n  confirmation at some point and a notice to the requester was queued; still\n  open \u2014 a record, not \"still waiting\": it stays after the confirmation is\n  answered and the reply replaces the notice), delivered, expired, cancelled.\n\n  'relays cancel' cannot withdraw a relay that is being delivered right now\n  (a reply or a prompt notice): the server answers 409 and the command exits\n  2. The delivery usually goes through; if it fails, the relay stays open and\n  can be cancelled again once that attempt is over. A relay that is already\n  closed (delivered, expired, cancelled) exits 2 too.\n\n  A reply is held rather than delivered while the requesting session is\n  generating -- typing into a running composer interrupts the turn -- and is\n  delivered as soon as it is idle again.\n\n  A line may end in pending=<kind> (the payload waiting for the requester's\n  composer) and blocked=<reason>@<time> (Issue #4105): why the LAST delivery\n  attempt of that payload stopped. blocked=prompt_waiting means the\n  requester's own pane shows a confirmation dialog; nothing is typed into it.\n  Answer that dialog and the next pass (about every 15 s) delivers; left alone,\n  the payload is replaced by the expiry notice at the deadline. No blocked=\n  means nothing was observed (e.g. after a restart), not that it can go out.\n  An expired relay whose expiry notice is still stopped (Issue #4193) is\n  listed under \"# closed, notice not delivered yet\" (closedBlocked in --json)\n  until the notice goes out; it is not an open relay and is not counted.\n\n### commandmate wait <worktree-id...>\n  Block until agent completes or prompt is detected.\n\n  Options:\n    --timeout <seconds>        Maximum wait time\n    --on-prompt <mode>         agent (default) or human\n    --stall-timeout <seconds>  Max time without output change\n    --instance <id>            Agent instance to wait on. There is no --agent here.\n    --verify                   After completion, run every verification gate\n    --require-work             After completion, run only the work-evidence gate\n    --auto-yes-grace <seconds> With the target's Auto-Yes on, how long a prompt may\n                               stay open before exit 10 (default 30; 0 = at once)\n\n  Exit codes:\n    0   - Completed (agent idle/ready), and verified when --verify was given\n    10  - Prompt detected (--on-prompt agent mode)\n    20  - A verification gate failed (--verify)\n    21  - Nothing to verify: no commits, no uncommitted changes\n    124 - Timeout exceeded\n\n  --on-prompt modes:\n    agent  - Returns exit 10 with prompt JSON on stdout: at once, or after the\n             Auto-Yes grace below when the target's Auto-Yes is on\n    human  - Keeps blocking until human responds via browser UI\n\n  Auto-Yes on the target (Issue #2463): in agent mode a prompt on a session\n  whose Auto-Yes is on is held, not reported, for up to --auto-yes-grace\n  seconds (default 30) -- Auto-Yes answers it within seconds, and an exit 10\n  would stop a delegation for a prompt nobody had to see. One stderr line says\n  so; stdout stays empty. If the prompt clears, wait goes on judging completion\n  as usual ('ask' does the same). It still exits 10 when the grace runs out,\n  and at once when the Auto-Yes policy withheld the answer -- the payload then\n  carries autoYesSuppression. --auto-yes-grace 0 restores the immediate exit.\n\n  Prompt JSON output (exit 10):\n    {\"worktreeId\":\"...\",\"cliToolId\":\"claude\",\"type\":\"yes_no\",\"question\":\"...\",\"options\":[\"yes\",\"no\"],\"status\":\"pending\"}\n    The payload IS the prompt -- read it from stdout before falling back to\n    capture. Since Issue #3755 it also carries \"observation\", the payload\n    \"commandmate prompt --json\" prints, read off the same capture. For type \"selection_list\", options is empty by design and the\n    question field carries the reason.\n\n    Three \"type\" values share exit 10; only the first is answerable with\n    respond:\n      yes_no / multiple_choice  a parsed prompt        -> commandmate respond\n      selection_list            arrow-key menu         -> special keys\n      unclassified              the frame is interactive but detection could\n                                not parse it, and it has stayed that way for\n                                60s -> look at the pane: capture <id> --pane\n    \"unclassified\" exists because a frame that slips past detection disables\n    auto-yes, the contract's autoYes policy and this exit 10 all at once. It\n    needs the dwell: a capture taken mid-repaint can raise the flag once.\n    --on-prompt human keeps waiting for it, same as the other two.\n\n    On opencode the commonest cause has a name and a one-key fix. If its\n    sidebar is on -- ctrl+x b, or \"Show sidebar\" in its ctrl+p palette -- it\n    shares screen rows with the transcript, covers the marker that ends a\n    turn, and every frame after that reads running/unknown_frame. wait says\n    so on stderr (paneObstruction=opencode_sidebar) and capture --json\n    publishes the same field. Press ctrl+x b in the pane to close it; Escape\n    does not.\n\n    An opencode DIALOG is the other one, and it exits 10 as selection_list\n    rather than waiting out the dwell. Its session list (ctrl+x l), agent list\n    (ctrl+x a), timeline (ctrl+x g), command palette (ctrl+p) and pickers are\n    painted over the transcript, so the marker of the previous turn is still\n    on the pane behind them -- which is what used to make wait report a\n    blocked pane as Completed. sessionStatusReason is opencode_modal_overlay\n    and Escape closes all of them.\n\n  --verify turns \"the agent stopped\" into \"the work passes the repository's own\n  checks\". Verification only runs when completion was detected: a prompt (10) or\n  a timeout (124) is reported as-is and never verified. With several worktrees,\n  gates run one worktree at a time because the server caps concurrent runs.\n\n### commandmate verify <worktree-id>\n  Run the gates declared in .commandmate/verify.yaml against a worktree.\n\n  Options:\n    --gates <id1,id2>     Gate ids to run (default: work-evidence + all declared)\n    --instance <id>       Attribute the run to an agent instance\n    --timeout <seconds>   Stop polling after N seconds (exit 124)\n    --json                Print the run and its gate results as JSON on stdout\n\n  Exit codes:\n    0   - Every gate passed\n    20  - A gate failed, timed out, or errored\n    21  - work-evidence found nothing to verify (no commits, no changes)\n    99  - The run produced no verdict (bad verify.yaml, gates skipped, cancelled)\n    124 - --timeout elapsed while the run was still going\n\n  Output (progress on stderr, verdict on stdout):\n    GATE work-evidence PASS (commits=3, uncommitted=2)\n    GATE lint PASS (exit=0, 12.3s)\n    GATE unit FAIL (exit=1, 45.0s)\n    RESULT failed\n\n  Gates run in the worktree's own directory. Gates are skipped (run status 99,\n  never 0) in the checkout the server itself runs from when verify.yaml sets\n  options.skipInPrimaryCheckout, so a 'build' gate cannot replace the assets the\n  live app is serving.\n\n### commandmate verify init\n  Draft .commandmate/verify.yaml from this repository's own CI definitions\n  (Issue #2061). Reads every 'run:' step in .github/workflows/*.yml plus the\n  canonical package.json scripts, and declares the ones that are safe to re-run.\n\n  Options:\n    --cwd <path>          Repository to draft for (default: current directory)\n    --dry-run             Print the proposal on stdout and write nothing\n    --json                Print gates, refusals and scanned files as JSON\n\n  Exit codes:\n    0   - Wrote (or, with --dry-run, proposed) the config\n    2   - The config already exists, or nothing draftable was found\n\n  NEVER overwrites. An existing verify.yaml is the repository's own judgement of\n  what passing means, usually with the reasoning for each gate beside it, so\n  there is no --force: \"throw it away\" is spelled by deleting the file.\n\n  The only verify subcommand that needs no server: it is what you run BEFORE the\n  repository has anything to verify.\n\n  Commands that are found and NOT declared are reported with a reason on stderr\n  (setup, network, release, container, mutating, long-running, multi-line,\n  multi-command, runner-specific, not-a-check, interactive, redundant,\n  unquotable, reserved-id). A gate must be safe to run any number of times, so\n  'npm ci', 'npm publish', 'npm audit' and e2e suites never become gates.\n\n  The draft is a draft: it mirrors what CI already runs, not what the repository\n  considers sufficient. Read it, then run it once and confirm RESULT passed.\n\n### commandmate verify history / commandmate verify show <run-id>\n  Read past verification runs. Both are read-only and never start a run, so\n  neither returns 20 or 21 \u2014 those mean \"this tree failed verification\", and a\n  question about history is not a verdict on the current tree.\n\n  commandmate verify history                          # every worktree, newest 50\n  commandmate verify history --worktree <id>          # one worktree\n  commandmate verify history --days 14 --limit 100    # window and page size\n  commandmate verify history --json                   # JSON array on stdout\n  commandmate verify show 42                          # gates + log tails\n  commandmate verify show 42 --json\n\n  history options:\n    --worktree <id>       Restrict to one worktree (default: all)\n    --days <n>            Look back n days, 1..90 (default: no lower bound)\n    --limit <n>           Maximum runs, 1..500 (default: 50)\n\n  One run per line. The leading #<run-id> is what \"verify show\" takes:\n    #42  2026-07-31T04:12:00.000Z  myrepo-feature-101  manual  failed  failed: unit,build\n\n  The listing carries gate verdicts but NOT gate log bodies \u2014 logTail is absent\n  from the JSON, not null. Use \"verify show <run-id>\" when you need the log.\n\n  Exit codes:\n    0   - Read succeeded (also when nothing matched: stderr note, or [] in JSON)\n    2   - Bad argument (--days/--limit out of range, bad worktree or run id)\n    99  - No such run (404), or an unexpected failure\n\n### commandmate prompt <worktree-id> --instance <id> [--json]\n  Observe, once, the screen an agent is stopped on (Issue #3755): its kind,\n  question, options, current selection, approval target, how it is answered,\n  a short-lived observation token, and Auto-Yes as two separate items -- the\n  poller's last record and the contract's policy re-evaluated now. The token\n  is single use and bound to this appearance of the screen and its highlighted\n  option; none is issued for unknown or when the session generation is not\n  known (\"tokenWithheld\" says which).\n\n  Kinds: antigravity-trust, antigravity-model-picker, antigravity-permission,\n  antigravity-slash-menu, composer / none (nothing asks), unknown (something\n  waits and no measured reading names it -- look at capture <id> --pane).\n  A missing poller record does NOT mean Auto-Yes can answer.\n\n  Exit codes:\n    0  - The screen was read (also composer / none / unknown)\n    21 - No running session: nothing to read\n\n### commandmate respond <worktree-id> \"<answer>\"\n  Respond to an agent's prompt.\n\n  commandmate respond <id> \"yes\"          # Yes/No\n  commandmate respond <id> \"2\"            # Multiple choice (number)\n  commandmate respond <id> \"custom text\"  # Free text\n  commandmate respond <id> \"yes\" --instance codex-2   # Specific instance\n\n  Exit codes:\n    0  - Response sent\n    99 - Prompt already dismissed (prompt_no_longer_active)\n    99 - answer_not_delivered: nothing was typed, safe to respond again\n    99 - answer_input_lost: may be partly typed; capture --pane that target before answering again\n         (read from the 500's reason on a server declaring prompt-answer-reason; older: the error text)\n\n  Strict mode (Issue #3756) -- answer only the screen you observed:\n    commandmate prompt <id> --instance antigravity --json      # kind, token, approvalTarget\n    commandmate respond <id> \"Yes\" --instance antigravity \\\n      --expect-screen antigravity-trust --observation <token> \\\n      --expect-target \"<approvalTarget>\" --json\n  The server re-captures the pane and sends nothing unless the kind, the token\n  (pane, generation, appearance, options, highlight) and, on a trust screen,\n  the folder still match. Own endpoint (prompt-response/strict); an older\n  server is a stop, never a fallback. Kinds: antigravity-trust,\n  antigravity-permission. Unnumbered screens (trust) take a label only, sent as\n  Up/Down + Enter: a number, --default, a label matching two options and an\n  option off screen are refused. While the instance's Auto-Yes is on,\n  antigravity-permission is refused (auto_yes_active): run auto-yes <id>\n  --disable first (the trust screen is answered either way). Retry with the\n  same --operation-id and arguments to read the result instead of sending\n  twice; other arguments under a used id are operation_id_conflict (41).\n  answeredBy in the record is self-reported by the CLI. Residual race: keys typed at the pane\n  between the last check and a key are not seen. NOT a way to get auto mode's\n  permission for an approval.\n    0  - Answered (outcome advanced / next-prompt / session-ended)\n    40 - Nothing was sent (mismatch, unreadable, old server): observe again\n    41 - Keys sent, result not confirmed: do NOT send again\n\n### commandmate interrupt <worktree-id>\n  Interrupt the turn an agent is generating (the GUI's interrupt button).\n  Not 'stop' -- that stops the CommandMate server.\n\n  commandmate interrupt <id>                    # Every running session of the worktree\n  commandmate interrupt <id> --instance codex-2 # Only that instance\n  commandmate interrupt <id> --json             # { success, message, interrupted[] }\n\n  Omitting --instance is a broadcast, not \"the primary instance\": the route\n  interrupts every session that is running. There is no --agent (wait's rule:\n  a tool name does not say which session).\n\n  Exit codes:\n    0  - At least one session was interrupted\n    30 - The worktree exists but nothing was running (nothing was interrupted)\n    99 - No such worktree\n\n### commandmate capture <worktree-id>\n  Get current terminal output.\n\n  commandmate capture <id>                   # Plain text\n  commandmate capture <id> --json            # JSON with status info\n  commandmate capture <id> --instance codex  # Specific instance\n\n### commandmate reply <worktree-id>\n  Print the latest reply a session wrote, read from its transcript (no pane).\n  Use it to read a turn you did not send with 'ask' (e.g. \"stop and report\").\n\n  commandmate reply <id> --instance cc-1                          # Reply body\n  commandmate reply <id> --instance cc-1 --since 2026-09-30T12:00:00Z --json\n\n  Only transcript-reader rows (<tool>-turn:<id>) count, as in 'ask'. No reply\n  yet: exit 0, empty stdout, one line on stderr; --json prints \"reply\": null.\n\n### commandmate auto-yes <worktree-id>\n  Control auto-yes (automatic prompt response).\n\n  commandmate auto-yes <id> --enable                    # Enable (default 1h)\n  commandmate auto-yes <id> --enable --duration 3h      # With duration\n  commandmate auto-yes <id> --enable --stop-pattern \"error\"\n  commandmate auto-yes <id> --disable                   # Disable\n  commandmate auto-yes <id> --enable --instance codex-2 # Scoped to one instance\n  commandmate auto-yes <id> --enable --answer-mode careful  # Questions are yours\n\n  --answer-mode (Issue #3863) decides how a question the agent asks (claude's\n  AskUserQuestion, command-code's question) is treated: recommended (the\n  default) answers it with the option whose title ends in (Recommended) /\n  \uFF08\u63A8\u5968\uFF09 / (\u63A8\u5968), else the default option, and leaves it to you when that\n  cannot be told (recommended-option-unidentified); careful leaves every such\n  question to you (question-left-to-human). Permissions are answered alike\n  (allow this call once), and the Submit/Cancel confirm page, OpenCode V2's\n  questions and whatever the contract withholds are never answered. Omitted,\n  a new grant is recommended and a grant that is on keeps its mode. The mode\n  shows as autoYesAnswerMode in capture --json / instances --json.\n\n  --stop-pattern matches new terminal output, not the commands an agent runs.\n  It cannot block a command; a build log that merely prints the pattern\n  (e.g. \"rm -rf\" in an npm script) also triggers it and stops auto-yes.\n  To suppress auto-responses for risky prompts, use the task contract's\n  autoYes.denyPatterns instead (docs/design/task-contract.md).\n\n  When the contract running on the instance sets autoYes.mode: off, --enable\n  (and send --auto-yes) print a 'Warning:' line on stderr and still exit 0:\n  Auto-Yes is armed but answers nothing there. safe / allow-listed add one\n  'Note:' line naming what is answered (Issue #3723).\n\n  A server restart turns every grant OFF and never turns one back on. After a\n  graceful stop (SIGINT / SIGTERM, e.g. /rebuild or 'commandmate stop') each\n  instance whose grant was live reports why, until that grant's own deadline or\n  the next --enable / --disable (Issue #3730): 'capture --json' autoYes.stopReason\n  = 'server-restart', 'ls' AUTO_YES 'off(restart)', 'instances' AUTO_YES\n  'no(restart)', a 'wait' exit 10 adds a stderr line, and the UI toggle reads\n  \"Released by restart\". Re-enable with --enable --instance <that instance> (a\n  bare --enable arms the default primary). A SIGKILL or a crash records\n  nothing: those grants come back as a plain off.\n\n### commandmate instances <worktree-id> [action] [args]\n  Discover and manage a worktree's agent-instance roster (1 agent, multiple sessions).\n\n  commandmate instances <id>                            # List roster + running/auto-yes status\n  commandmate instances <id> --json                     # JSON output\n  commandmate instances <id> add --agent codex          # Add an instance (auto-generates ID, e.g. codex-2)\n  commandmate instances <id> add --agent codex --alias \"Review\" --id codex-3\n  commandmate instances <id> remove <instance-id>       # Remove from roster\n  commandmate instances <id> remove <instance-id> --kill  # Remove and kill its session\n  commandmate instances <id> alias <instance-id> \"New Name\"\n  commandmate instances <id> kill <instance-id>         # Kill only that instance's session\n\n  commandmate instances <id> add --agent codex --role reviewer   # Add it with a role (--no-role: none)\n  commandmate instances <id> set-role <instance-id> --role reviewer  # For its next start (or --none / --inherit)\n\n  See \"Multi-Session\" below for the ID convention and roster semantics, and\n  \"commandmate roles\" below for what a role is and how it reaches a session.\n  --json rows carry role: { stored, effectiveNext, launched, requested, restartPending },\n  each with its source. launched null means not known, which is not \"no role\".\n  set-role --json: { success, instanceId, cliToolId, adapterEnabled, stored, effectiveNext,\n  launched, requested, restartPending, applyPending, rosterRevision }. applyPending is true\n  only when the running process differs from the next start.\n\n### commandmate roles\n  Define roles and set which one a new session gets, without the screen. Never interactive.\n\n  commandmate roles list [--json]\n  commandmate roles show <role> [--json]\n  commandmate roles add <name> (--file <path> | --stdin) [--json]\n  commandmate roles edit <role> [--name <name>] [--file <path> | --stdin] [--if-version <n>] [--json]\n  commandmate roles rm <role> [--force] [--json]\n  commandmate roles default <tool> (--role <role> | --none) [--json]\n  commandmate roles default <tool> --repo <repository> (--role <role> | --none | --inherit) [--json]\n  commandmate roles defaults [--repo <repository>] [--tool <tool>] [--json]\n\n  Define a reviewer and make it this repository's Codex default:\n    commandmate roles add reviewer --file ./reviewer.md\n    commandmate roles default codex --repo . --role reviewer\n\n  Three different things:\n    roles edit       the role's text. Everything pointing at it follows, from its next start.\n    roles default    what a new start of a tool resolves to: one repository (--repo), or all\n                     that do not say otherwise. Schedules follow too.\n    set-role / send --role   one instance.\n  A role is fixed when the process starts. None of these touches a running session: stop it\n  (instances <wt> kill <id>) and send again.\n\n  <role> is an ID or a name; two candidates is exit 2 with both listed. Nothing is reserved:\n  --none, --no-role and --inherit are flags, so a role can be called none.\n  --repo is an ID, then a path (a value with \"/\" or starting with \".\"; a worktree of a\n  repository means that repository, so --repo . works inside one), then a name. See what is\n  registered with: commandmate roles defaults. Errors: unknown_repository,\n  repository_not_registered (a directory with no row), ambiguous_repository. A repository\n  with no setting for a tool reads stored: inherit, and effective says what it gets.\n  Tools: claude, codex, command-code, opencode, opencode-v2, copilot, antigravity.\n\n  send --role <role> / --no-role is a condition, not a switch: saved first, then a running\n  session gets the message only if it started with exactly that. Another role, or no record of\n  its start, is exit 32 with nothing typed, and the setting stays saved. An ad-hoc id needs\n  --register too: --register --role creates the instance and its role BEFORE sending, so the\n  first start has it, and repeating it replaces the setting and is a condition as above.\n  --register without a role registers after sending, and the message has gone out by then: a roster\n  that kept changing, or any other failure to register, is a warning and exit 0 (not exit 31). Do\n  not send it again; the warning has the command that registers it.\n  --auto-yes applied after the message (--model on a tool that arms after it, or a grant already on)\n  cannot take the send back: if it fails, that is a warning and exit 0, so do not send it again; the\n  warning has the command that enables it. Armed before the message, a failure is an error with\n  nothing sent.\n  --expect-role-generation <g> with --expect-role-fingerprint <f> | --expect-no-role pin a send\n  to what capture --json's roleLaunch said, saving nothing: a process replaced before the\n  first key gets nothing (exit 32). A send with a role or a pin that types nothing withdraws the\n  --auto-yes it armed, and leaves a grant already on as it was. --auto-yes with no role, pin or\n  --reply-to reads nothing first: it cannot tell a grant it armed from one already on, so a refused\n  send leaves it on, with the command that stops it. A server too old to name its grants (no\n  grantId) is not asked to withdraw one either: it stays on, with the same command.\n  send --new-conversation: OpenCode V1 continues the conversation it remembers, even under another\n  role, and stopping it does not forget it. Stop the session and send with this to start a new one.\n  Another tool, or a session running or starting at that check, is exit 2 with nothing sent.\n\n  Exit codes: 0 done; 1 server not running; 2 bad arguments, unknown or ambiguous role or\n  repository, a tool outside the feature; 31 a conflict, nothing changed (name_conflict,\n  name_changed, version_conflict, role_in_use, instance_exists, roster_changed; plain instances\n  add/remove/alias end in roster_changed too, and remove --kill may have stopped the session by\n  then, as it stops first and saves after); 32 nothing typed (send);\n  99 anything else. --json failures: { success: false, error, message, candidates?, references? }.\n  Full --json shapes: commandmate roles --help\n\n### commandmate skill <subcommand>\n  Manage official Agent Skills. Every subcommand is a thin client over the same\n  APIs the browser UI uses: the CLI never downloads, extracts, writes or deletes\n  anything itself, and never sends a filesystem path, artifact URL, file list or\n  checksum (the API rejects those outright).\n\n  commandmate skill list [--json] [--prerelease]\n  commandmate skill info <skill-id> [--version <v>] [--json]\n  commandmate skill plan <skill-id> --worktree <id> [--version <v>] [--json]\n  commandmate skill install <skill-id> --worktree <id> --version <exact> [--dry-run] [--yes] [--ack-risk <id>@<version>] [--json]\n  commandmate skill uninstall <skill-id> --worktree <id> [--dry-run] [--yes] [--json]\n  commandmate skill status <skill-id> --worktree <id> [--json]\n\n  Confirmation contract (writes = install / uninstall):\n    - A plan is always built and shown first. --dry-run stops there.\n    - Without a TTY, a write REQUIRES --yes. A missing --yes is refused, never\n      assumed: an environment that cannot prompt must not install silently.\n    - A high-risk Skill additionally requires --ack-risk <skill-id>@<version>\n      with the exact id and version. --yes alone never carries a high-risk\n      install, in a TTY or out of one.\n\n  Exit codes:\n    0   success\n    1   the server or the Catalog could not be reached (retryable)\n    2   invalid arguments, unknown Skill or unknown version\n    11  the worktree refused it (local change, conflict, lock, plan drift)\n    12  the write was never confirmed (no --yes, declined, or missing --ack-risk)\n    13  files changed but the operation needs reconciliation\n\n  --json prints the API response body verbatim on stdout; diagnostics, prompts\n  and errors always go to stderr, so a failed --json run leaves stdout empty.\n\n  'skill status' reports one Skill in one worktree, read from the install\n  receipt on disk. There is no per-worktree listing endpoint yet, so <skill-id>\n  is required.\n\n## Multi-Session (1 agent, multiple sessions)\n\n  A worktree can run several sessions of the same CLI tool concurrently. Each\n  session is an \"instance\" identified by an instance ID:\n    <agent>        - the agent's primary instance (e.g. \"claude\")\n    <agent>-<n>    - an additional instance, n >= 2 (e.g. \"claude-2\", \"claude-3\")\n\n  --instance is accepted by send / wait / respond / capture / auto-yes.\n  send --instance auto-starts the session if it is not already running.\n\n  --instance alone is the recommended way to name a target (Issue #1638). It is\n  the only flag all five commands share: --agent is rejected by 'wait'. A\n  rostered instance already carries its CLI tool (Issue #1629), and an instance\n  id that is itself a tool id resolves to that tool's primary instance even\n  without a roster entry, so '--instance codex' needs no --agent.\n\n  --agent remains accepted by send / respond / capture / auto-yes as the\n  supplement for ad-hoc instances the roster does not know -- notably\n  '--register', which cannot infer the tool from an id like codex-3. Passing an\n  --agent that contradicts the roster is an error (exit 2), not an override.\n\n  The roster (visible in the browser UI's Agent panel) is the list of known\n  instances with aliases and display order. Ad-hoc sessions started via\n  'send --instance' do NOT appear in the roster unless registered:\n    commandmate send <id> \"...\" --instance claude-2 --register\n  Without --register, the session still runs and responds to CLI commands,\n  but it will not show up in the UI sidebar/roster until added there or via\n  'commandmate instances <id> add'.\n\n  Per-instance auto-yes: --instance scopes --auto-yes/--duration/--stop-pattern\n  to that specific session, independent of other instances of the same agent.\n\n  --instance also accepts the ALIAS shown in the ALIAS column of\n  'commandmate instances <id>' and in the browser UI's Agent panel\n  (Issue #2376), e.g. --instance \"Codex 2\". An alias two roster rows answer to\n  is refused with exit 2 and both candidates listed; ids always win over aliases.\n\n  commandmate instances <id>                        # discover valid --instance values\n  commandmate send <id> \"task\" --instance codex-2 --auto-yes\n  commandmate wait <id> --instance codex-2 --timeout 600\n  commandmate capture <id> --instance codex-2\n\n  Asking ANOTHER session something and getting its reply is one command, not\n  three -- and waiting for it is optional ('ask --async' / 'send --reply-to',\n  Issue #2377): see 'commandmate docs --section delegation'.\n\n## All Exit Codes\n\n  0   SUCCESS          - Completed successfully\n  1   DEPENDENCY_ERROR - Server not running\n  2   CONFIG_ERROR     - Validation error (invalid agent, duration, etc.)\n  10  PROMPT_DETECTED  - Prompt detected during wait\n  20  VERIFY_FAILED    - A verification gate failed (verify, wait --verify)\n  21  NOT_STARTED      - Nothing to verify: no commits, no uncommitted changes\n  30  NO_ACTIVE_SESSIONS - interrupt found no running session to interrupt\n  31  ROLE CONFLICT    - A role or roster conflict; nothing changed or sent (roles, instances, send).\n                         Plain instances add/remove/alias too. remove --kill may have stopped the session\n  32  ROLE NOT_SENT    - The role condition does not hold or its start was refused; nothing typed (send, ask)\n  99  UNEXPECTED_ERROR - Unexpected error / resource not found / no verdict\n  124 TIMEOUT          - Wait or verification timeout exceeded\n\n  When one 'wait' covers several worktrees, the reported code is the highest\n  priority one observed: 10 > 20 > 21 > 124.\n\n## Troubleshooting\n\n  Server not running:\n    commandmate start --daemon\n    CM_PORT=3011 commandmate ls        # Different port\n\n  Worktree not found:\n    commandmate ls --quiet             # Check registered IDs\n    commandmate sync                   # Sync new worktrees (e.g. after git worktree add)\n    commandmate status                 # Confirm 'ls' and 'status' report the same Port\n                                       # (with several servers running, an exported CM_PORT\n                                       #  points 'ls' at a different one)\n\n  Authentication:\n    CM_AUTH_TOKEN=your-token commandmate ls\n";
 export declare const AGENT_OPERATIONS_SAMPLES = "# CLI Agent Operations - Workflow Samples\n\nCopy and adapt these patterns for your use case.\n\n## 1. Basic: send, wait, capture\n\n  WT=$(commandmate ls --branch feature/101 --quiet)\n  commandmate send \"$WT\" \"Implement Issue #101 with TDD\"\n  commandmate wait \"$WT\" --timeout 600\n  commandmate capture \"$WT\"\n\n## 2. With Auto-Yes (unattended execution)\n\n  WT=$(commandmate ls --branch feature/101 --quiet)\n  commandmate send \"$WT\" \"Implement Issue #101\" --auto-yes --duration 3h\n  commandmate wait \"$WT\" --timeout 1800\n  commandmate auto-yes \"$WT\" --disable    # Disable for safety\n  commandmate capture \"$WT\" --json\n\n## 3. Prompt Response Loop\n\n  WT=$(commandmate ls --branch feature/101 --quiet)\n  commandmate send \"$WT\" \"Refactor this module\"\n\n  while true; do\n    commandmate wait \"$WT\" --timeout 600 --on-prompt agent\n    EXIT_CODE=$?\n\n    if [ $EXIT_CODE -eq 0 ]; then\n      echo \"Done\"\n      break\n    elif [ $EXIT_CODE -eq 10 ]; then\n      commandmate respond \"$WT\" \"yes\"\n    elif [ $EXIT_CODE -eq 124 ]; then\n      echo \"Timeout\"\n      break\n    fi\n  done\n\n  commandmate capture \"$WT\"\n\n## 4. Parallel Worktrees\n\n  WT1=$(commandmate ls --branch feature/101 --quiet)\n  WT2=$(commandmate ls --branch feature/102 --quiet)\n\n  commandmate send \"$WT1\" \"Implement #101\" --auto-yes\n  commandmate send \"$WT2\" \"Implement #102\" --auto-yes --instance codex\n\n  # One --instance covers every worktree id in the call, so worktrees on\n  # different instances need one wait each. Both agents keep running while the\n  # first wait blocks, so this costs no wall clock over a combined wait.\n  # A bare 'wait \"$WT2\"' would watch WT2's DEFAULT agent, not the codex session:\n  # 'wait' has no --agent to correct that with.\n  commandmate wait \"$WT1\" --timeout 1800\n  commandmate wait \"$WT2\" --instance codex --timeout 1800\n\n  commandmate capture \"$WT1\" --json\n  commandmate capture \"$WT2\" --instance codex --json\n\n## 5. Check status before sending\n\n  # Find worktrees and check status\n  commandmate ls --json | python3 -c \"\n  import sys, json\n  for wt in json.load(sys.stdin):\n      if wt['name'].startswith('feature/'):\n          print(f\\\"{wt['id']}  {wt['name']}\\\")\n  \"\n\n## 6. Error handling pattern\n\n  WT=$(commandmate ls --branch feature/101 --quiet)\n\n  if [ -z \"$WT\" ]; then\n    echo \"Error: worktree not found\"\n    exit 1\n  fi\n\n  commandmate send \"$WT\" \"Fix the bug\" --auto-yes\n  commandmate wait \"$WT\" --timeout 600\n  EXIT_CODE=$?\n\n  case $EXIT_CODE in\n    0)   echo \"Success\"; commandmate capture \"$WT\" ;;\n    10)  echo \"Prompt detected\"; commandmate respond \"$WT\" \"yes\" ;;\n    124) echo \"Timeout\"; commandmate capture \"$WT\" --json ;;\n    *)   echo \"Error: exit $EXIT_CODE\" ;;\n  esac\n\n## 7. Multi-Session: run a second Codex session alongside the primary agent\n\n  WT=$(commandmate ls --branch feature/101 --quiet)\n\n  # Discover the roster before picking an --instance value\n  commandmate instances \"$WT\"\n\n  # Register a second Codex instance, then send/wait/capture scoped to it.\n  # Once it is in the roster, --instance alone carries the CLI tool.\n  commandmate instances \"$WT\" add --agent codex --alias \"Review\"\n  commandmate send \"$WT\" \"Review the diff\" --instance codex-2 --auto-yes\n  commandmate wait \"$WT\" --instance codex-2 --timeout 600\n  commandmate capture \"$WT\" --instance codex-2 --json\n\n  # Ad-hoc instance without pre-registering (still runs; register to show in UI).\n  # --agent is required here: codex-3 is not in the roster yet, so nothing else\n  # says which CLI tool to start.\n  commandmate send \"$WT\" \"Quick check\" --agent codex --instance codex-3 --register\n\n  # Clean up when done\n  commandmate instances \"$WT\" remove codex-2 --kill\n\n## 8. Verify the work instead of trusting \"the agent stopped\"\n\n  WT=$(commandmate ls --branch feature/101 --quiet)\n  commandmate send \"$WT\" \"Implement Issue #101 with TDD\" --auto-yes\n\n  # One call: wait for completion, then run every gate in .commandmate/verify.yaml\n  commandmate wait \"$WT\" --timeout 1800 --verify\n  case $? in\n    0)  echo \"Verified\" ;;\n    10) commandmate respond \"$WT\" \"yes\" ;;\n    20) echo \"A gate failed\"; commandmate verify \"$WT\" --json ;;\n    21) echo \"The agent produced nothing\" ;;\n  esac\n\n  # Cheap pre-check: is there any work at all, before paying for the full suite?\n  commandmate wait \"$WT\" --require-work || echo \"no commits and no changes\"\n\n  # Re-run a subset after a fix, without waiting on the agent\n  commandmate verify \"$WT\" --gates lint,unit\n";
 /**
  * Delegation between agent sessions (Issue #2376).

package/dist/cli/docs/agent-operations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-operations.d.ts","sourceRoot":"","sources":["../../../src/cli/docs/agent-operations.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,sBAAsB,qxkCA2mBlC,CAAC;AAEF,eAAO,MAAM,wBAAwB,klJAmIpC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,sBAAsB,4mPA6JlC,CAAC"}
+{"version":3,"file":"agent-operations.d.ts","sourceRoot":"","sources":["../../../src/cli/docs/agent-operations.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,sBAAsB,stxCAmsBlC,CAAC;AAEF,eAAO,MAAM,wBAAwB,klJAmIpC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,sBAAsB,4mPA6JlC,CAAC"}

package/dist/cli/docs/agent-operations.js

@@ -197,8 +197,9 @@ These commands enable coding agents (Claude Code, Codex, etc.) to orchestrate ot
     commandmate relays cancel <relay-id>    # withdraw one; nothing is delivered
 
   States: pending (the worker has not finished), prompt (it stopped on a
-  confirmation and the requester was told; still open), delivered, expired,
-  cancelled.
+  confirmation at some point and a notice to the requester was queued; still
+  open — a record, not "still waiting": it stays after the confirmation is
+  answered and the reply replaces the notice), delivered, expired, cancelled.
 
   'relays cancel' cannot withdraw a relay that is being delivered right now
   (a reply or a prompt notice): the server answers 409 and the command exits
@@ -210,6 +211,17 @@ These commands enable coding agents (Claude Code, Codex, etc.) to orchestrate ot
   generating -- typing into a running composer interrupts the turn -- and is
   delivered as soon as it is idle again.
 
+  A line may end in pending=<kind> (the payload waiting for the requester's
+  composer) and blocked=<reason>@<time> (Issue #4105): why the LAST delivery
+  attempt of that payload stopped. blocked=prompt_waiting means the
+  requester's own pane shows a confirmation dialog; nothing is typed into it.
+  Answer that dialog and the next pass (about every 15 s) delivers; left alone,
+  the payload is replaced by the expiry notice at the deadline. No blocked=
+  means nothing was observed (e.g. after a restart), not that it can go out.
+  An expired relay whose expiry notice is still stopped (Issue #4193) is
+  listed under "# closed, notice not delivered yet" (closedBlocked in --json)
+  until the notice goes out; it is not an open relay and is not counted.
+
 ### commandmate wait <worktree-id...>
   Block until agent completes or prompt is detected.
 
@@ -513,7 +525,80 @@ These commands enable coding agents (Claude Code, Codex, etc.) to orchestrate ot
   commandmate instances <id> alias <instance-id> "New Name"
   commandmate instances <id> kill <instance-id>         # Kill only that instance's session
 
-  See "Multi-Session" below for the ID convention and roster semantics.
+  commandmate instances <id> add --agent codex --role reviewer   # Add it with a role (--no-role: none)
+  commandmate instances <id> set-role <instance-id> --role reviewer  # For its next start (or --none / --inherit)
+
+  See "Multi-Session" below for the ID convention and roster semantics, and
+  "commandmate roles" below for what a role is and how it reaches a session.
+  --json rows carry role: { stored, effectiveNext, launched, requested, restartPending },
+  each with its source. launched null means not known, which is not "no role".
+  set-role --json: { success, instanceId, cliToolId, adapterEnabled, stored, effectiveNext,
+  launched, requested, restartPending, applyPending, rosterRevision }. applyPending is true
+  only when the running process differs from the next start.
+
+### commandmate roles
+  Define roles and set which one a new session gets, without the screen. Never interactive.
+
+  commandmate roles list [--json]
+  commandmate roles show <role> [--json]
+  commandmate roles add <name> (--file <path> | --stdin) [--json]
+  commandmate roles edit <role> [--name <name>] [--file <path> | --stdin] [--if-version <n>] [--json]
+  commandmate roles rm <role> [--force] [--json]
+  commandmate roles default <tool> (--role <role> | --none) [--json]
+  commandmate roles default <tool> --repo <repository> (--role <role> | --none | --inherit) [--json]
+  commandmate roles defaults [--repo <repository>] [--tool <tool>] [--json]
+
+  Define a reviewer and make it this repository's Codex default:
+    commandmate roles add reviewer --file ./reviewer.md
+    commandmate roles default codex --repo . --role reviewer
+
+  Three different things:
+    roles edit       the role's text. Everything pointing at it follows, from its next start.
+    roles default    what a new start of a tool resolves to: one repository (--repo), or all
+                     that do not say otherwise. Schedules follow too.
+    set-role / send --role   one instance.
+  A role is fixed when the process starts. None of these touches a running session: stop it
+  (instances <wt> kill <id>) and send again.
+
+  <role> is an ID or a name; two candidates is exit 2 with both listed. Nothing is reserved:
+  --none, --no-role and --inherit are flags, so a role can be called none.
+  --repo is an ID, then a path (a value with "/" or starting with "."; a worktree of a
+  repository means that repository, so --repo . works inside one), then a name. See what is
+  registered with: commandmate roles defaults. Errors: unknown_repository,
+  repository_not_registered (a directory with no row), ambiguous_repository. A repository
+  with no setting for a tool reads stored: inherit, and effective says what it gets.
+  Tools: claude, codex, command-code, opencode, opencode-v2, copilot, antigravity.
+
+  send --role <role> / --no-role is a condition, not a switch: saved first, then a running
+  session gets the message only if it started with exactly that. Another role, or no record of
+  its start, is exit 32 with nothing typed, and the setting stays saved. An ad-hoc id needs
+  --register too: --register --role creates the instance and its role BEFORE sending, so the
+  first start has it, and repeating it replaces the setting and is a condition as above.
+  --register without a role registers after sending, and the message has gone out by then: a roster
+  that kept changing, or any other failure to register, is a warning and exit 0 (not exit 31). Do
+  not send it again; the warning has the command that registers it.
+  --auto-yes applied after the message (--model on a tool that arms after it, or a grant already on)
+  cannot take the send back: if it fails, that is a warning and exit 0, so do not send it again; the
+  warning has the command that enables it. Armed before the message, a failure is an error with
+  nothing sent.
+  --expect-role-generation <g> with --expect-role-fingerprint <f> | --expect-no-role pin a send
+  to what capture --json's roleLaunch said, saving nothing: a process replaced before the
+  first key gets nothing (exit 32). A send with a role or a pin that types nothing withdraws the
+  --auto-yes it armed, and leaves a grant already on as it was. --auto-yes with no role, pin or
+  --reply-to reads nothing first: it cannot tell a grant it armed from one already on, so a refused
+  send leaves it on, with the command that stops it. A server too old to name its grants (no
+  grantId) is not asked to withdraw one either: it stays on, with the same command.
+  send --new-conversation: OpenCode V1 continues the conversation it remembers, even under another
+  role, and stopping it does not forget it. Stop the session and send with this to start a new one.
+  Another tool, or a session running or starting at that check, is exit 2 with nothing sent.
+
+  Exit codes: 0 done; 1 server not running; 2 bad arguments, unknown or ambiguous role or
+  repository, a tool outside the feature; 31 a conflict, nothing changed (name_conflict,
+  name_changed, version_conflict, role_in_use, instance_exists, roster_changed; plain instances
+  add/remove/alias end in roster_changed too, and remove --kill may have stopped the session by
+  then, as it stops first and saves after); 32 nothing typed (send);
+  99 anything else. --json failures: { success: false, error, message, candidates?, references? }.
+  Full --json shapes: commandmate roles --help
 
 ### commandmate skill <subcommand>
   Manage official Agent Skills. Every subcommand is a thin client over the same
@@ -606,6 +691,9 @@ These commands enable coding agents (Claude Code, Codex, etc.) to orchestrate ot
   20  VERIFY_FAILED    - A verification gate failed (verify, wait --verify)
   21  NOT_STARTED      - Nothing to verify: no commits, no uncommitted changes
   30  NO_ACTIVE_SESSIONS - interrupt found no running session to interrupt
+  31  ROLE CONFLICT    - A role or roster conflict; nothing changed or sent (roles, instances, send).
+                         Plain instances add/remove/alias too. remove --kill may have stopped the session
+  32  ROLE NOT_SENT    - The role condition does not hold or its start was refused; nothing typed (send, ask)
   99  UNEXPECTED_ERROR - Unexpected error / resource not found / no verdict
   124 TIMEOUT          - Wait or verification timeout exceeded
 

package/dist/cli/index.d.ts

@@ -18,6 +18,10 @@
  * half of the same feature — what a delegation left standing — and `send`'s and
  * `ask`'s `--reply-to` are declared on their own commands inside
  * `buildProgram()` because those commands already exist there.
+ *
+ * Issue #4116 attaches `roles` here for the first reason: it leaves `buildProgram()`
+ * what its tests characterise. `send --role` and `instances set-role` are declared on
+ * their own commands, as `--reply-to` is.
  */
 export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG"}

package/dist/cli/index.js

@@ -19,6 +19,10 @@
  * half of the same feature — what a delegation left standing — and `send`'s and
  * `ask`'s `--reply-to` are declared on their own commands inside
  * `buildProgram()` because those commands already exist there.
+ *
+ * Issue #4116 attaches `roles` here for the first reason: it leaves `buildProgram()`
+ * what its tests characterise. `send --role` and `instances set-role` are declared on
+ * their own commands, as `--reply-to` is.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 const program_1 = require("./program");
@@ -26,6 +30,7 @@ const ask_1 = require("./commands/ask");
 const whoami_1 = require("./commands/whoami");
 const peers_1 = require("./commands/peers");
 const relays_1 = require("./commands/relays");
+const roles_1 = require("./commands/roles");
 const program = (0, program_1.buildProgram)();
 // Issue #2376: delegation between agent sessions.
 program.addCommand((0, ask_1.createAskCommand)());
@@ -33,5 +38,6 @@ program.addCommand((0, whoami_1.createWhoamiCommand)());
 program.addCommand((0, peers_1.createPeersCommand)());
 // Issue #2377: and the ledger the delegation leaves behind.
 program.addCommand((0, relays_1.createRelaysCommand)());
+program.addCommand((0, roles_1.createRolesCommand)());
 // Parse and execute
 program.parse();

package/dist/cli/types/api-responses.d.ts

@@ -145,6 +145,11 @@ export interface OpencodeSessionsResponse {
 }
 export interface WorktreeDetailResponse extends WorktreeItem {
     agentInstances: AgentInstance[];
+    /**
+     * Issue #4132: names this reading of the roster, for a write that replaces it. Absent
+     * from an older server. Pinned to the route by tests/integration/cli-response-types-4159.test.ts.
+     */
+    rosterRevision?: string;
 }
 /**
  * Mirrors: src/lib/polling/auto-yes-resolver.ts AutoYesSuppressionReason
@@ -1388,6 +1393,13 @@ export interface AutoYesSetResult {
      * not enabled and from an older server.
      */
     answerMode?: string;
+    /**
+     * Issue #4132: which enabling this is, on the same answers as `answerMode`. Handed back
+     * as `?expectedGrantId=` to turn off this grant and no other. Absent from an older server,
+     * which then cannot be asked for that (Issue #4159). Pinned to the route by
+     * tests/integration/cli-response-types-4159.test.ts.
+     */
+    grantId?: string;
     pollingStarted?: boolean;
     /**
      * Approvals that were already pending and got re-judged by this call
@@ -1597,6 +1609,20 @@ export interface ChatMessage {
     worktreeId: string;
     role: string;
     content: string;
+    /** Issue #4115/#4116: the process a send with a role condition reached. */
+    roleLaunch?: {
+        sessionGeneration: string;
+        injectionFingerprint: string | null;
+        saved: boolean;
+        stored: unknown;
+    };
+    /** Issue #4115/#4116: this tool's role replaces its default instructions. */
+    replacesDefaultInstructions?: boolean;
+    /** Issue #4115/#4116: OpenCode V1 continued a conversation that had another role. */
+    roleResume?: {
+        continued: boolean;
+        message: string;
+    };
     cliToolId?: string;
     createdAt?: string;
     /**
@@ -2347,6 +2373,8 @@ export interface TaskCreateResponse {
     task: TaskView;
     /** Contract preamble + goal, composed server-side; this is what gets sent. */
     message: string;
+    /** A running session with no evidence of its role, which the settings give one (Issue #4132). Absent otherwise and from older servers. */
+    roleWarning?: string;
 }
 /** Mirrors: src/app/api/worktrees/[id]/tasks/route.ts GET response. */
 export interface TaskListResponse {
@@ -2459,6 +2487,25 @@ export interface RelayView {
      * is queued or there is none.
      */
     deliveryHold?: RelayDeliveryHoldResponse | null;
+    /**
+     * Issue #4105: what the last delivery attempt of the current payload
+     * stopped for. Absent on an older server; null = no observation in this
+     * server process (NOT "deliverable"). Never part of `held` / `heldCount`.
+     */
+    lastDeliveryBlock?: RelayLastDeliveryBlockResponse | null;
+}
+/**
+ * Mirrors: `RelayLastDeliveryBlock` in src/lib/relay/types.ts (Issue #4105).
+ * Strings rather than unions, for the reason `RelayView.state` is one.
+ */
+export interface RelayLastDeliveryBlockResponse {
+    /** `prompt_waiting` | `generating` | `session_stopped` | `foreign_session`. */
+    reason: string;
+    /** The payload it was for: `reply` | `prompt` | `expired`. */
+    kind: string;
+    payloadId: string | null;
+    /** Epoch ms of the attempt that observed it. */
+    observedAt: number;
 }
 /**
  * Mirrors: `RelayDeliveryHold` in src/lib/relay/types.ts (Issue #4064).
@@ -2501,6 +2548,13 @@ export interface RelayListResponse {
      * delivery hold. Absent on an older server.
      */
     held?: RelayView[];
+    /**
+     * Issue #4193: closed relays in scope (by the requester) whose payload — the
+     * expiry notice, in practice — is still undelivered and whose last delivery
+     * attempt stopped (`lastDeliveryBlock` set). Not in `open` / `awaiting` and
+     * not in `counts` / `heldCount`. Absent on an older server.
+     */
+    closedBlocked?: RelayView[];
     counts: RelayCountsResponse;
     /**
      * Issue #4082: how many payloads in scope are held as `uncertain` now —