@phnx-labs/agents-cli 1.22.117 → 1.22.118

package/CHANGELOG.md

@@ -1,5 +1,232 @@
 # Changelog
 
+## 1.22.118
+
+- **`agents sessions <read> --device <name>` routes a SINGLE-device READ through the standalone `sessions --host` when both sides support it (PHNX-4012).**
+  A read `--device` query (search / list / id lookup, and no explicit `--host`) that names exactly one
+  device now resolves it to its SSH target and forwards `sessions <read args> --host ssh://<target>` to
+  the local standalone — the local-orchestration collapse where `sessions` owns the remote hop, instead
+  of the in-repo peer fan-out. `--host` is point-to-one, so a **multi-device** read (`--device box
+  mac-mini`, a repeated `--device`, or a `--device all`/`fleet` sentinel) stays on the in-repo `--device`
+  fan-out, which merges the peers. It takes the standalone path only when THIS box's `sessions` is ≥ 0.2.1. If the PEER
+  lacks the standalone the remote `bash -lc` command-not-found surfaces as exit 127, on which the read
+  falls through to the existing in-repo `--device` fan-out so it still succeeds — a capability gate
+  keyed on that specific signal (same spirit as the 0.2.1 `--host` version gate), a migration bridge
+  until the fleet is uniformly on 0.2.1. Below the host floor, or with no standalone installed, a
+  `--device` read stays on the in-repo engine exactly as before. Lifecycle `--device` (resume / watch /
+  inject / focus / …) is untouched, and an explicit `--host` still wins. Internal routing change with no
+  user-visible behavior change on a healthy fleet. Source: `cli/src/lib/sessions-client.ts`,
+  `cli/src/index.ts`.
+
+- **`agents sessions … --host <target>` forwards to the standalone `sessions` CLI (PHNX-4012).**
+  A point-to-one remote read (`agents sessions <query> --host box` — SSH to ONE box, run
+  `sessions … --local`, stream JSON back) now takes the standalone fast path when the installed
+  `sessions` is ≥ 0.2.1, mirroring how the 0.2.0 filter/sort flags are version-gated. A box with
+  `sessions` below the 0.2.1 host floor — or none installed — keeps the query on the in-repo engine
+  exactly as before (which resolves `--device` against the fleet), so nothing mis-routes or crashes.
+  This is an internal routing change: `--host` behaves the same for callers, only the engine that
+  answers it changes. Source: `cli/src/lib/sessions-client.ts`, `cli/src/index.ts`.
+
+- **`agents browser` is now a thin consumer of the standalone `browser` CLI (PHNX-4101).** The
+  duplicate in-repo browser engine — the CDP/BiDi/Arc drivers, the browser IPC service, the
+  chrome-data/profile store and the network-capture pipeline — is deleted; every verb forwards
+  verbatim to `@phnx-labs/browser-cli` (`browser`), which owns the engine and keeps every on-disk
+  path the old subsystem used. agents-cli supplies only what the fleet CLI knows: `--device`
+  resolved to an SSH target (bound once at `start`), remote-control consent, the acting session
+  identity, and the capture/session history behind `agents browser sessions`. The daemon no longer
+  hosts the browser IPC service or the browser-task reaper (browser-cli runs its own), and the
+  retired `browser` alias shim no longer shadows the standalone binary on PATH. Install it with
+  `npm i -g @phnx-labs/browser-cli` or `agents setup browser`. Source: `cli/src/lib/browser-client.ts`,
+  `cli/src/commands/browser.ts`, `cli/src/lib/browser/{context,record,sessions-list,paths}.ts`,
+  `cli/src/lib/daemon/daemon.ts`, `cli/docs/browser.md`.
+
+- **A PreToolUse hook whose script is missing now denies the tool call instead of allowing it (PHNX-4106).**
+  Generated hook shims embed one source path inside a version home; when that file was gone (a
+  pruned version, sync rewriting `hooks/`) the shim exited 127, which Claude Code, Codex and Droid
+  read as "allow". On one laptop the primary-checkout guard was silently disabled for about 17
+  hours this way. A `PreToolUse` shim now exits 2 with the repair named (`agents hooks sync`) and
+  logs `cache: missing-source`, after the `matches:` gate and only for a PreToolUse firing; other
+  events and skipped fires stay fail-open. `agents prune <harness>@<version>` also re-points the
+  shims at the surviving home immediately instead of waiting for the daemon. Source:
+  `cli/src/lib/hooks/cache.ts`, `cli/src/lib/installations/versions.ts`.
+
+- **Claude no longer gets every plugin skill twice.** Sync flattened each plugin's `skills/` into
+  the top-level `skills/` of every harness, but Claude Code already loads them from the plugin
+  registration, namespaced (`/sessions:continue`), so the picker listed `/continue` and
+  `/sessions:continue` side by side for 47 skills. Claude is flagged `nativePluginSkills`: sync
+  stops flattening there, and the leftover copies are swept by the next full `agents sync claude`
+  (or `agents prune cleanup skills`). Harnesses that only see plugin skills through the flat copy
+  (Codex) are unchanged. Source: `cli/src/lib/staleness/writers/sources.ts`,
+  `cli/src/lib/agent-spec/agents.ts`.
+
+- **`auth-sync` credential pushes plan per peer off that peer's own first-hand reply, with no fleet-wide freshness gate (PHNX-4116).**
+  The daemon's `auth-sync` tick no longer skips **every** credential push when the newest fleet exchange goes
+  stale — the old `readLastSuccessfulExchangeMs` marker and its "skipping credential push … need one within
+  900s" WARN are gone. Reserved-key presence on a peer is now `verdict ∧ fingerprint`: the peer's own per-account
+  verdict row (`accounts.rows`) must be non-`missing` AND the credential fingerprint (`workerCredential.mintedAt`)
+  the publisher last delivered to that peer must match the account's current one. The verdict half is first-hand
+  — a key removed on a worker flips its next verdict to `missing` and the push resumes. The fingerprint half
+  catches a re-mint: `agents accounts login <harness>#<name>` rotates the reserved key and bumps `mintedAt` while
+  the worker's OLD token still authenticates (verdict stays live), so a publisher-side rotation cursor
+  (`reserved-sync-delivered.json`, local-only, never synced) re-pushes the new key within one tick instead of
+  reading present forever. A peer that has never replied, or whose reply carries no `accounts.rows` field at all
+  (an older CLI — fail closed), is skipped this tick and logged at INFO, not WARN. The push stays idempotent, so
+  a stale reply is safe. No user-visible surface change; a re-authed account now reaches every worker within a
+  tick, and a briefly-quiet exchange no longer stalls provisioning. Source: `cli/src/lib/daemon/auth-sync-service.ts`,
+  `cli/src/lib/secrets-policy.ts`.
+
+- **Drop stale worker account slots and their credentials (PHNX-4116).** On a
+  worker, `reconcileLocalWorkerSlots` now removes any `deviceAccounts.slots`
+  record whose account is no longer registered — the leftovers of an older
+  account-id generation, each a full HOME carrying a live `.claude/.oauth_token`
+  — deleting the 0600 credential while KEEPING the directory (its
+  `.claude/projects` holds transcripts) and logging one line per drop. It fails
+  closed: an empty or unreadable account registry drops nothing, so a transient
+  read can never strip a healthy box's whole slot set. Source:
+  `cli/src/lib/secrets-policy.ts`, `cli/src/lib/accounts/slots.ts`.
+
+- **A routine skipped by an overlapping run reads `blocked`, not "wedged"
+  (PHNX-4116).** Since there is no longer a "wedged" daemon state, a routine
+  whose prior run is still active now reports `blocked: run <id> active since
+  <t>` — naming the live run and when it started — instead of the stale "wedged:
+  a prior run is still active". Source: `cli/src/commands/routines.ts`.
+
+- **`agents daemon status` no longer calls a worker's absent secrets broker
+  `down` (PHNX-4116).** On a box that reads file-backed secret stores (every
+  headless worker), an unreachable broker is expected — secrets read one-shot
+  with no broker — so the health line now reads `info  secrets agent not running
+  (file-backed stores)` instead of `down  secrets broker (unreachable)`. A
+  keychain-backed box with no broker is still a real fault and still reads
+  `down`. Source: `cli/src/commands/daemon.ts`.
+
+- **A balanced pick or the account picker now launches the account it chose (PHNX-4116).**
+  Since accounts became registered slots (PHNX-3940), a `balanced` pick and the "no fresh usage"
+  picker only set the executable version, so the run started in that version's home with whatever
+  login it held. On yosemite-m0 the picker chose `trp` and Claude Code opened as another account,
+  in its first-run wizard. Both paths now resolve the picked candidate through the same local
+  launch resolver an explicit `--account` uses, so the spawn gets the slot's home and durable
+  credential env. Source: `cli/src/commands/exec.ts`.
+
+- **One run-readiness gate, computed on the box that runs (PHNX-4116).** `agents view --json`
+  now carries a per-agent `runReady` (`{ ready, reason, accounts: [{ name, ready, reason }] }`)
+  computed from the router's own enumeration — native account slots AND version homes
+  (`collectRunCandidates` → `readinessFromCandidate`), not the per-version list, which missed the
+  slots a run actually picks from. `--device auto` reads that answer instead of re-deriving usage
+  freshness on the dispatching box, so a worker holding a valid setup-token is schedulable on that
+  fact: a synced-only usage row (its poller lives on the headed box that published it) is never
+  refused for being old — its age weights the pick, it never decides eligibility — and a
+  rate-limit window whose reset has already passed reads as available. A placement error now names
+  the box's own reason, e.g. `no ready harness account (all signed_out)`, instead of a bare
+  `no ready harness account`. `agents devices harnesses` now derives its displayed usage
+  percentage from the SAME live windows as the status verdict (`liveUsageWindows`), so a
+  maxed-then-reset account no longer reads `available` next to a stale ~100%. The one-release
+  fallback for an older remote CLI without `runReady` keeps the pre-fix throttle exclusion — a
+  FRESH `rate_limited`/`out_of_credits` or a FRESH dead auth verdict still disqualifies a
+  launchable version, while a STALE reading stays unverified — so a throttled worker cannot slip
+  into `--device auto` during a rolling upgrade. Source: `cli/src/commands/view.ts`,
+  `cli/src/lib/hosts/ready.ts`, `cli/src/lib/accounting/rotate.ts`,
+  `cli/src/lib/accounting/usage.ts`, `cli/src/lib/devices/harness-inventory.ts`,
+  `cli/src/lib/smart-launch.ts`.
+
+- **A wedged daemon service now restarts the whole daemon instead of parking a dead service or reading `wedged` forever (PHNX-4116).**
+  A supervised daemon service that HANGS past its deadline (a stuck usage refresh, a frozen heartbeat)
+  no longer parks and waits for an in-process backoff restart that could stall for days — the
+  supervisor records the cause and exits the process (code 70), and systemd (`Restart=always`,
+  `RestartSec=30`, `StartLimitIntervalSec=0`, `KillMode=process`) / launchd (`KeepAlive` +
+  `ThrottleInterval=30`) restart the daemon within ~30s, so it recovers on its own like any
+  well-behaved service. A service whose tick merely THROWS is recorded and keeps ticking. The
+  `parked` service state and the `wedged` daemon state are gone: `agents daemon status` now reports
+  `running`/`stopped`, the daemon's PID, uptime, heartbeat age, and the count of supervised restarts
+  in the last 24h with the last cause. Source: `cli/src/lib/daemon/supervisor.ts`,
+  `cli/src/lib/daemon/daemon.ts`.
+
+- **Usage rows and daemon state travel over SSH; the shared user repo carries no daemon state (PHNX-4116).**
+  The 15-minute `usage-sync` tick used to commit every device's `devices/<device>/daemon-state.json`
+  into the fleet-synced user repo and exchange it under a lock and a 45 s deadline. That grew the
+  shared store to 1.1 GiB and 18,358 commits (100% of the last 2,000 were `chore(devices): publish
+  <device> daemon state`), one worker's clone fell 10,398 commits behind with `git fetch timed out`
+  on every tick, and a box holding a valid setup-token could not be scheduled because a repo was
+  bloated. A headed (`personal`/`desktop`) daemon now dials every dialable peer in parallel with
+  `agents __usage-ingest --reply` (20 s per peer; a timed-out peer is skipped for that tick), sending
+  its own envelope on stdin; the peer merges the usage rows into its cache newest-wins, stores the
+  envelope as that peer's file, and prints its own state back, which the headed box stores stamped
+  `receivedAt`. Workers never initiate. The placement probe ingests the dispatcher's usage rows on the
+  same round-trip, so the chosen worker holds current numbers at dispatch. `agents repo sync user` is
+  a plain fetch-and-fast-forward of human-authored resources again; the 8-minute kickoff offset that
+  only existed to dodge the repo lock is gone. `__usage-ingest` gains `--reply`; the legacy v1 payload
+  from an older headed peer is still accepted. Source: `cli/src/lib/accounting/usage-sync.ts`,
+  `cli/src/lib/accounting/usage-ingest.ts`, `cli/src/lib/daemon/usage-sync-service.ts`.
+
+- **`agents update claude#work` works, and a refused update names the process holding the installation (PHNX-4116).**
+  The `<agent>#<account>` selector `agents run` already takes was rejected by `update` as
+  "Unknown agent 'claude#work'"; it now resolves to the managed installation that account runs on
+  and refuses only an account the registry does not know. "Account home is in use; retry after its
+  sessions finish" is replaced by the actual holder, e.g. `pid 2173999, up 01:10:22, pts/1:
+  …/claude --resume 3ef30267…`, with `agents sessions stop <id>` as the way out. Source:
+  `cli/src/commands/update.ts`, `cli/src/lib/installations/active-check.ts`.
+
+- **`agents view` / `agents accounts list` show FACTS per account per box, never a
+  word that means "we did not look" (PHNX-4116).** Each account row now states its
+  evidence: the **token** on disk (`sk-ant-oat01 (Sep 16)` = the slot's
+  `.claude/.oauth_token` scheme prefix + file date, `api key (present)`, or
+  `no token`), what happened when it was last **used** (`last used ok 12m ago` /
+  `last auth failure 401 Sep 20 14:02` / `rate-limited until 15:00` / `not used on
+  this box yet`), and a **usage** reading that names its origin when it came from
+  another box (`S 12% W 40% … (from zion)`). The auth fact is recorded from real run
+  outcomes into the auth-health cache with a new `source: 'run'` field — an auth
+  failure at the routine runner's `isAuthFailureFromLog` sites, a success at
+  statusline ingest and a clean headless `agents run` exit. `agents view <harness>
+  --json` accounts now carry `token` and `lastAuth` for the emitting box. Source:
+  `cli/src/lib/auth-health.ts`, `cli/src/lib/account-catalog.ts`,
+  `cli/src/commands/accounts.ts`, `cli/src/commands/view.ts`.
+
+- **A synced usage file no longer masquerades as a live auth verdict, and a worker
+  no longer publishes a `unverified` probe row (PHNX-4116).** `verdictFromFreshUsage`
+  refuses a `freshness.source === 'sync'` snapshot — a fresh reading from another
+  box's poller proves the shared token works somewhere, not that THIS box can
+  authenticate. A worker's setup-token box, which cannot read the usage endpoint,
+  now returns the honest `no_evidence` verdict (dropped from the published probe
+  rows) instead of the overloaded `unverified`, so eight identical workers read one
+  distinct picture instead of five. Source: `cli/src/lib/auth-health.ts`.
+
+- **A `--host <worker>` routine activates on a token-backed worker again
+  (PHNX-4116).** Dropping the worker's `no_evidence` probe row left `agents devices
+  ping --local --json` with no row for the agent, so host-placed routine readiness
+  read the absent row as `unconfigured` and reported `agent_auth_failed` with a
+  valid token on disk. `devices ping --local --json` now also emits `launchable`
+  (the agents this box holds a launchable signed-in credential for, from the same
+  `collectRunCandidates` the run router uses), and one shared decision
+  (`decideRoutineAuthReadiness`) is used by both the local and host readiness paths:
+  an absent row plus a launchable credential is ready, a box with no credential
+  fails, and a fresh `revoked` blocks — so both paths reach the same answer for the
+  same box. Source: `cli/src/lib/routine-readiness.ts`, `cli/src/commands/ssh.ts`.
+
+- **`--device auto` no longer refuses a worker whose usage reading is merely old (PHNX-4116).**
+  Remote readiness re-derived a 40-minute usage-freshness refusal from `agents view --json`'s
+  per-version list, so one broken usage-sync made every worker read `no ready harness account`
+  while `--device <name>` on the same box launched fine. The dispatcher now READS the running box's
+  own `runReady` verdict instead of re-deriving it (see the readiness fragment); usage age weights
+  the pick, it never decides eligibility. Source: `cli/src/lib/hosts/ready.ts`.
+
+- **The daemon no longer freezes for minutes on session-index and mirror writes (PHNX-4154).**
+  `session_text` FTS rows now sit at the rowid of the `sessions` row they describe and are
+  addressed by it (schema v51, a one-time rebuild: 24 s for a 669 MB index). Every delete and
+  content read used to filter on the UNINDEXED `session_id`, a full scan of the FTS content per
+  statement; the fleet session mirror runs one per mirrored row inside a daemon tick, so the
+  daemon's event loop stalled for 10+ minutes per tick, every service logged `tick exceeded
+  deadline`, and `agents browser` verbs on the same loop timed out with
+  `Arc Apple Event timed out`. Source: `cli/src/lib/session/db.ts`.
+
+- **Fix `ENOTDIR` crash on stale lock files.** `withFileLock` and `withFileLockAsync`
+  now self-heal when a prior crash left a regular file instead of the directory
+  `proper-lockfile` expects, matching the caller's `realpath` option when computing
+  the lock path. Source: `cli/src/lib/fs-atomic.ts`.
+
+- **Fix `Unknown account` for unregistered native logins.** `ag run claude#email`
+  now discovers a native OAuth login from version-home `.claude.json` files when the
+  account is not yet in `accounts.native`, and correctly routes it through the
+  provider-backed harness guard. Source: `cli/src/lib/account-registry.ts`.
+
 ## 1.22.117
 
 - **`agents run --local`, and `--device <this machine>` no longer SSHes to itself.** A bare
