/** * Agent Operations documentation content * Issue #518: Embedded in CLI for npm package distribution * * 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 # Filter by branch name prefix\n commandmate ls --id # Filter by worktree id prefix\n\n Worktree ids are - 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. ' (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..\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..blockedByContract)\n off(restart) - off, because the server restarted while the grant was live\n (Issue #3730; --json: autoYesStopReasonByInstance.)\n - - not known: the server predates #2512, or this row is not idle and\n no instance explains its STATUS\n\n A trailing ' ()' 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 --json --instance '\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 \"\"\n Send a message to an agent (async). Starts session automatically if not running.\n\n Options:\n --instance Agent instance ID: or - (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 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 \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 Auto-yes duration: 1h-24h, whole hours, e.g. 1h, 3h, 8h\n (default: 1h)\n --stop-pattern

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 Deliver the target session's reply into 's composer\n when the turn ends: [@], 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 . 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 / ] , 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 A relay with antigravity at either end is refused by the tool policy instead\n (exit 33, nothing sent) unless the server declares API-key or enterprise use.\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 ' shows why it is held.\n\n### commandmate whoami [--json]\n Which worktree / instance is THIS session? Reads CM_WORKTREE_ID / CM_INSTANCE_ID /\n CM_CLI_TOOL (or the CM_AGENT_* launch-line variables), else the mcbd-... tmux\n session name. --json: worktreeId, instanceId, cliToolId, alias, source, sessionName,\n serverUrl (+ serverMismatch: true when this CLI is talking to a different server).\n Exit 3 (NOT_IN_SESSION) when the shell is not inside a CommandMate agent session.\n\n### commandmate peers [--json]\n The other agent sessions in THIS repository, your own row marked '(you)', each\n other row with a ready-to-run 'ask' line. --json: self, serverUrl, peers[]\n (worktreeId, instanceId, cliTool, alias, status, isSelf, ask). Exit 3\n (NOT_IN_SESSION) outside a session.\n\n### commandmate ask \"\" [--instance ]\n send + wait + read the reply, in one command. Name the target with --instance\n alone (--agent is for an instance the roster does not know).\n --timeout Maximum wait for the reply (default 1800)\n --json worktreeId, instanceId, cliToolId, source (history|none),\n reply (null when not collected), askId, attribution\n {state, reason, notified}, overlapped (only when true)\n --async Do not wait: register a relay, print its id, exit 0. The reply\n is typed into --reply-to's composer when the turn ends.\n --reply-to [@], or 'self' (default)\n --allow-relay-chain Permit a relay opened while answering a relayed message\n There is no --auto-yes on purpose. Wait ('ask') when the reply is your next step;\n 'ask --async' (or 'send --reply-to') when you can end your turn. Exit codes are\n wait's (0 / 10 / 21 / 124) plus:\n 11 UPSTREAM_FAULT the turn never ran (ask always uses failOnUpstreamFault);\n id=context-limit: 'instances kill ' and ask again;\n id=model-capacity: ask another instance or model\n 32 ROLE NOT_SENT the role condition does not hold; nothing was typed\n 33 TOOL POLICY DENIED the send or the --async relay to antigravity was refused by\n the tool policy (no usage declaration); nothing was typed.\n stderr line 1 'Error [TOOL_POLICY_DENIED]: ...'; --json has\n \"sent\": false and \"refusal\". Do not ask again: tell a person\n 2 a relay refusal (reason on stderr), a bad argument, or the target is on a prompt\n The reply is read by the ask's own id (Issue #4344): printed only when the\n server ties it to this ask (attribution.state \"matched\"; claude and codex).\n Otherwise exit 0, empty stdout, reply null and one 'reply not collected' line\n on stderr (unavailable: tool_unsupported / server_unsupported / slash_command;\n ambiguous; unmatched). The pane is never read for a reply.\n Full guide: 'commandmate docs --section delegation'.\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 --instance codex-2\n commandmate relays --json # owed / awaiting / open / counts\n commandmate relays --id # one relay, closed too: send= overlap= hold=\n commandmate relays cancel # 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= (the payload waiting for the requester's\n composer) and blocked=@