@phnx-labs/agents-cli 1.20.49 → 1.20.51

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 ## Unreleased
 
+## 1.20.51
+
+- **Fix: `agents run --lease` bootstraps a fresh crabbox image and no longer leaks the box after the run.** Three failures compounded on a stock Hetzner lease (Ubuntu 24.04, no node preinstalled): (1) the bootstrap's `npm install -g @phnx-labs/agents-cli` ran with no node/npm on the box and swallowed the failure with `|| true`, so every run died deep in the script with `agents: command not found` (exit 127) and no hint why; (2) even with the CLI installed, a fresh install refuses `agents run` with "agents-cli is not set up" until `agents setup` has run; (3) teardown called `crabbox stop --id <slug>`, but crabbox's `stop` takes a positional target (unlike `status`/`run`/`ssh`) and died with `flag provided but not defined: -id` — silently, because `crabboxStop` is best-effort — so every one-shot lease box was **kept, billed, and left carrying the run's working data** until someone noticed (`Box … kept` instead of destroyed). The bootstrap now: exports `~/.local/bin` onto PATH, installs node user-level from the official `latest-v22.x` tarball when missing (arch-aware, satisfies `engines.node >=22.5.0`, no sudo needed), points the npm prefix at `~/.local`, fails loud with exit 96 and a diagnostic when the CLI still isn't runnable, and runs `agents setup` behind the same `[ ! -d ~/.agents/.system ]` first-run guard the hosts bootstrap uses; `crabboxStop` passes the slug positionally. Verified live on a fresh Hetzner cpx62 by the run's own progression across builds: the pre-fix lease exited 127 (`agents: command not found`) with `Box … kept`; after the node/npm fix it reached `agents-cli is not set up`; after the setup fix it reached the agent's login check (`Not logged in`); and every post-fix run ends with `Box <slug> destroyed.` instead of leaking. Source: `apps/cli/src/lib/crabbox/lease.ts` (`ENSURE_AGENTS_CLI`, `buildBootstrapScript`), `apps/cli/src/lib/crabbox/cli.ts` (`crabboxStop`). Known follow-up: leasing a **Claude** runtime from a Mac whose Claude Code credential lives in the login Keychain (the default install, and any agents-cli managed home — service name is hash-suffixed) still lands "Not logged in" on the box, because the picker copies `~/.claude.json` (config/state) but not the OAuth token, and extracting the token from the Keychain needs an interactive ACL approval; tracked separately.
+- **`agents repo pull user <git-url>` now git-backs a plain `~/.agents` instead of silently skipping it — fixing config sync on Windows/fresh machines.** Setup only ever git-clones the *system* repo (`~/.agents/.system/`); the user repo is created as a bare directory (`state.ts ensureAgentsDir`), so `~/.agents` is git-backed only where it was cloned by hand as a dotfiles step. On a box where that never happened (a fresh install, or Windows), `agents repo pull` just printed `user: not a git repo, skipping` and the machine silently fell out of config sync — no `rules/`, no `agents sync` of shared resources. Now, passing your config remote once — `agents repo pull user git@github.com:you/.agents.git` — **adopts** the existing directory in place: it clones your remote and moves the `.git` in without deleting anything, materializes the tracked resources it was missing, and **backs up any locally-modified tracked file** (e.g. a machine-specific `agents.yaml`) to a sibling `~/.agents.pre-adopt-backup/` before overwriting it. Untracked runtime state (`.cache/`, `.history/`, `.system/` — all gitignored) is never touched. Every subsequent `agents repo pull` / `agents sync` is plain (the remote is now `origin`). No new command; the URL is only needed the first time. SSH transport is preserved (a `git@…` URL clones over SSH, not a rewritten https that would hang on a private-repo credential prompt), and git never prompts (`GIT_TERMINAL_PROMPT=0`). Source: `apps/cli/src/lib/git.ts` (`adoptRepo`), `apps/cli/src/commands/repo.ts`.
+- **`agents run` now warns when a headless run leaves committed-but-unpushed work, instead of stranding it silently.** A headless `agents run` in a writable mode (`edit`/`skip`/`auto`) could end with the agent having committed on a branch but never pushed it — the run's exit path did no git work, so those commits sat invisible in a worktree until someone audited the box (exactly how a batch dispatch loop can quietly lose a verified fix). After a non-interactive, writable run the CLI now inspects the cwd for commits on the current branch that haven't reached any remote (`git log HEAD --not --remotes`, correct even when no upstream is set — work already on an `origin/*` ref is not flagged) and prints a loud stderr warning naming the branch, the unpushed commits, and the exact `git push` / `gh pr create` commands. Advisory only: it never pushes, never mutates the repo, and never throws (a 5s git timeout plus full error-swallowing guarantee it can't delay or break the run's exit). The check is wired into every headless exit path — single run, `--loop`, `--acp`, `--resume-checkpoint`, and the crash/catch path — and gated by `shouldWarnUnpushed(mode, interactive)` so it stays silent for interactive runs (the human sees their shell) and read-only `plan` mode. Source: `apps/cli/src/lib/warn-unpushed.ts`, `apps/cli/src/commands/exec.ts`. (#868)
+- **Codex mode flags now match what the mode names promise — only `--mode skip` is yolo.** `--mode edit` used to append `--dangerously-bypass-approvals-and-sandbox` (Codex's `--yolo`) alongside `--sandbox workspace-write`, and the bypass flag wins — so "edit" silently ran Codex with **no sandbox and no approvals**, verified against codex 0.142.5's own session banner (`sandbox: danger-full-access`). And `--mode plan` mapped to `workspace-write` (writable!) because the template predated Codex's `read-only` sandbox. Now: `plan` → `--sandbox read-only`, `edit` → `--sandbox workspace-write -c sandbox_workspace_write.network_access=true` (sandboxed writes, network on so git/gh/installs keep working, no approval bypass), `skip` → `--dangerously-bypass-approvals-and-sandbox` (unchanged — skip IS the gnarly mode, equivalent to `codex --yolo`). Same fix in routine jobs (`runner.ts`) and in headless `codex exec resume`, which used to get the bypass for ANY non-plan resume — it now maps plan/edit through `-c sandbox_mode=…` and reserves the bypass for skip; interactive `codex resume` now carries the mode's sandbox flags instead of none. Verified live per mode against codex 0.142.5 session banners: skip = `approval: never / sandbox: danger-full-access`, edit = `sandbox: workspace-write (network access enabled)`, plan = `sandbox: read-only`. Source: `apps/cli/src/lib/exec.ts` (`AGENT_COMMANDS.codex`, resume block), `apps/cli/src/lib/runner.ts` (`buildJobCommand`).
+- **`--add-dir` is now forwarded to Codex (it was silently dropped).** `agents teams` passes `--add-dir ~/.agents` so Codex teammates can run `agents teams add`, but `buildExecCommand` emitted `--add-dir` for Claude only — the grant never reached Codex, masked until now by edit mode's accidental sandbox bypass. Codex takes `--add-dir` natively (widens the workspace-write sandbox); it is now forwarded for fresh runs and skipped on resume (`codex exec resume` rejects it). Source: `apps/cli/src/lib/exec.ts`.
+- **Fix: the documented `agents run <agent> [prompt] -- <native flags>` passthrough works again.** commander ≥13 rejects excess operands by default, so any post-`--` token (e.g. `agents run codex -- --yolo`) died with `too many arguments` before the run started. The run command now allows excess operands, re-derives the `--` boundary from argv (a post-`--` token can never be mis-parsed as the prompt — `agents run codex -- --yolo` launches the TUI with `--yolo`, it doesn't headless-run the "prompt" `--yolo`), and still errors, with a hint to quote the prompt, on excess operands NOT behind `--`. Verified live: `agents run codex "…" -- --yolo` forwards `--yolo` and codex reports `sandbox: danger-full-access`. Source: `apps/cli/src/commands/exec.ts`.
+
+- **Fix: grok launch shims resolve the binary from the versioned home before the global `~/.grok/downloads`, so a pinned grok that installed into the versioned home no longer dies with "grok@<version> not installed."** Grok ships a native binary (not an npm package), and it lands in the versioned home's `.grok/downloads` whenever the installer runs with `GROK_HOME` set — via the shim, a correct `agents add grok`, or a grok self-update from within the shim. Both generated shims (the dispatcher in `generateShimScript` and the `grok@<version>` versioned alias in `generateVersionedAliasScript`) checked only `$HOME/.grok/downloads`, which was often empty, so they fell through to the "not installed" error even though the binary existed in the versioned home. `getBinaryPath` already checked the versioned home first, so `agents view` and the shims disagreed. Both shim blocks now check `$VERSION_DIR/home/.grok/downloads` first and fall back to the global `$HOME/.grok/downloads` for pre-fix installs, then the existing adopted-launcher/PATH last resort. Bumps `SHIM_SCHEMA_VERSION` 25→26 and `VERSIONED_ALIAS_SCHEMA_VERSION` 12→13 so existing on-disk grok shims regenerate. Supersedes the pre-monorepo #830. Source: `apps/cli/src/lib/shims.ts` (`generateShimScript` grok dispatcher block, `generateVersionedAliasScript` `binaryResolution`).
+- **Fix: `browser stop --host <windows>` tree-kills the remote browser — relaunches never wedge on a stale `SingletonLock`.** The kill script used `Stop-Process` on the CDP port owner only; orphaned Chromium child processes survived, kept the profile's `SingletonLock` held, and the next `browser start --host` against the same profile exited immediately as a second instance. The script now uses `taskkill /PID <owner> /T /F` to take down the whole process tree. Source: `apps/cli/src/lib/browser/drivers/ssh.ts` (`buildWindowsKillScript`). (GitHub #561)
+- **Fix: `agents browser start --host <windows>` actually serves CDP now — the remote browser launches in the user's interactive session instead of session 0.** The Windows launch used WMI `Win32_Process.Create` (chosen so the browser outlives the ssh session), but a WMI-created process lands in session 0, where Edge binds the debugging port yet its DevTools server never initializes — every `/json/version` probe hung forever and `DevToolsActivePort` was never written, so `browser start --host` failed with a connection error on every attempt. The launch is now a one-shot scheduled task registered and started by the logged-on user: it survives ssh disconnect the same way, runs in the interactive session where DevTools comes up normally, and is unregistered immediately after start. The launch args also gained the same automation-modal suppressors the local launcher has (`--no-first-run --no-default-browser-check --hide-crash-restore-bubble --disable-session-crashed-bubble`) — without them a relaunch against a previously hard-killed profile triggers session-restore churn that closes the CDP page target mid-command. Verified live against win-mini (Edg/150). Source: `apps/cli/src/lib/browser/drivers/ssh.ts` (`buildWindowsLaunchScript`). (GitHub #561)
+- **Fix: remote CDP no longer dies on large payloads — screenshots of content-rich pages over `browser --host` work.** The CDP client rode the platform (undici) WebSocket, which enforces a non-configurable max decompressed message size; a `Page.captureScreenshot` response for a content-rich page blew past it and the socket closed with 1006 ("Max decompressed message size exceeded") while the command was pending, surfacing as "CDP connection closed". The websocket transport now uses the `ws` client (no permessage-deflate offer by default, explicit 256MB `maxPayload`); the local pipe transport is unchanged. Source: `apps/cli/src/lib/browser/cdp.ts`. (GitHub #561)
+- **`agents sessions <id> --json` now exposes the ExitPlanMode plan markdown as a top-level field, and the shape changed from a bare event array to `{ session, events }`.** The session-state engine already detected plan-review (`awaitingReason: 'plan_review'`) off a trailing `ExitPlanMode` tool call, but the plan markdown itself was dropped on the floor — forcing every consumer that wanted it (the Factory NEEDS-YOU panel via `parsePlanFromClaudeJsonl`, external dashboards) to re-open the raw JSONL and scan for the same tool call. That "extension re-implements the session engine" gap now closes at the source: the state engine surfaces `state.plan` alongside `awaitingReason`, the Claude scanner captures the plan text at scan time and persists it to `sessions.db` (schema v11, additive, rescan-on-migrate), it's exposed as `plan` on `SessionMeta` in every `agents sessions --json` row, and `agents sessions <id> --json` now emits `{ session: SessionMeta, events: SessionEvent[] }` so the plan is one top-level `output.session.plan` read instead of a needle-in-haystack scan. Verified live against a real Claude session with an ExitPlanMode event: `agents sessions 74464df7 --json` prints the plan markdown at `.session.plan`. Source: `apps/cli/src/lib/session/{state,discover,db,render,types}.ts`, `apps/cli/src/lib/session/active.ts`, `apps/cli/src/commands/sessions.ts`. (issue #743 / RUSH-1505)
+- **`agents computer` Windows parity: scoped screenshots, `get-text --max-chars`, `status`/`reload --host`, and honest `--background`/`--require-frontmost` handling (#548).** Four params the CLI already sent were silently ignored by the Windows daemon. (1) **Screenshots are now pid-scoped like macOS** — `screenshot --list` enumerates the target pid's top-level windows (`window_id` is the Win32 HWND, the same id `raise --window-id` takes), the default capture crops to the pid's largest on-screen window, `--window-id` shoots one window, and `--display` captures the display the app is on; previously every capture was the whole virtual desktop. Verified live on win-mini: window capture 2097x984/28KB vs full display 2560x1440/380KB. (2) **`get-text --max-chars` is honored** (default stays 20k, ceiling 200k like macOS) — `--max-chars 100` now returns exactly 100 chars. (3) **`status --host <device>` and `reload --host <device>`** — status reports the recorded tunnel plus a live daemon probe (previously it misreported macOS-local install state for a remote Windows daemon); reload restarts the daemon's scheduled task (the way to pick up a freshly pushed exe) and confirms it answers through the tunnel. (4) **`--require-frontmost` is enforced on Windows** — `SendInput` lands in the *focused* window, so `type-text`/`key` now report `frontmost` (feeding the existing CLI warning) and the flag hard-fails with `not_frontmost` when the target isn't foreground; **`--background` is rejected** with `action_unsupported` instead of silently no-oping (macOS postToPid delivery has no Win32 analogue — element-mode clicks via UIA patterns are the focus-safe path). Source: `native/computer-win/{Screenshot,Automation}.cs`, `apps/cli/src/commands/computer.ts`, `apps/cli/docs/computer.md`.
+- **The `never` prompt-policy is now live — the signed keychain helper was rebuilt, re-notarized, and re-pinned.** `agents secrets create --policy never --i-understand` stores bundle values with no biometry ACL (`kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly`, device-local, non-synchronizable) so headless automation can read them with zero Touch ID prompts. The Swift `set-no-acl` path shipped in #682 but the pinned helper binary predated it, so the policy failed against the shipped helper; the helper is rebuilt from current source, notarized (Apple submission `a2373c91-7fc2-4894-a801-b37c111597aa`, status Accepted, stapled, Gatekeeper `Notarized Developer ID`), and `scripts/Agents CLI.app.sha256` re-pinned to the new binary. (GitHub #421)
+- **Consolidated ~30 copy-pasted terminal-formatting helpers into one shared `apps/cli/src/lib/format.ts`, fixing three user-visible drifts at the source.** `die`, `truncate`, `relTime`, `humanDuration`, `visibleWidth`, `padRight`/`padVisible`, `isJsonMode`, `readStdinSync`, and `termLink` had drifted into per-command copies with different behavior; every consumer now imports the single canonical version. Three normalizations are user-visible: (1) the truncation ellipsis is now the single glyph `…` everywhere — `agents cloud` task lists, `agents sessions` overflow, and session prompt/tool summaries previously showed ASCII `...` or a bare `.`; (2) `agents cloud` relative timestamps switch from the long "5 minutes ago" form to the compact "5m ago" form already used by `agents teams`; (3) the `agents teams` picker duration cell gains a space ("2h5m" → "2h 5m") to match the sessions/browser pickers. It also fixes a latent bug: `agents repo`'s divergence-table column alignment used a `visibleWidth` regex missing its `\x1b` escape, so ANSI-colored cells were mis-measured and columns could misalign — the canonical `visibleWidth` strips the full SGR sequence. `lib/events.ts`'s `truncate` (a distinct nullable, exported helper that truncates persisted event payloads) and the domain-specific `statusColor` copies (different status vocabularies with conflicting color assignments) are deliberately left in place. Internal refactor plus the noted string normalizations; no other behavior change. Source: `apps/cli/src/lib/format.ts` and consumers across `apps/cli/src/commands/` and `apps/cli/src/lib/`. (GitHub #753 / RUSH-1515)
+- **`agents computer setup --host` now works from a plain `npm i -g` install — the Windows helper exe downloads on demand from GitHub releases.** The ~157MB `computer-helper-win.exe` never shipped in the npm tarball, so setup died with "Windows helper exe not built. Run: bash scripts/build-win.sh" for anyone without a repo checkout. On `v*` tags the `computer-helper-win.yml` workflow now builds the self-contained exe, smoke-tests it, and uploads it plus a `.sha256` as GitHub release assets; `setup --host` resolves a local build first, then downloads the asset for the exact running CLI version, verifies its sha256 against the published checksum, and caches it under `~/.agents/.cache/computer/win-helper/v<version>/`. A tag with no asset is a hard error naming that tag — never a silent fallback to a different release. (GitHub #547) Source: `apps/cli/src/lib/ssh-tunnel.ts` (`ensureWinHelperExe`, `downloadWinHelperExe`), `.github/workflows/computer-helper-win.yml` (`release-exe`).
+- **`registerMcp` HTTP transport now routes through the capability table instead of an inline agent-id allowlist.** MCP-over-HTTP support and MCP-header support were gated by hardcoded `agentId !== 'claude' && agentId !== 'codex' && agentId !== 'gemini'` / `agentId !== 'claude'` checks in `apps/cli/src/lib/agents.ts`, bypassing the `capabilities.ts`/`supports()` table that is the single source of truth for "which agent supports what." A newly-added agent would silently get the wrong HTTP-MCP behavior with no compile-time signal. Two new capabilities land on the `AgentConfig` matrix — `mcpHttp` (Claude/Codex/Gemini today) and `mcpHeaders` (Claude only) — and both inline allowlists are replaced with `supports(agentId, cap)` calls. Pure refactor: `capableAgents('mcpHttp')` is `['claude','codex','gemini']` and `capableAgents('mcpHeaders')` is `['claude']`, matching the pre-change behavior exactly. Source: `apps/cli/src/lib/{agents,capabilities,types}.ts`, `apps/cli/src/lib/{agents,capabilities}.test.ts`, `apps/cli/src/lib/__tests__/capabilities.test.ts`. (issue #742 / RUSH-1504)
+- **Hook `matches:` predicates are now enforced at fire time — the documented gating was inert.** A hook manifest entry could declare `matches:` predicates (`prompt_contains` / `prompt_matches` / `tool_name` / `tool_args_match` / `cwd_includes` / `project_has` / `git_dirty`) to gate when it fires, and the docs described the gate ("all predicates AND together; an empty block always fires"), but `shouldFire()` (the evaluator in `src/lib/hooks/match.ts`) had **zero runtime callers**: the agent execs the registered command directly and nothing evaluated `matches:`, so any hook with a `matches:` block fired unconditionally. A hook that declares `matches:` (with or without `cache:`) is now registered as a generated wrapper shim that evaluates the predicates against the event JSON on stdin before running the script — a non-matching event exits 0 without running the hook body (logged as `cache:"skip"`), a matching event runs it. Matches-only hooks (no `cache:`) get a gate-only pass-through shim; cached hooks apply the gate before the cache. The shim gate is a faithful port of `shouldFire()` (same AND semantics, same ReDoS guard) and is pinned to it by a 20-case conformance test so the two can't drift. Gating is fail-open: a garbled predicate runs the hook rather than silently disabling a safety hook (e.g. `git-guard`). No installed or bundled hook currently declares `matches:`, so this changes no existing hook's behavior — it activates a documented feature for authors who add one. Verified end-to-end by generating a shim from a `matches: { tool_name: Bash, tool_args_match: "rm -rf" }` manifest and firing it: a `Read` event and a `Bash`+`ls` event were skipped, a `Bash`+`rm -rf` event ran the body. Source: `apps/cli/src/lib/hooks/cache.ts` (`renderShim` gate + pass-through tail), `apps/cli/src/lib/hooks.ts` (`resolveHookCommand`), `apps/cli/docs/hooks.md`. (RUSH-1506)
+- **Browser-over-SSH no longer hangs on an unreachable remote host — it fails fast (~10s).** The raw-`ssh` spawns in the browser SSH driver (`ensureRemoteBrowser`, `runSSHCommand`) passed only `-o BatchMode=yes`, with no `ConnectTimeout`, so a dropped SYN to a down host stalled on the OS default TCP timeout (~127s) instead of erroring. Both call sites now compose the shared hardened baseline `SSH_OPTS` from `ssh-exec.ts` (`BatchMode` + `ConnectTimeout=10` + `ServerAlive` keepalive) rather than re-listing options — the same baseline `sshExec` and the `-L` tunnel already use. The options now also precede the target (matching `sshExec`); on macOS/BSD `getopt` an option placed after the target is swallowed into the remote command instead of applied. Verified against TEST-NET `203.0.113.1` (guaranteed unreachable): `-o BatchMode=yes` alone was still hanging at a 30s cap (en route to ~127s), while the `SSH_OPTS` set failed in `10.04s` with `connect to host 203.0.113.1 port 22: Connection timed out`. Source: `apps/cli/src/lib/browser/drivers/ssh.ts`. (RUSH-1508)
+- **Fix: OpenCode sessions now load on Windows.** Reading OpenCode sessions shelled out to the `sqlite3` CLI at three call sites — `parseOpenCode` (transcript parse) plus the session scan and active-account lookup in discovery — and that binary is absent on Windows, so OpenCode sessions silently never appeared in `agents sessions` there. All three now read through the same runtime-aware node/bun `Database` wrapper the Antigravity parser already uses (`bun:sqlite`/`node:sqlite`, no native addon, no CLI), and the OpenCode transcript query binds the session id as a parameter instead of interpolating it. No behavior change on macOS/Linux. Source: `apps/cli/src/lib/session/parse.ts` (`parseOpenCode`), `apps/cli/src/lib/session/discover.ts` (`scanOpenCodeIncremental`, `getOpenCodeAccount`). (RUSH-1513)
+- **`agents sessions --active --json` now carries the agent's actual decision, not a truncated status line.** A session waiting on you used to collapse everything to a one-line `preview` — an `AskUserQuestion` became the generic `"Asked you a question"` (throwing away the options that are already in the tool input), and a trailing thinking block masked the real turn as `"thinking…"`. The state engine now emits a structured `question` object (`{ text, reason, options: [{ label, description, key }] }`) for every waiting path — `AskUserQuestion` (with each option's 1-based select key), plan review, permission (Approve=`1` / Deny=`esc`), and a trailing prose question — plus a short assistant `tail` for context, and `preview` no longer degrades to `"thinking…"` when a real turn exists. Every consumer (the Factory NEEDS-YOU panel, teams, cloud) now gets the real "what does it want from me" instead of re-deriving it from prose. Verified live: the blocked session in the screenshot now reports `awaitingReason: question` with the real question text. Source: `apps/cli/src/lib/session/state.ts` (`structuredQuestionFromAsk`, `inferActivity`), `apps/cli/src/lib/session/active.ts`. (RUSH-453)
+
+## 1.20.50
+
+- **Distributed agent teams: teammates can now run on different machines across your fleet, not just the box running `teams start`.** A single team can place the backend teammate on a Linux box and the UI teammate on a Mac while one orchestrator still drives the DAG, polls status, and cleans up. One vocabulary, all optional (omit it and teams stay 100% local as before): `teams create --devices a,b,c` (alias `--hosts`) declares a pool the team may auto-schedule onto, `--repo <url|path>` (defaults to the local checkout's `origin`) says how each device gets the code, and `teams add --device X` (alias `--host`) pins one teammate to a host — which needs **no** pool, so "send just one teammate elsewhere" is zero-setup. Placement resolves top-down at launch: explicit `--device` pin → single-device pool (whole team there) → multi-device pool (least-loaded auto-schedule) → local. Remote teammates dispatch over SSH via the existing `agents devices`/host machinery (a third teammate backend beside local and cloud), are monitored by offset-tailing the remote log + `.exit` sentinel, and get the repo auto-provisioned per device (reuse an existing checkout, else clone into `~/.agents/repos/<team>`) with an optional per-teammate git worktree on the host. `teams status`/`teams logs` show each teammate's host and stream its output back with the local mirror capped (~512KB rolling tail) so a 10+-teammate fleet can't blow up the orchestrator. POSIX hosts only in v1 (Windows rejected with a clear message). Source: `apps/cli/src/lib/teams/{scheduler,remoteWorktree,agents,api,supervisor,registry}.ts`, `apps/cli/src/lib/hosts/{progress,passthrough}.ts`, `apps/cli/src/commands/teams.ts`, `apps/cli/docs/teams.md`.
+- **NEW: `agents doctor --devices` shows a cross-device agent-readiness matrix.** `agents doctor` could already run on one remote machine via `--host`, but checking the whole fleet meant running the command once per box. `--devices` fans out `agents teams doctor --json` to every registered device (plus the local machine), renders a device × agent matrix, and emits a stable JSON contract with `--json`. `--device <name>` or `--host <name>` scopes the same matrix to a single machine. The remote probe now bootstraps `PATH` with the canonical shim directories before running, so login shells that haven't sourced interactive rc files no longer report false "not installed" negatives. Source: `apps/cli/src/commands/doctor.ts`, `apps/cli/src/lib/teams/agents.ts`, `apps/cli/src/lib/hosts/{passthrough,remote-cmd}.ts`.
+- **`agents run codex` / `agents teams` now honor your configured Codex model instead of silently defaulting to `gpt-5.3-codex`.** Codex runs under a per-version `CODEX_HOME`, and your `model` preference (`~/.codex/config.toml`) lives only in the version-home that was active when you set it. A dispatch pinned to a different version read a home with no top-level `model`, so Codex fell back to its built-in default — which a ChatGPT-tier account isn't entitled to use, so the run died with `400: The 'gpt-5.3-codex' model is not supported when using Codex with a ChatGPT account` before doing any work, even though `ag view` reported Codex "signed in". When no explicit `--model` is passed, the model is now defaulted (for Codex) to the top-level `model` in your active `~/.codex/config.toml` and forwarded via `--model`; it's read-only (no file writes), so fanning out many parallel runs to one version-home can't race. Verified live on a box where Codex was 100% unusable: the request model changed `gpt-5.3-codex` → `gpt-5.5` and codex@0.142.0 returned successfully. Source: `apps/cli/src/lib/exec.ts`, `apps/cli/src/lib/shims.ts` (`readCodexConfiguredModel`).
+- **Fix: `agents add claude@<version>` now produces a runnable install — it no longer ships a half-built binary that dies with "claude native binary not installed."** `installVersion` runs `npm install --ignore-scripts` (the right posture for the dependency *tree* — never run arbitrary transitive postinstalls), but that also skipped the agent package's OWN postinstall, which for `@anthropic-ai/claude-code` is a required step: the package ships a ~500-byte stub at `bin/claude.exe` plus per-arch native binaries as optional deps, and its `postinstall` (`node install.cjs`) is what copies the correct ~231 MB native binary over the stub. Skipped, every launch died with `Error: claude native binary not installed`. The existing launch-health self-heal (#764, and its Windows/daemon extension) couldn't save it on two counts: the stub reports its breakage *politely* rather than with a raw `ENOENT`, so the probe's missing-binary signature didn't match and the gutted install read as healthy; and the repair path (`ensureAgentRunnable` → clean reinstall) re-ran the same `--ignore-scripts` install, so it never copied the binary either. `installVersion` now runs the **first-party** package's declared `postinstall` after the npm install (scoped to that one package — never the dependency tree, never claude-code's `exit 1` `prepare` guard), best-effort, before the integrity gate. Because `installVersion` is the single choke point for `agents add`, config refresh, run-time heal, and the daemon's proactive heal, this also revives the repair path for the whole class. `isMissingBinarySignature` was additionally widened to recognize the stub's polite phrases (`native binary not installed`, `postinstall did not run`, `optional dependency was not downloaded`) so the self-heal catches this failure mode if a postinstall ever silently no-ops. Verified end-to-end on linux-arm64: `installVersion('claude','2.1.186')` into a clean HOME runs the postinstall automatically, lands the 231,782,112-byte binary (not the stub), and `claude.exe --version` returns `2.1.186 (Claude Code)` — with no manual `install.cjs` step. Source: `apps/cli/src/lib/versions.ts` (`installVersion`, `isMissingBinarySignature`).
+
 ## 1.20.49
 
 - **`agents run --mode plan` no longer hard-fails on agents without a read-only mode (antigravity, cursor, kiro, …).** Those agents have no plan flag, so an explicit or default `--mode plan` used to abort with `does not support 'plan' mode` — breaking multi-agent scripts that pass a uniform plan flag, and diverging from `agents teams add` (default mode `edit`). `resolveMode` now degrades unsupported `plan` to the agent's safest native mode (`capabilities.modes[0]`, typically `edit`), matching the existing `auto` → `edit` degrade. The CLI prints a yellow warning when the user explicitly asked for plan (gray for the implicit default) so the elevation is never silent. `skip` still hard-fails when unsupported. Source: `apps/cli/src/lib/exec.ts`, `apps/cli/src/commands/exec.ts`.

package/README.md

@@ -307,6 +307,9 @@ agents logs <id> --full                 # the full raw transcript / stdout (toke
 agents logs <id> -f                     # re-attach to a running one and follow
 agents view claude --host gpu-box       # inspect the remote install
 agents sync --host gpu-box              # make the remote machine current
+agents doctor --devices                 # readiness matrix for every registered device
+agents doctor --devices --json          # machine-readable fleet readiness
+agents doctor --device mac-mini         # same matrix, scoped to one device
 
 # Your Tailscale fleet, auto-discovered
 agents devices sync                     # ingest `tailscale status`

package/dist/commands/browser-picker.js

@@ -5,29 +5,12 @@
  * Shows task name, profile, domains, and tab count; preview pane shows full tab list.
  */
 import chalk from 'chalk';
+import { truncate, humanDuration } from '../lib/format.js';
 import { itemPicker } from '../lib/picker.js';
 const DOT = chalk.gray(' · ');
-function humanDuration(ms) {
-    const s = Math.floor(ms / 1000);
-    if (s < 60)
-        return `${s}s`;
-    const m = Math.floor(s / 60);
-    if (m < 60)
-        return `${m}m`;
-    const h = Math.floor(m / 60);
-    const mm = m % 60;
-    if (h < 24)
-        return mm ? `${h}h ${mm}m` : `${h}h`;
-    const d = Math.floor(h / 24);
-    const hh = h % 24;
-    return hh ? `${d}d ${hh}h` : `${d}d`;
-}
 function formatAge(ms) {
     return humanDuration(Date.now() - ms) + ' ago';
 }
-function truncate(s, max) {
-    return s.length > max ? s.slice(0, max - 1) + '…' : s;
-}
 /** Build the preview pane for a browser task. */
 export function buildBrowserPreview(item) {
     const { task, profile } = item;

package/dist/commands/cloud.js

@@ -1,4 +1,5 @@
 import chalk from 'chalk';
+import { die, relTime, truncate, isJsonMode } from '../lib/format.js';
 import * as fs from 'fs';
 import * as path from 'path';
 import ora from 'ora';
@@ -35,28 +36,6 @@ function parseSkillRef(raw) {
     return { id: raw };
 }
 /** Print an error message to stderr and exit. */
-function die(msg, code = 1) {
-    console.error(chalk.red(msg));
-    process.exit(code);
-}
-/** Format an ISO timestamp as a human-readable relative time string. */
-function relTime(iso) {
-    const secs = Math.floor((Date.now() - new Date(iso).getTime()) / 1000);
-    if (secs < 10)
-        return 'just now';
-    if (secs < 60)
-        return `${secs}s ago`;
-    if (secs < 3600)
-        return `${Math.floor(secs / 60)} minutes ago`;
-    if (secs < 86400)
-        return `${Math.floor(secs / 3600)} hours ago`;
-    return `${Math.floor(secs / 86400)} days ago`;
-}
-function truncate(s, n) {
-    if (s.length <= n)
-        return s;
-    return s.slice(0, n - 1) + '...';
-}
 /** Return a chalk color function appropriate for the given task status. */
 function statusColor(status) {
     switch (status) {
@@ -70,9 +49,6 @@ function statusColor(status) {
         default: return chalk.white;
     }
 }
-function isJsonMode(opts) {
-    return Boolean(opts.json) || !process.stdout.isTTY;
-}
 /**
  * After a `MissingTargetError`, try to resolve the target interactively.
  * Returns the chosen id, or undefined when no interactive resolution is

package/dist/commands/computer.d.ts

@@ -37,5 +37,6 @@ export declare function reconcileScreenshotExt(outPath: string, buf: Buffer): {
 };
 export declare function registerComputerCommand(program: Command): void;
 export declare function registerComputerSubcommands(program: Command): void;
+export declare function buildRestartTaskScript(taskName: string, exeName: string): string;
 export { resolveHelperExec as resolveHelperPath };
 export { resolveSocketPath };

package/dist/commands/computer.js

@@ -4,7 +4,9 @@ import * as os from 'os';
 import * as path from 'path';
 import { registerCommandGroups } from '../lib/help.js';
 import { openComputerClient, resolveHelperApp, resolveHelperExec, resolveSocketPath, resolveLogPath, resolvePolicyPath, resolvePeersPath, resolveTcpEndpoint, loadComputerAllowList, loadDefaultPeers, writeComputerPolicy, writeComputerPeers, } from '../lib/computer-rpc.js';
-import { setupRemoteHelper, startRemoteTunnel, stopRemoteHelper, hydrateRemoteEnvFromState, } from '../lib/ssh-tunnel.js';
+import { setupRemoteHelper, startRemoteTunnel, stopRemoteHelper, hydrateRemoteEnvFromState, readRemoteState, resolveRemoteDevice, REMOTE_TASK_NAME, WIN_HELPER_EXE, } from '../lib/ssh-tunnel.js';
+import { sshExec } from '../lib/ssh-exec.js';
+import { encodePowershell } from '../lib/hosts/remote-cmd.js';
 import { registerActionCommands, withClient, unwrap, pickTarget } from './computer-actions.js';
 import { runComputerLoop } from '../lib/computer/loop.js';
 import { makeVerbDispatcher } from '../lib/computer/dispatch.js';
@@ -18,9 +20,10 @@ const COMPUTER_HELP_GROUPS = [
     { title: 'Interact', names: ['launch', 'raise', 'click', 'right-click', 'type', 'type-text', 'key', 'drag', 'scroll', 'ax-action', 'focus', 'wait'] },
 ];
 // Subcommands that manage the `--host` remote path themselves (provisioning /
-// tunnel lifecycle). Every other `--host`-bearing subcommand is a plain verb
-// that just needs the TCP endpoint hydrated before it runs.
-const REMOTE_LIFECYCLE = new Set(['setup', 'start', 'stop']);
+// tunnel lifecycle, or daemon-state reporting that must degrade gracefully
+// when no tunnel is recorded). Every other `--host`-bearing subcommand is a
+// plain verb that just needs the TCP endpoint hydrated before it runs.
+const REMOTE_LIFECYCLE = new Set(['setup', 'start', 'stop', 'status', 'reload']);
 /**
  * Pure platform gate. The computer subsystem is macOS-only for LOCAL driving
  * (Accessibility / launchctl). It is NOT blocked off macOS when a remote daemon
@@ -111,8 +114,13 @@ export function registerComputerSubcommands(program) {
 function registerStatusCommand(program) {
     program
         .command('status')
-        .description('Report install state, daemon state, and Accessibility trust')
-        .action(async () => {
+        .description('Report install state, daemon state, and Accessibility trust — or a remote Windows daemon with --host')
+        .option('--host <device>', 'Report the remote Windows daemon (tunnel + liveness) instead of the local helper')
+        .action(async (opts) => {
+        if (opts.host) {
+            await reportRemoteStatus(opts.host);
+            return;
+        }
         const socketPath = resolveSocketPath();
         const installed = fs.existsSync(HELPER_APP_DEST);
         const socketUp = fs.existsSync(socketPath);
@@ -159,6 +167,108 @@ function registerStatusCommand(program) {
         }
     });
 }
+// status --host: the local checks (app install, launchd socket, policy files)
+// are macOS concepts — a remote Windows daemon is reported from what actually
+// exists for it: the recorded tunnel and a live trust_status probe through it.
+async function reportRemoteStatus(host) {
+    console.log(`host:      ${host}`);
+    const state = readRemoteState(host);
+    if (!state) {
+        console.log('tunnel:    none');
+        console.log('daemon:    unknown (no tunnel to probe through)');
+        console.log('');
+        console.log(`Run:  agents computer start --host ${host}`);
+        process.exit(1);
+    }
+    console.log(`tunnel:    127.0.0.1:${state.localPort} -> ${state.target} (127.0.0.1:${state.remotePort})`);
+    hydrateRemoteEnvFromState(host);
+    try {
+        const client = openComputerClient();
+        try {
+            const r = await client.call('trust_status');
+            if (r.error) {
+                console.error(`error: ${r.error.code}: ${r.error.message}`);
+                process.exit(1);
+            }
+            console.log('daemon:    running');
+            console.log(`trust:     ${r.result?.trusted ? 'granted' : 'denied'} (Windows UIAutomation needs no per-app grant)`);
+            if (typeof r.result?.pid === 'number')
+                console.log(`pid:       ${r.result.pid}`);
+            if (typeof r.result?.path === 'string' && r.result.path)
+                console.log(`exe:       ${r.result.path}`);
+        }
+        finally {
+            await client.close();
+        }
+    }
+    catch (err) {
+        console.log('daemon:    unreachable');
+        console.log(`           ${err.message}`);
+        console.log('');
+        console.log(`Run:  agents computer start --host ${host}`);
+        process.exit(1);
+    }
+}
+// PowerShell to bounce the remote daemon: kill the running exe (tolerating
+// "not running"), then start the LOGON scheduled task that owns its
+// lifecycle. Pure so tests can assert the exact script (mirrors the
+// ssh-tunnel script builders).
+export function buildRestartTaskScript(taskName, exeName) {
+    const procName = exeName.replace(/\.exe$/i, '');
+    return [
+        `$ErrorActionPreference = 'Stop'`,
+        `Stop-Process -Name '${procName}' -Force -ErrorAction SilentlyContinue`,
+        `Start-ScheduledTask -TaskName '${taskName}'`,
+        `Write-Output 'restarted'`,
+    ].join('; ');
+}
+// reload --host: the Windows daemon has no policy file to re-read (it
+// enforces no allow-list — see TrustStatus in native/computer-win/Rpc.cs), so
+// reload means bounce the daemon via its scheduled task — the way to pick up
+// a freshly pushed exe — then prove it answers through the recorded tunnel.
+async function reloadRemoteHelper(host) {
+    const { target } = await resolveRemoteDevice(host);
+    const script = buildRestartTaskScript(REMOTE_TASK_NAME, WIN_HELPER_EXE);
+    const res = sshExec(target, `powershell -NoProfile -NonInteractive -EncodedCommand ${encodePowershell(script)}`, { timeoutMs: 60_000 });
+    if (res.code !== 0) {
+        const msg = (res.stderr || res.stdout || '').trim();
+        console.error(`restart failed on ${target}${res.timedOut ? ' (timed out)' : ''}${msg ? `: ${msg}` : ''}`);
+        process.exit(1);
+    }
+    console.log(`task:   restarted "${REMOTE_TASK_NAME}" on ${target}`);
+    const state = readRemoteState(host);
+    if (!state) {
+        console.log(`(no tunnel recorded — run \`agents computer start --host ${host}\` to drive it)`);
+        return;
+    }
+    hydrateRemoteEnvFromState(host);
+    // The relaunched daemon needs a beat to rebind its port; poll through the
+    // tunnel until it answers.
+    const deadline = Date.now() + 15_000;
+    let lastErr = '';
+    while (Date.now() < deadline) {
+        try {
+            const client = openComputerClient();
+            try {
+                const r = await client.call('trust_status');
+                if (!r.error && r.result) {
+                    console.log(`reloaded: daemon answering (pid ${r.result.pid ?? '?'})`);
+                    return;
+                }
+                lastErr = r.error ? `${r.error.code}: ${r.error.message}` : 'empty result';
+            }
+            finally {
+                await client.close();
+            }
+        }
+        catch (err) {
+            lastErr = err.message;
+        }
+        await sleep(500);
+    }
+    console.error(`daemon did not answer within 15s after restart${lastErr ? ` (${lastErr})` : ''}`);
+    process.exit(1);
+}
 // run — the embedded observe -> act -> verify agent loop. A reasoning model
 // (Claude API by default, or any Anthropic-shaped endpoint via --base-url for
 // Ollama / vLLM / LiteLLM) drives the EXISTING computer verbs as tools over the
@@ -560,8 +670,19 @@ function registerStartCommand(program) {
 function registerReloadCommand(program) {
     program
         .command('reload')
-        .description('Reload the allow-list policy from ~/.agents/permissions/groups/ (SIGHUP the daemon)')
-        .action(async () => {
+        .description('Reload the allow-list policy (SIGHUP the local daemon) — or restart a remote Windows daemon with --host')
+        .option('--host <device>', 'Restart the remote Windows daemon (its scheduled task) instead of SIGHUPing the local one')
+        .action(async (opts) => {
+        if (opts.host) {
+            try {
+                await reloadRemoteHelper(opts.host);
+            }
+            catch (err) {
+                console.error(`error: ${err.message}`);
+                process.exit(1);
+            }
+            return;
+        }
         const socketPath = resolveSocketPath();
         if (!fs.existsSync(socketPath)) {
             console.error(`daemon not running (no socket at ${socketPath})`);

package/dist/commands/doctor.js

@@ -1,6 +1,12 @@
 import { addHostOption } from '../lib/hosts/option.js';
+import { buildRemoteAgentsInvocation } from '../lib/hosts/remote-cmd.js';
+import { loadDevices } from '../lib/devices/registry.js';
+import { resolveHost } from '../lib/hosts/registry.js';
+import { sshExec } from '../lib/ssh-exec.js';
+import { sshTargetFor } from '../lib/hosts/types.js';
+import { machineId } from '../lib/session/sync/config.js';
 import chalk from 'chalk';
-import { checkAllClis } from '../lib/teams/agents.js';
+import { checkAllClis, collectTeamsDoctorData } from '../lib/teams/agents.js';
 import { AGENTS, ALL_AGENT_IDS, resolveAgentName, formatAgentError } from '../lib/agents.js';
 import { getGlobalDefault, getVersionHomePath, isVersionInstalled, listInstalledVersions, parseAgentSpec, } from '../lib/versions.js';
 import { loadManifest, isStale } from '../lib/staleness/index.js';
@@ -203,6 +209,121 @@ function renderExecPolicyAdvisory() {
         console.log(chalk.gray(`           ${line}`));
     }
 }
+const AGENT_ORDER = ['claude', 'codex', 'kimi', 'grok', 'antigravity', 'opencode', 'cursor', 'gemini', 'droid'];
+function shortAgentHeader(name) {
+    return name.slice(0, 4).padEnd(4);
+}
+function agentCell(entry) {
+    if (!entry)
+        return chalk.gray('-   ');
+    if (entry.installed) {
+        const signedInHint = entry.signedIn ? '*' : ' ';
+        return chalk.green(`rdy${signedInHint}`.padEnd(4));
+    }
+    if (entry.error)
+        return chalk.red('err '.padEnd(4));
+    return chalk.gray('no  '.padEnd(4));
+}
+async function resolveFleetTargets(opts) {
+    const singleName = opts.host || opts.device;
+    if (singleName) {
+        // --device / --host as a single-device filter: resolve through the device
+        // registry first, then the general host registry, then ad-hoc user@host.
+        const registry = await loadDevices();
+        const deviceProfile = registry[singleName];
+        if (deviceProfile) {
+            return [{
+                    name: deviceProfile.name,
+                    sshTarget: deviceProfile.name,
+                    os: deviceProfile.platform !== 'unknown' ? deviceProfile.platform : undefined,
+                }];
+        }
+        const host = await resolveHost(singleName);
+        if (host) {
+            return [{ name: singleName, sshTarget: sshTargetFor(host), os: host.os }];
+        }
+        console.error(chalk.red(`Unknown host or device '${singleName}'.`));
+        process.exit(1);
+    }
+    const registry = await loadDevices();
+    const localName = machineId();
+    return Object.values(registry)
+        .filter((d) => d.name.toLowerCase() !== localName)
+        .map((d) => ({
+        name: d.name,
+        sshTarget: d.name,
+        os: d.platform !== 'unknown' ? d.platform : undefined,
+    }));
+}
+async function probeFleetTarget(target) {
+    const forwarded = ['teams', 'doctor', '--json'];
+    const isWin = /^win/i.test((target.os ?? '').trim());
+    const remoteCmd = buildRemoteAgentsInvocation(forwarded, undefined, isWin ? 'windows' : undefined, 
+    // POSIX login shells often lack the shims dir; Windows PowerShell usually
+    // has it via the install profile, and our single-quote escaping would
+    // prevent $HOME expansion there, so skip the bootstrap on Windows.
+    isWin ? undefined : { PATH: '$HOME/.agents/.cache/shims:$HOME/.local/bin:$PATH' });
+    const res = sshExec(target.sshTarget, remoteCmd, { timeoutMs: 30000, multiplex: true });
+    if (res.code !== 0) {
+        return {
+            name: target.name,
+            online: false,
+            error: res.timedOut ? 'timed out' : (res.stderr || `exit ${res.code ?? 'unknown'}`),
+            agents: {},
+        };
+    }
+    try {
+        const agents = JSON.parse(res.stdout);
+        return { name: target.name, online: true, agents };
+    }
+    catch (err) {
+        const stderrHint = res.stderr ? ` stderr: ${res.stderr.trim()}` : '';
+        return {
+            name: target.name,
+            online: true,
+            error: `invalid JSON (${err?.message ?? 'parse error'})${stderrHint}`,
+            agents: {},
+        };
+    }
+}
+async function runDevicesDoctor(opts) {
+    const singleName = opts.host || opts.device;
+    const targets = await resolveFleetTargets(opts);
+    const localName = machineId();
+    const results = [];
+    // Local machine first, directly.
+    if (!singleName) {
+        results.push({ name: localName, online: true, agents: await collectTeamsDoctorData() });
+    }
+    // Remote targets in parallel.
+    const remoteResults = await Promise.all(targets.map(probeFleetTarget));
+    results.push(...remoteResults);
+    if (opts.json) {
+        console.log(JSON.stringify({ devices: results }, null, 2));
+        return;
+    }
+    if (results.length === 0) {
+        console.log(chalk.gray('No registered devices. Run `agents devices` to register some.'));
+        return;
+    }
+    const agentsToShow = AGENT_ORDER.filter((a) => results.some((r) => r.agents[a] !== undefined));
+    console.log(chalk.bold('Agent readiness by device'));
+    if (agentsToShow.length === 0) {
+        console.log(chalk.gray('  (no agent data collected)'));
+        return;
+    }
+    const nameWidth = Math.max(...results.map((r) => r.name.length));
+    const header = `  ${'Device'.padEnd(nameWidth)}  ${agentsToShow.map(shortAgentHeader).join('  ')}`;
+    console.log(chalk.gray(header));
+    for (const row of results) {
+        const status = row.online ? chalk.green('online ') : chalk.red('offline');
+        const errorSuffix = row.error ? `  ${chalk.gray(row.error)}` : '';
+        const cells = agentsToShow.map((a) => agentCell(row.agents[a])).join('  ');
+        console.log(`  ${row.name.padEnd(nameWidth)}  ${status}  ${cells}${errorSuffix}`);
+    }
+    console.log();
+    console.log(chalk.gray('  rdy* = installed and signed in · rdy = installed · no = not installed · err = probe failed · - = offline'));
+}
 function parseTargetArg(arg) {
     const at = arg.indexOf('@');
     const agentPart = at === -1 ? arg : arg.slice(0, at);
@@ -484,7 +605,9 @@ export function registerDoctorCommand(program) {
         .option('--kind <kinds>', 'Restrict to comma-separated resource kinds (commands,skills,hooks,rules,mcp,permissions,subagents,plugins,promptcuts)')
         .option('--cwd <path>', 'Resolution cwd for project layer detection (default: process.cwd())')
         .option('--adopt <agent>', "Take over the agent's native launcher that shadows the shim (symlink it to the version-managed shim; reversible with --release)")
-        .option('--release <agent>', 'Undo --adopt: restore the native launcher agents-cli previously adopted');
+        .option('--release <agent>', 'Undo --adopt: restore the native launcher agents-cli previously adopted')
+        .option('--devices', 'Check agent readiness on every registered device (alias --hosts)')
+        .option('--hosts', 'Alias of --devices');
     setHelpSections(doctorCmd, {
         examples: `
       # Overview: CLI availability + sync status + orphans across all defaults
@@ -511,6 +634,14 @@ export function registerDoctorCommand(program) {
     });
     doctorCmd.action(async (target, opts) => {
         const cwd = opts.cwd ? opts.cwd : process.cwd();
+        if (opts.devices || opts.hosts) {
+            if (target) {
+                console.error(chalk.red('Cannot combine --devices with a target argument.'));
+                process.exit(1);
+            }
+            await runDevicesDoctor(opts);
+            return;
+        }
         // Launcher adoption escape hatch. `--adopt <agent>` forces the take-over
         // even for a non-default agent; `--release <agent>` reverses it.
         if (opts.adopt || opts.release) {