commandmate 0.22.1 → 0.23.0

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

@@ -5,6 +5,6 @@
  * 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- Use CM_PORT env var to connect to a different port (default: 3000)\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, DEFAULT)\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### 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    --duration <d>         Auto-yes duration: 1h, 3h, 8h (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\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  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### 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\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 immediately with prompt JSON on stdout\n    human  - Keeps blocking until human responds via browser UI\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. 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  --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 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 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\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 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\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### 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  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## 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  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\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, DEFAULT)\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### 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    --duration <d>         Auto-yes duration: 1h, 3h, 8h (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\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  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### 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\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 immediately with prompt JSON on stdout\n    human  - Keeps blocking until human responds via browser UI\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. 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  --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 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 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\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 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\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### 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  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## 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  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";
 //# sourceMappingURL=agent-operations.d.ts.map

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,+2jBA2VlC,CAAC;AAEF,eAAO,MAAM,wBAAwB,klJAmIpC,CAAC"}
+{"version":3,"file":"agent-operations.d.ts","sourceRoot":"","sources":["../../../src/cli/docs/agent-operations.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,sBAAsB,stkBA+VlC,CAAC;AAEF,eAAO,MAAM,wBAAwB,klJAmIpC,CAAC"}

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

@@ -17,7 +17,8 @@ These commands enable coding agents (Claude Code, Codex, etc.) to orchestrate ot
 
 - CommandMate server must be running: commandmate start --daemon
 - Target worktrees must be registered (visible in browser UI sidebar)
-- Use CM_PORT env var to connect to a different port (default: 3000)
+- Connection target is resolved as: exported CM_PORT > ~/.commandmate/.env CM_PORT > 3000
+  (CM_BIND and the CM_HTTPS_CERT + CM_HTTPS_KEY pair are honoured the same way)
 - Use CM_AUTH_TOKEN env var for authenticated servers
 
 ## Commands
@@ -352,6 +353,9 @@ These commands enable coding agents (Claude Code, Codex, etc.) to orchestrate ot
   Worktree not found:
     commandmate ls --quiet             # Check registered IDs
     commandmate sync                   # Sync new worktrees (e.g. after git worktree add)
+    commandmate status                 # Confirm 'ls' and 'status' report the same Port
+                                       # (with several servers running, an exported CM_PORT
+                                       #  points 'ls' at a different one)
 
   Authentication:
     CM_AUTH_TOKEN=your-token commandmate ls

package/dist/cli/utils/api-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/api-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,4CAA4C;AAC5C,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAK3C;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAErD;AAaD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,GAAG,SAAS,CASjF;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AA0BD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,OAAO,EACd,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,eAAe,GACxB,cAAc,CAyEhB;AAeD;;;GAGG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,KAAK,CAAC,CAAS;gBAEX,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE;IAa1D,OAAO,CAAC,UAAU;IAUlB;;;OAGG;IACG,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAuBtC;;;OAGG;IACG,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IA2BvD;;;;OAIG;IACG,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;CAyBzD;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;IACxD,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AA0BD;;GAEG;AACH,qBAAa,QAAS,SAAQ,KAAK;aAGf,QAAQ,EAAE,MAAM;aAChB,UAAU,CAAC,EAAE,MAAM;IACnC,gEAAgE;aAChD,OAAO,CAAC,EAAE,eAAe;gBAJzC,OAAO,EAAE,MAAM,EACC,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,YAAA;IACnC,gEAAgE;IAChD,OAAO,CAAC,EAAE,eAAe,YAAA;IAM3C,uEAAuE;IACvE,IAAI,OAAO,IAAI,MAAM,GAAG,SAAS,CAEhC;CACF;AAkBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EACnC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,EACvC,OAAO,EAAE,MAAM,GACd,CAAC,CAiBH;AAOD;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CASvF;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CASxE"}
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/api-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,4CAA4C;AAC5C,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAK3C;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAErD;AAaD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,GAAG,SAAS,CASjF;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AA0BD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,OAAO,EACd,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,eAAe,GACxB,cAAc,CAyEhB;AAeD;;;GAGG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,KAAK,CAAC,CAAS;gBAEX,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE;IAmB1D,OAAO,CAAC,UAAU;IAUlB;;;OAGG;IACG,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAuBtC;;;OAGG;IACG,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IA2BvD;;;;OAIG;IACG,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;CAyBzD;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;IACxD,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AA0BD;;GAEG;AACH,qBAAa,QAAS,SAAQ,KAAK;aAGf,QAAQ,EAAE,MAAM;aAChB,UAAU,CAAC,EAAE,MAAM;IACnC,gEAAgE;aAChD,OAAO,CAAC,EAAE,eAAe;gBAJzC,OAAO,EAAE,MAAM,EACC,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,YAAA;IACnC,gEAAgE;IAChD,OAAO,CAAC,EAAE,eAAe,YAAA;IAM3C,uEAAuE;IACvE,IAAI,OAAO,IAAI,MAAM,GAAG,SAAS,CAEhC;CACF;AAkBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EACnC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,EACvC,OAAO,EAAE,MAAM,GACd,CAAC,CAiBH;AAOD;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CASvF;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CASxE"}

package/dist/cli/utils/api-client.js

@@ -19,6 +19,7 @@ exports.fetchDaemonVersion = fetchDaemonVersion;
 exports.warnIfVersionSkew = warnIfVersionSkew;
 const types_1 = require("../types");
 const package_info_1 = require("./package-info");
+const server_url_1 = require("./server-url");
 /** Maximum stop-pattern length [SEC4-06] */
 exports.MAX_STOP_PATTERN_LENGTH = 500;
 /** Worktree ID validation pattern [SEC4-04] */
@@ -190,8 +191,14 @@ class ApiClient {
     baseUrl;
     token;
     constructor(options) {
-        const port = process.env.CM_PORT || '3000';
-        this.baseUrl = options?.baseUrl || `http://localhost:${port}`;
+        // Issue #1743: resolve through loadClientEnv() rather than `process.env.CM_PORT || '3000'`.
+        // Reading process.env alone ignored ~/.commandmate/.env, so with two servers running,
+        // `status` reported the .env port while every ApiClient-based subcommand (ls / send / wait
+        // / capture / …) silently talked to the default port 3000. loadClientEnv() layers .env
+        // *under* process.env — see its doc comment for why that order is the reverse of the one
+        // `status` uses. resolveServerEndpoint() then applies the same CM_BIND / CM_HTTPS_CERT +
+        // CM_HTTPS_KEY rules as `status`, which the old hardcoded `http://localhost:` ignored.
+        this.baseUrl = options?.baseUrl || (0, server_url_1.resolveServerEndpoint)((0, server_url_1.loadClientEnv)()).url;
         this.token = resolveAuthToken(options);
         // [SEC4-02] Warn about HTTP to non-localhost
         if (this.token && !this.baseUrl.startsWith('https://') && !isLocalhost(this.baseUrl)) {

package/dist/cli/utils/server-url.d.ts

@@ -35,4 +35,27 @@ export declare function resolveServerEndpoint(env: ServerEnv): ServerEndpoint;
  * @param envPath - A worktree .env layered over the main one; omit for the main server
  */
 export declare function loadEffectiveEnv(envPath?: string): NodeJS.ProcessEnv;
+/**
+ * Build the environment a *client* resolves its connection target from (Issue #1743).
+ *
+ * The layering is deliberately the mirror image of loadEffectiveEnv(), because the two
+ * answer different questions:
+ *
+ * - loadEffectiveEnv() answers "where is the server?". It reproduces what daemon.start()
+ *   hands the child (`{...process.env, ...parsed}`), so the .env the server actually booted
+ *   with outranks whatever this shell happens to export. That is what `status` reports.
+ * - loadClientEnv() answers "where should this invocation dial?". An exported CM_PORT is the
+ *   caller naming a target for this one command (`CM_PORT=3011 commandmate ls`, documented in
+ *   docs/user-guide/cli-operations-guide.md), so it has to outrank a file default. That is
+ *   the standard dotenv precedence, and reusing loadEffectiveEnv() here would silently break
+ *   that documented usage.
+ *
+ * What Issue #1743 required of both is that they consult ~/.commandmate/.env at all: ApiClient
+ * resolved from `process.env` alone, so with two servers running, every subcommand built on it
+ * (ls / send / wait / capture / …) dialled the default port 3000 while `status` correctly
+ * reported the .env port.
+ *
+ * Resolution order: `process.env` > `~/.commandmate/.env` > resolveServerEndpoint() defaults.
+ */
+export declare function loadClientEnv(): ServerEnv;
 //# sourceMappingURL=server-url.d.ts.map

package/dist/cli/utils/server-url.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-url.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/server-url.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AAErE,mDAAmD;AACnD,MAAM,WAAW,cAAc;IAC7B,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B,4DAA4D;IAC5D,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,SAAS,GAAG,cAAc,CAQpE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,UAAU,CAWpE"}
+{"version":3,"file":"server-url.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/server-url.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AAErE,mDAAmD;AACnD,MAAM,WAAW,cAAc;IAC7B,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B,4DAA4D;IAC5D,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,SAAS,GAAG,cAAc,CAQpE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,UAAU,CAWpE;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,IAAI,SAAS,CAUzC"}

package/dist/cli/utils/server-url.js

@@ -11,6 +11,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveServerEndpoint = resolveServerEndpoint;
 exports.loadEffectiveEnv = loadEffectiveEnv;
+exports.loadClientEnv = loadClientEnv;
 const dotenv_1 = require("dotenv");
 const env_setup_1 = require("./env-setup");
 /**
@@ -41,3 +42,35 @@ function loadEffectiveEnv(envPath) {
         : (0, dotenv_1.config)({ path: envPath }).parsed || {};
     return { ...process.env, ...mainParsed, ...ownParsed };
 }
+/**
+ * Build the environment a *client* resolves its connection target from (Issue #1743).
+ *
+ * The layering is deliberately the mirror image of loadEffectiveEnv(), because the two
+ * answer different questions:
+ *
+ * - loadEffectiveEnv() answers "where is the server?". It reproduces what daemon.start()
+ *   hands the child (`{...process.env, ...parsed}`), so the .env the server actually booted
+ *   with outranks whatever this shell happens to export. That is what `status` reports.
+ * - loadClientEnv() answers "where should this invocation dial?". An exported CM_PORT is the
+ *   caller naming a target for this one command (`CM_PORT=3011 commandmate ls`, documented in
+ *   docs/user-guide/cli-operations-guide.md), so it has to outrank a file default. That is
+ *   the standard dotenv precedence, and reusing loadEffectiveEnv() here would silently break
+ *   that documented usage.
+ *
+ * What Issue #1743 required of both is that they consult ~/.commandmate/.env at all: ApiClient
+ * resolved from `process.env` alone, so with two servers running, every subcommand built on it
+ * (ls / send / wait / capture / …) dialled the default port 3000 while `status` correctly
+ * reported the .env port.
+ *
+ * Resolution order: `process.env` > `~/.commandmate/.env` > resolveServerEndpoint() defaults.
+ */
+function loadClientEnv() {
+    // quiet: dotenv's "injecting env" banner is written to stdout, where it would corrupt
+    //   machine-readable output such as `commandmate ls --json`.
+    // processEnv: this is a read-only lookup. Left to its default, dotenv would populate
+    //   process.env with every key the file defines, turning file values into "exported"
+    //   ones for the rest of the process — the precedence this function exists to avoid.
+    const parsed = (0, dotenv_1.config)({ path: (0, env_setup_1.getEnvPath)(), processEnv: {}, quiet: true }).parsed ?? {};
+    // process.env last: an explicitly exported variable wins over the file (see above)
+    return { ...parsed, ...process.env };
+}

package/dist/server/src/config/log-config.js

@@ -18,6 +18,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getLogDir = getLogDir;
 const path_1 = __importDefault(require("path"));
 const env_1 = require("../lib/env");
+const safe_directory_1 = require("./safe-directory");
 /**
  * Get the log directory path.
  *
@@ -25,6 +26,13 @@ const env_1 = require("../lib/env");
  * 1. CM_LOG_DIR environment variable (with MCBD_LOG_DIR fallback via getEnvByKey)
  * 2. Default: `${process.cwd()}/data/logs`
  *
+ * Issue #1774: a CM_LOG_DIR inside `/proc`, `/sys` or `/dev` falls back to the
+ * default with a warning. `log-manager.ensureLogDirectory()` calls
+ * `fs.mkdir(dir, {recursive:true})` on the result, and on Linux that promise
+ * never settles for such a path — it holds a libuv threadpool thread for the
+ * life of the process instead. Throwing is not an option here: the log
+ * directory is where the complaint would have to go.
+ *
  * @returns Absolute path to the log directory
  *
  * @example
@@ -37,5 +45,6 @@ const env_1 = require("../lib/env");
  * ```
  */
 function getLogDir() {
-    return (0, env_1.getEnvByKey)('CM_LOG_DIR') || path_1.default.join(process.cwd(), 'data', 'logs');
+    const fallback = path_1.default.join(process.cwd(), 'data', 'logs');
+    return (0, safe_directory_1.resolveSafeDirectory)((0, env_1.getEnvByKey)('CM_LOG_DIR'), fallback, 'CM_LOG_DIR');
 }

package/dist/server/src/config/safe-directory.js

@@ -0,0 +1,103 @@
+"use strict";
+/**
+ * The one place a configured directory becomes a directory this process is
+ * willing to create (Issue #1774).
+ *
+ * ## What this is defending against
+ *
+ * Pointing a configured path at `/proc`, `/sys` or `/dev` does not make
+ * CommandMate fail — it makes it **stop**. procfs answers a `mkdir` for a child
+ * that cannot exist with ENOENT rather than EPERM, and Node's recursive mkdir
+ * reads ENOENT as "the parent is missing", creates the parent, and retries; the
+ * parent is created with EEXIST, so one level is enough to loop. Measured in a
+ * container: `mkdirSync('/proc/x/y', {recursive:true})` had not returned after
+ * 25s at 100.4% CPU, and `fs.promises.mkdir` on the same path never settled and
+ * held a libuv threadpool thread (there are four) forever. The synchronous form
+ * stops the event loop outright, which is also why the `try/catch` these call
+ * sites already have does nothing: control never reaches it. There is no error
+ * log, no OOM and no timeout — the process simply goes quiet. PR #1773's CI job
+ * ran 5h31m that way.
+ *
+ * On macOS none of the three paths exist, so the same call throws instantly and
+ * everything looks fine. The failure is Linux- and container-only.
+ *
+ * ## Why a resolver rather than a check at each mkdir
+ *
+ * Five settings reach a recursive mkdir this way (`CM_AGENT_HOOKS_DIR`,
+ * `CM_LOG_DIR`, `CODEX_HOME`, `COPILOT_HOME`, `CM_OPENCODE_PORT_FILE`), and
+ * three of the five arrived with Phase 4 (#1760 / #1761 / #1763) as copies of
+ * the first. Guarding the mkdir sites individually invites a sixth copy; putting
+ * the guard on the *resolution* of the value means a new tool is protected by
+ * calling the resolver its siblings already call.
+ *
+ * ## Why it never throws
+ *
+ * A bad log directory must not take out logging, and hook injection is
+ * fail-open by design (`hook-settings-generator.buildClaudeLaunchCommand`).
+ * Falling back to the built-in default and saying so keeps a misconfigured
+ * server running with its events intact.
+ *
+ * @module config/safe-directory
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resetSafeDirectoryWarnings = resetSafeDirectoryWarnings;
+exports.resolveSafeDirectory = resolveSafeDirectory;
+const logger_1 = require("../lib/logger");
+const system_directories_1 = require("./system-directories");
+const logger = (0, logger_1.createLogger)('safe-directory');
+/**
+ * Settings already warned about, so a rejection is reported once rather than on
+ * every call.
+ *
+ * `getLogDir()` runs on the path of every log write; an unconditional warning
+ * would turn one misconfigured variable into a log flood, in the log directory
+ * that is already not the one the operator asked for.
+ */
+const warnedRejections = new Set();
+/** Forget which rejections have been warned about. For tests. */
+function resetSafeDirectoryWarnings() {
+    warnedRejections.clear();
+}
+/**
+ * The directory to actually use for `candidate`, which is `candidate` unless
+ * using it would hang the process.
+ *
+ * Pure with respect to the filesystem in the sense that matters here: it reads
+ * (symlink resolution) but creates nothing, so it is safe to call — and to test
+ * — with a path that no `mkdir` could survive.
+ *
+ * A *file* path is a valid candidate. The check is prefix-based, so a file
+ * inside a virtual filesystem is rejected exactly as its directory would be;
+ * `CM_OPENCODE_PORT_FILE` relies on that.
+ *
+ * @param candidate - The configured path. Empty or undefined means "unset"
+ * @param fallback - The built-in default to use when the candidate is refused
+ * @param source - What supplied the candidate, e.g. `'CM_LOG_DIR'`. Appears in
+ *   the warning, because the operator's next question is which setting to fix
+ * @returns `candidate`, or `fallback` when the candidate is inside `/proc`,
+ *   `/sys` or `/dev`
+ *
+ * @example
+ * ```typescript
+ * const fallback = join(homedir(), '.commandmate', 'hooks');
+ * return resolveSafeDirectory(process.env.CM_AGENT_HOOKS_DIR, fallback, 'CM_AGENT_HOOKS_DIR');
+ * ```
+ */
+function resolveSafeDirectory(candidate, fallback, source) {
+    if (!candidate)
+        return fallback;
+    if (!(0, system_directories_1.isVirtualFilesystemPath)(candidate))
+        return candidate;
+    const key = `${source}|${candidate}`;
+    if (!warnedRejections.has(key)) {
+        warnedRejections.add(key);
+        logger.warn('virtual-filesystem-path-rejected', {
+            source,
+            candidate,
+            fallback,
+            reason: 'A recursive mkdir under /proc, /sys or /dev never returns on Linux; ' +
+                'the built-in default is used instead (Issue #1774).',
+        });
+    }
+    return fallback;
+}

package/dist/server/src/config/system-directories.js

@@ -13,9 +13,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SYSTEM_DIRECTORIES = void 0;
+exports.VIRTUAL_FILESYSTEM_ROOTS = exports.SYSTEM_DIRECTORIES = void 0;
 exports.isPathWithin = isPathWithin;
 exports.isSystemDirectory = isSystemDirectory;
+exports.isVirtualFilesystemPath = isVirtualFilesystemPath;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 /**
@@ -36,6 +37,35 @@ exports.SYSTEM_DIRECTORIES = [
     '/sys',
     '/proc',
 ];
+/**
+ * The subset of {@link SYSTEM_DIRECTORIES} that is not a filesystem at all.
+ *
+ * Issue #1774: these three are kernel-backed namespaces, and their `mkdir`
+ * error codes are not the ones `fs` callers assume. procfs answers a `mkdir`
+ * for a child that cannot exist with **ENOENT rather than EPERM**, and Node's
+ * recursive mkdir reads ENOENT as "the parent is missing", so it creates the
+ * parent and retries — forever. Measured in a container: `mkdirSync('/proc/x/y',
+ * {recursive:true})` had not returned after 25s at 100.4% CPU; the promise from
+ * `fs.promises.mkdir` never settled and held a libuv threadpool thread (4 by
+ * default) for the life of the process. Neither logs anything, and the
+ * synchronous form stops the event loop, so a surrounding `try/catch` is never
+ * reached. On macOS the paths do not exist and the call throws at once, which
+ * is why this is invisible outside Linux and containers.
+ *
+ * Kept as a named subset rather than reusing the whole list because the two
+ * lists answer different questions. {@link isSystemDirectory} answers "may a
+ * database live here", and rejects `/tmp` and `/var` for that; but `/tmp` and
+ * `/var/log` are ordinary writable directories that a log or hook directory may
+ * legitimately be pointed at — `os.tmpdir()` is *inside* one on both platforms
+ * (`/tmp` on Linux, `/var/folders/…` on macOS), which is where every isolated
+ * test directory in this repository lives. Rejecting those would not prevent a
+ * hang; it would redirect isolated test runs and container deployments back
+ * onto the real `~/.codex` and `~/.commandmate`.
+ *
+ * `SYSTEM_DIRECTORIES` remains the superset — `tests/unit/config/system-directories.test.ts`
+ * pins that, so the two cannot drift apart.
+ */
+exports.VIRTUAL_FILESYSTEM_ROOTS = ['/proc', '/sys', '/dev'];
 /**
  * POSIX separator. SYSTEM_DIRECTORIES are POSIX absolute paths and this guard
  * protects POSIX platforms, so the boundary is always '/' rather than path.sep.
@@ -66,13 +96,14 @@ function isPathWithin(target, dir) {
  *
  * Mount layout does not change while the process runs, so this is computed once.
  */
-let resolvedSystemDirectoriesCache = null;
-function getSystemDirectoryCandidates() {
-    if (resolvedSystemDirectoriesCache !== null) {
-        return resolvedSystemDirectoriesCache;
+const resolvedDirectoryCandidatesCache = new Map();
+function getDirectoryCandidates(directories) {
+    const cached = resolvedDirectoryCandidatesCache.get(directories);
+    if (cached !== undefined) {
+        return cached;
     }
     const candidates = new Set();
-    for (const dir of exports.SYSTEM_DIRECTORIES) {
+    for (const dir of directories) {
         // Always keep the literal form: it must stay enforced even when the
         // directory does not exist on this platform (e.g. /proc and /sys on macOS).
         candidates.add(dir);
@@ -83,8 +114,9 @@ function getSystemDirectoryCandidates() {
             // Not present on this platform; the literal form still applies.
         }
     }
-    resolvedSystemDirectoriesCache = Array.from(candidates);
-    return resolvedSystemDirectoriesCache;
+    const resolved = Array.from(candidates);
+    resolvedDirectoryCandidatesCache.set(directories, resolved);
+    return resolved;
 }
 /**
  * Resolve symlinks in an absolute path, tolerating components that do not exist.
@@ -140,7 +172,40 @@ function resolvePhysicalPath(absolutePath) {
  * @returns true if the path is within a system directory
  */
 function isSystemDirectory(inputPath) {
+    return matchesAnyDirectory(inputPath, exports.SYSTEM_DIRECTORIES);
+}
+/**
+ * Check if a path is inside a virtual filesystem ({@link VIRTUAL_FILESYSTEM_ROOTS}).
+ *
+ * Issue #1774: the question `isSystemDirectory` cannot answer for a directory
+ * that is about to be created. A recursive `mkdir` under one of these roots does
+ * not fail — it hangs the process, unrecoverably and without a log line — so
+ * every path that reaches a `mkdir(…, {recursive:true})` has to be filtered
+ * through this first. See {@link VIRTUAL_FILESYSTEM_ROOTS} for the measurements
+ * and for why this is a subset of `SYSTEM_DIRECTORIES` rather than all of it.
+ *
+ * Matching is the same as `isSystemDirectory`: lexical *and* physical form, so a
+ * symlink that points into `/proc` is rejected along with a literal `/proc/…`.
+ * That is the direction that matters — a missed one hangs the server.
+ *
+ * Reads the filesystem (symlink resolution); it never creates anything, and
+ * `realpath` on a procfs path returns ENOENT immediately rather than spinning.
+ *
+ * @param inputPath - The path to check (relative paths are resolved against cwd)
+ * @returns true if a recursive mkdir for this path could spin
+ */
+function isVirtualFilesystemPath(inputPath) {
+    return matchesAnyDirectory(inputPath, exports.VIRTUAL_FILESYSTEM_ROOTS);
+}
+/**
+ * Shared matcher for {@link isSystemDirectory} and {@link isVirtualFilesystemPath}.
+ *
+ * @param inputPath - The path to check
+ * @param directories - Absolute directory prefixes to test against
+ * @returns true if either the lexical or the physical form lands in one of them
+ */
+function matchesAnyDirectory(inputPath, directories) {
     const lexicalPath = path_1.default.resolve(inputPath);
     const physicalPath = resolvePhysicalPath(lexicalPath);
-    return getSystemDirectoryCandidates().some((dir) => isPathWithin(lexicalPath, dir) || isPathWithin(physicalPath, dir));
+    return getDirectoryCandidates(directories).some((dir) => isPathWithin(lexicalPath, dir) || isPathWithin(physicalPath, dir));
 }

package/dist/server/src/lib/cli-tools/antigravity.js

@@ -16,6 +16,8 @@ const tmux_1 = require("../tmux/tmux");
 const submit_verified_sender_1 = require("./submit-verified-sender");
 const tmux_capture_cache_1 = require("../tmux/tmux-capture-cache");
 const cli_patterns_1 = require("../detection/cli-patterns");
+const sources_1 = require("../../lib/hooks/sources");
+const agent_session_lifecycle_1 = require("../../lib/session/agent-session-lifecycle");
 const logger_1 = require("../../lib/logger");
 const cli_tool_timing_config_1 = require("../../config/cli-tool-timing-config");
 const logger = (0, logger_1.createLogger)('cli-tools/antigravity');
@@ -116,6 +118,11 @@ class AntigravityTool extends base_1.BaseCLITool {
             logger.info('antigravity-session-exists');
             return;
         }
+        // Issue #1762: fence this instance's structured events off from the process
+        // that used to hold the same (worktree, tool, instance) key. Creation path
+        // only — the reuse branch above has already returned — and before the pane
+        // exists. Bumped even if the launch below then fails.
+        (0, agent_session_lifecycle_1.beginAgentSession)({ worktreeId, cliToolId: sources_1.ANTIGRAVITY_CLI_TOOL_ID, instanceId });
         try {
             // Create tmux session with large history buffer for agy output
             // (agy is inline-rendered and retains scrollback, like Codex)
@@ -127,8 +134,18 @@ class AntigravityTool extends base_1.BaseCLITool {
             });
             // Wait a moment for the session to be created
             await new Promise((resolve) => setTimeout(resolve, cli_tool_timing_config_1.TUI_SESSION_CREATE_WAIT_MS));
-            // Start agy in interactive mode, optionally pinned to a model
-            const launchCommand = model ? `agy --model ${shellSingleQuote(model)}` : 'agy';
+            // Start agy in interactive mode, optionally pinned to a model.
+            //
+            // Issue #1762: `prepareAgentLaunch` merges CommandMate's named hook into
+            // `~/.gemini/config/hooks.json` — agy's single global config, shared with
+            // gemini's tree and with whatever the user has in it — and prefixes
+            // `CM_HOOK_URL`. That variable is the *only* correlation channel agy has:
+            // its payloads carry no `cwd`, its hooks run in `~/.gemini/config`, and
+            // one file serves every worktree on the machine. `--model` is appended
+            // after, so the env prefix stays in front of the command.
+            // `CM_AGENT_HOOKS_INJECT=0` returns bare `agy`, unchanged from before.
+            const base = (0, agent_session_lifecycle_1.prepareAgentLaunch)({ worktreeId, cliToolId: sources_1.ANTIGRAVITY_CLI_TOOL_ID, instanceId }, this.command).command;
+            const launchCommand = model ? `${base} --model ${shellSingleQuote(model)}` : base;
             await (0, tmux_1.sendKeys)(sessionName, launchCommand, true);
             // Wait for agy to initialize
             await new Promise((resolve) => setTimeout(resolve, ANTIGRAVITY_INIT_WAIT_MS));