@@ -11,6 +238,14 @@
   MagicDNS name, loopback, or the `interactive` sentinel now resolves to the same local
   run. The placement-failure hint names `--local`. Source: `cli/src/commands/exec.ts`
   (`pinLocalWhenTargetIsSelf`), `cli/src/lib/placement.ts`, `cli/src/lib/hosts/remote-cmd.ts`.
+- **`agents sessions` filter/sort queries take the standalone fast path when it's new enough.**
+  `--project`/`-p`, `--since`, `--until`, `--sort`, and the harness shorthands
+  (`--claude`/`--codex`/…) now route to the standalone `sessions` binary when the installed one is
+  ≥ 0.2.0 (which implements them), and stay on the in-process engine otherwise — a version probe
+  (`sessions --version`, cached, run only when such a flag is present) gates it, so an older binary
+  never gets a flag it would mis-read as an FTS token. `--json`/`--limit`/`--agent` and a bare
+  query/id already route unconditionally, unchanged. Behavior is unchanged; the fast path just
+  covers more queries. Source: `cli/src/lib/sessions-client.ts`, `cli/src/index.ts`.
 
 ## 1.22.116
 

package/dist/bootstrap.js

@@ -1193,18 +1193,11 @@ catch (err) {
     if (err instanceof Error && err.name === 'ExitPromptError') {
         process.exit(130);
     }
-    // Browser-service-not-running and CDP-not-reachable surface as typed errors
-    // from src/lib/browser/. Don't dump a Node stacktrace for these — they are
-    // user-actionable, not engineering bugs. See issues #41 and #43.
     if (err instanceof Error) {
-        const isBrowserServiceNotRunning = err.name === 'BrowserServiceNotRunningError';
-        const isBrowserCdpUnreachable = err.name === 'BrowserCdpConnectionError';
-        const isBrowserIpcDown = err.message.startsWith('IPC error:') &&
-            (err.message.includes('ECONNREFUSED') || err.message.includes('ENOENT'));
-        if (isBrowserServiceNotRunning || isBrowserCdpUnreachable || isBrowserIpcDown) {
-            console.error(err.message);
-            process.exit(1);
-        }
+        // (The browser-service-not-running / CDP-unreachable / IPC-down typed errors
+        // were thrown by the in-repo browser engine, deleted with PHNX-4101; the
+        // standalone `browser` CLI now prints its own user-actionable errors and
+        // agents-cli forwards its exit code, so there is nothing to special-case here.)
         // A --device targeting a password-auth device throws this from resolveHost.
         // It carries an actionable message (switch to key auth / enroll as a host);
         // handling it here covers every resolveHost caller (run, hosts check/rm,

package/dist/commands/browser.d.ts

@@ -1,82 +1,64 @@
-import { Command } from 'commander';
-import { type BrowserProfile } from '../lib/browser/profiles.js';
-import { listInstalledBrowsers } from '../lib/browser/chrome.js';
-import type { DeviceProfile } from '../lib/devices/registry.js';
-export declare function remoteStartTaskName(stdout: string, explicit?: string): string | undefined;
 /**
- * Fetch an absolute remote file into a private local path, bounded.
+ * `agents browser` — the consumer surface over the standalone `browser` CLI
+ * (@phnx-labs/browser-cli, PHNX-4101).
  *
- * Bounded for real, not by a pre-flight `stat`: the byte budget is enforced on the
- * stream as it arrives (`sshExecRawStream` + `cat`), so a file that grows between
- * a size check and the copy — or a peer that lies about the size — still cannot
- * spend more than the budget. `scp` could not do this; it would transfer
- * everything before this process got a chance to refuse.
+ * WHAT THIS FILE IS NOW. Every verb below forwards its arguments verbatim to the
+ * standalone engine and propagates its exit code. agents-cli contributes what the
+ * engine cannot know, carried on the fd-3 context (`lib/browser/context.ts`):
  *
- * The local file is written 0600 inside a 0700 directory, because a capture can
- * show anything that was on the peer's screen and a world-readable temp path
- * would publish it to every local user.
- */
-/**
- * The command that streams one file's RAW BYTES to stdout on the device's shell.
+ *   1. `--device <name>` resolved against the fleet — the device registry, ssh
+ *      identity and platform — so the engine drives the right remote box without
+ *      a fleet registry of its own (it matches the alias against `context.target`,
+ *      then `~/.ssh/config`);
+ *   2. whether THIS machine consents to being driven by a peer
+ *      (`browser.remote-control`); the engine enforces the resolved flag;
+ *   3. the acting actor and agent session, so an action lands in the right
+ *      session history.
  *
- * Platform-correct, not one command with a portable-looking name. On Windows
- * `cat` is an alias for `Get-Content`, which is a TEXT reader: it decodes the
- * file, splits it into lines, and re-encodes on output — so a screenshot arrives
- * corrupted rather than merely reordered. The .NET path opens a `FileStream` and
- * copies it into the raw stdout handle, bypassing PowerShell's object/text
- * pipeline entirely, which is the only way binary survives.
- */
-export declare function remoteReadFileArgv(remotePath: string, shell: DeviceProfile['shell']): string[];
-/**
- * Largest capture `browser show --device` will pull. A capture is a screenshot,
- * a PDF or a short recording; anything past this is not something a viewer should
- * stream over ssh, and the cap is what makes the transfer BOUNDED rather than
- * "however big the peer's file happens to be".
+ * The engine streams back the actions it performed on fd 4, and agents-cli — which
+ * owns `sessions.db` — records each into the durable `browser_sessions` row that
+ * `agents browser sessions` and `agents sessions --browser` read
+ * (`lib/browser/record.ts`).
+ *
+ * THE REMOTE PATH IS THE ENGINE's. `--device <name>` is resolved to an ssh target
+ * here and forwarded verbatim (the engine binds the device once at `start` and
+ * runs page verbs against the task's bound device). agents-cli opens no tunnel and
+ * publishes no endpoint: the engine owns the CDP/BiDi/Arc drivers, the IPC service,
+ * the chrome-data store and the profile declarations, keeping every on-disk path
+ * the in-repo subsystem used (integration contract §4).
+ *
+ * WHY VERB FLAGS ARE NOT REDECLARED HERE. Each passthrough verb takes everything
+ * as opaque operands via `allowUnknownOption`. Mirroring the engine's flags would
+ * create a second, silently drifting copy of its surface: a flag added upstream
+ * would be rejected here as unknown until someone noticed. The engine also owns
+ * per-verb `--help` for the same reason. What agents-cli keeps is the verb CATALOG
+ * — names, one-line descriptions, help groups — because that is what makes the
+ * surface discoverable from `agents browser --help`.
+ *
+ * `sessions` is the one verb that never reaches the engine: it reads agents-cli's
+ * own capture/session history (`browser-sessions-picker.ts`).
  */
-export declare const REMOTE_VIEW_MAX_BYTES: number;
+import { Command } from 'commander';
 /**
- * Fetch an absolute remote file into a private local path, bounded.
+ * The verb catalog. Descriptions are the consumer's (they appear in
+ * `agents browser --help`); flags are the engine's.
  *
- * Auth is the CANONICAL device path, not a hand-rolled ssh: `buildSshInvocation`
- * supplies the askpass shim for a password-auth box, `-i`/`IdentitiesOnly` for an
- * explicit identity file, and the managed known-hosts pinning. Building the ssh
- * args here instead meant a password-auth device could not be reached at all and
- * an explicit `identityFile` was silently ignored.
+ * This list is the contract with the engine: a verb the engine drops should fail
+ * loud here rather than silently vanish, and `browser.test.ts` pins the names so a
+ * drift shows up as a failing test. `sessions` is deliberately NOT in the list —
+ * it is agents-cli's own reader, registered separately.
  *
- * Bounded for real, not by a pre-flight `stat`: the byte budget is enforced on the
- * stream as it arrives, so a file that grows between a size check and the copy — or
- * a peer that misreports its size — still cannot spend more than the budget.
- *
- * The local file is written 0600 inside a 0700 directory, because a capture can
- * show anything that was on the peer's screen and a world-readable temp path
- * would publish it to every local user.
+ * `start` is the ONE verb that resolves `--device`; the engine binds the device
+ * there and rejects `--device` on the page verbs itself.
  */
-export declare function fetchRemoteFileForViewing(device: string, remotePath: string, localPath: string, opts?: {
-    maxBytes?: number;
-    timeoutMs?: number;
-}): Promise<void>;
+export declare const BROWSER_PASSTHROUGH_VERBS: ReadonlyArray<{
+    name: string;
+    description: string;
+}>;
 /**
- * The fleet browser hub this box drives by default (`browser.device`), or
- * undefined to drive locally. It is one fleet-synced value in the central
- * agents.yaml, so every box reads the same hub name — but the hub itself resolves
- * to a self-host, and a fleet-dispatched invocation is already ON its target, so
- * both return undefined. That self short-circuit is what lets a single synced
- * value be safe: only the boxes that are NOT the hub forward to it, and the hub
- * never forwards to itself.
+ * Peek `--device <name>` (or `--device=name`) out of a raw argv without consuming
+ * it — the flag is forwarded to the engine verbatim, and agents-cli only reads it
+ * to resolve the fleet target for the fd-3 context. Pure, so it is unit-testable.
  */
-export declare function defaultBrowserHub(): string | undefined;
+export declare function peekDevice(argv: string[]): string | undefined;
 export declare function registerBrowserCommand(program: Command): void;
-export declare function registerBrowserSubcommands(program: Command): void;
-interface BrowserUseOptions {
-    unset?: boolean;
-}
-interface BrowserUseChoice {
-    name: string;
-    value: {
-        name: string;
-        installed?: ReturnType<typeof listInstalledBrowsers>[number];
-    };
-}
-export declare function buildBrowserUseChoices(profiles: BrowserProfile[], installed: ReturnType<typeof listInstalledBrowsers>, current?: string): BrowserUseChoice[];
-export declare function runBrowserUse(name: string | undefined, opts: BrowserUseOptions, interactive?: boolean): Promise<boolean>;
-export {};