@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/devices/config-migration.js

@@ -1,42 +1,3 @@
-/**
- * One-time migration to the current device-config + pins layout:
- *
- *   (a) central `fleet.devices.<name>.config` (the short-lived #2458 store)
- *       folds into each per-device doc's `config:` block — central wins
- *       (newest intent) — and is stripped from central;
- *   (b) legacy `.history/devices/auto-launch.json` flags fold into the doc
- *       `config:` too (oldest store — only fills keys not already set);
- *   (c) a top-level `defaultBrowserProfile:` in a device doc folds into that
- *       doc's `config:`;
- *   (d) agent pins (`agents:` / `isolatedAgents:`) leave the TRACKED
- *       per-device docs: THIS machine's pins move to the untracked
- *       `.history/devices/pins-<host>.json` (pins file wins on conflict — it
- *       is the destination); peers' pins are simply dropped from the tracked
- *       file (each peer owns/rewrites its own pins locally).
- *   (e) legacy `.history/devices/ignored.json` (per-machine, UNTRACKED — a
- *       dismissal never reached the rest of the fleet) folds into the central
- *       TRACKED `fleet.ignored` list (RUSH-3062). Entries keep the legacy
- *       file's `updatedAt` as `ignoredAt` and take THIS machine's id as
- *       `ignoredOn` — the legacy store recorded neither, so the folding box
- *       is the only attribution available. The legacy file is removed only
- *       AFTER the central write lands.
- *
- * What stays put: a device doc's existing `config:` (already the right home)
- * and its `routines:` list (operator-owned, read cross-device by
- * routine-activation.ts).
- *
- * Order is crash-safe: destination writes (pins file, device doc) land BEFORE
- * the source strip (central), so a crash mid-fold re-folds on the next run and
- * the destination-wins merges make that a no-op. Idempotent — after a
- * successful run none of the legacy locations hold data, so re-running is a
- * cheap existence check. A doc that fails to parse is LOUDLY skipped (left
- * untouched) so the next run retries — never silently emptied, same corruption
- * contract the device registry keeps.
- *
- * Invoked from three places so every install converges regardless of entry
- * point: `runMigration()` (fresh / sentinel-less installs), daemon boot, and
- * the first `lib/device-config.ts` read/write in a process.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
@@ -45,7 +6,6 @@ import { atomicWriteFileSync } from '../fs-atomic.js';
 import { machineId } from '../machine-id.js';
 import { withIgnoredAdded } from './registry.js';
 import { addIgnoredEntry } from './device-docs.js';
-/** Read every device doc. A doc that fails to parse is loudly skipped. */
 function readDeviceDocs(devicesRoot) {
     const docs = [];
     let entries;
@@ -53,7 +13,7 @@ function readDeviceDocs(devicesRoot) {
         entries = fs.readdirSync(devicesRoot, { withFileTypes: true });
     }
     catch {
-        return docs; // no devices/ tree — nothing to fold
+        return docs;
     }
     for (const entry of entries) {
         if (!entry.isDirectory())
@@ -70,7 +30,7 @@ function readDeviceDocs(devicesRoot) {
             continue;
         }
         if (parsed === null || parsed === undefined)
-            continue; // empty doc
+            continue;
         if (typeof parsed !== 'object' || Array.isArray(parsed)) {
             console.error(`device config migration: ${docPath} is not a YAML map; leaving it for manual repair`);
             continue;
@@ -79,7 +39,6 @@ function readDeviceDocs(devicesRoot) {
     }
     return docs;
 }
-/** Write a device doc, or remove it (and its dir) when nothing remains. */
 function writeDeviceDoc(docPath, doc) {
     try {
         if (Object.keys(doc).length === 0) {
@@ -87,7 +46,7 @@ function writeDeviceDoc(docPath, doc) {
             try {
                 fs.rmdirSync(path.dirname(docPath));
             }
-            catch { /* not empty — other files live in the device dir */ }
+            catch { }
         }
         else {
             fs.mkdirSync(path.dirname(docPath), { recursive: true });
@@ -98,7 +57,6 @@ function writeDeviceDoc(docPath, doc) {
         console.error(`device config migration: could not rewrite ${docPath} (${err.message}); a later run retries`);
     }
 }
-/** The legacy auto-launch.json flags, keyed by device name ({} when absent). */
 function readAutoLaunchFlags(autoLaunchPath) {
     const out = {};
     let raw;
@@ -106,7 +64,7 @@ function readAutoLaunchFlags(autoLaunchPath) {
         raw = fs.readFileSync(autoLaunchPath, 'utf-8');
     }
     catch {
-        return out; // absent — nothing to fold
+        return out;
     }
     let parsed;
     try {
@@ -133,19 +91,13 @@ function readAutoLaunchFlags(autoLaunchPath) {
 function isConfigMap(v) {
     return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
-/**
- * The legacy per-machine ignored.json. Absent => null. A parse failure is
- * logged loudly and reported as `undefined` so the caller LEAVES the file in
- * place for a later retry — never silently emptied, the same corruption
- * contract the ignore-list itself keeps (registry.ts's loadIgnoredEntries).
- */
 function readLegacyIgnoredFile(p) {
     let raw;
     try {
         raw = fs.readFileSync(p, 'utf-8');
     }
     catch {
-        return null; // absent — nothing to fold
+        return null;
     }
     try {
         const parsed = JSON.parse(raw);
@@ -159,16 +111,10 @@ function readLegacyIgnoredFile(p) {
         return undefined;
     }
 }
-/**
- * Fold every legacy device-config/pins location into the current layout. Safe
- * to call on every boot / config access: cheap no-op once folded.
- */
 export function migrateDeviceConfigStores() {
     const devicesRoot = path.join(getUserAgentsDir(), 'devices');
     const autoLaunchPath = getDevicesAutoLaunchPath();
     const self = machineId();
-    // ── 1. Gather ────────────────────────────────────────────────────────────
-    // Central per-device config (the #2458 store).
     const fleet = readMeta().fleet;
     const centralDevices = fleet && fleet.devices !== 'all' ? fleet.devices : {};
     const centralHasConfig = Object.values(centralDevices).some((ov) => ov?.config && Object.keys(ov.config).length > 0);
@@ -177,19 +123,11 @@ export function migrateDeviceConfigStores() {
     const legacyIgnoredPath = getDevicesIgnoredPath();
     const legacyIgnoredPending = fs.existsSync(legacyIgnoredPath);
     const legacyIgnored = legacyIgnoredPending ? readLegacyIgnoredFile(legacyIgnoredPath) : null;
-    // Central shared fleet.discovery / fleet.ignored (PHNX-3315): the maps N boxes
-    // used to rewrite. Folded into THIS box's device doc below, then stripped.
     const centralFleetState = !!(fleet &&
         ((fleet.discovery && Object.keys(fleet.discovery).length > 0) ||
             (Array.isArray(fleet.ignored) && fleet.ignored.length > 0)));
-    // Central shared `hosts:` map (PHNX-3315): the host registry N boxes used to
-    // rewrite. Folded into THIS box's device doc below, then the central key is
-    // dropped entirely.
     const centralHosts = readMeta().hosts;
     const centralHostsPending = !!(centralHosts && Object.keys(centralHosts).length > 0);
-    // Central device-scoped native accounts (PHNX-3315): a native login is
-    // machine-local, so `scope:'device'` identities (and the bindings that target
-    // them) belong in this box's device doc, off the git-tracked shared file.
     const centralAccounts = readMeta().accounts;
     const accountsPending = !!(centralAccounts?.native && Object.values(centralAccounts.native).some((a) => a.scope === 'device'));
     const pinsPath = getDevicePinsPath();
@@ -197,9 +135,7 @@ export function migrateDeviceConfigStores() {
     try {
         selfPins = JSON.parse(fs.readFileSync(pinsPath, 'utf-8')) || {};
     }
-    catch { /* absent or malformed — the fold below recreates it */ }
-    // ── 1b. Plan (pure) — so a converged install never takes the meta lock or
-    //    rewrites a byte-identical doc on every boot.
+    catch { }
     const plans = [];
     for (const { name, path: docPath, doc } of docs) {
         const plan = planDeviceDocFold(name, docPath, doc, centralDevices[name]?.config, autoLaunchFlags[name]);
@@ -227,15 +163,8 @@ export function migrateDeviceConfigStores() {
     const autoLaunchPending = fs.existsSync(autoLaunchPath);
     if (!centralHasConfig && !hasDestinationWork && !autoLaunchPending && !legacyIgnoredPending && !centralFleetState && !centralHostsPending && !accountsPending)
         return;
-    // ── 2. Destination writes FIRST (crash-safe), under the meta lock so they
-    //    serialize against writeMetaUnlocked's own read-merge-write of the doc.
-    //    Only taken when there IS a write — a converged install never locks
-    //    (taking it would create a default central agents.yaml as a side effect).
     if (hasDestinationWork) {
         withMetaLock(() => {
-            // 2a. THIS machine's pins: doc pins merge INTO the pins file (pins file
-            //     wins — it is the destination, and a re-fold after a crash must not
-            //     clobber pins the new CLI already wrote).
             if (docAgents || docIsolated) {
                 const pins = { ...selfPins };
                 if (docAgents)
@@ -250,17 +179,12 @@ export function migrateDeviceConfigStores() {
                     console.error(`device config migration: could not write ${pinsPath} (${err.message}); a later run retries`);
                 }
             }
-            // 2b/2c. The planned doc rewrites + creations.
             for (const plan of plans)
                 writeDeviceDoc(plan.path, plan.next);
             for (const nd of newDocs)
                 writeDeviceDoc(nd.path, nd.doc);
         });
     }
-    // ── 3. Source strips LAST ────────────────────────────────────────────────
-    // 3a. Central: drop every devices.<name>.config block (now folded into the
-    //     device docs). Overrides left with no other fields are dropped; an
-    //     emptied fleet block (no defaults/secrets/routines) goes away entirely.
     if (centralHasConfig) {
         updateMeta((m) => {
             const devices = m.fleet?.devices;
@@ -274,11 +198,6 @@ export function migrateDeviceConfigStores() {
                     nextDevices[name] = rest;
             }
             const fleet = { ...m.fleet, devices: nextDevices };
-            // Drop the whole `fleet` block only when NOTHING else lives in it. Every
-            // resident must be named here: `ignored` holds the user's dismissals and
-            // `discovery` their discovery policy, and deleting the block would not
-            // just lose them locally — `agents repo push` would sync the deletion
-            // fleet-wide. Add any new fleet.* key to this guard.
             const fleetIsEmpty = Object.keys(nextDevices).length === 0 &&
                 !fleet.defaults &&
                 !fleet.secrets &&
@@ -293,7 +212,6 @@ export function migrateDeviceConfigStores() {
             return { ...m, fleet };
         });
     }
-    // 3b. The legacy auto-launch.json.
     if (autoLaunchPending) {
         try {
             fs.rmSync(autoLaunchPath, { force: true });
@@ -302,11 +220,6 @@ export function migrateDeviceConfigStores() {
             console.error(`device config migration: could not remove ${autoLaunchPath} (${err.message}); a later run retries`);
         }
     }
-    // ── 4. Legacy ignored.json → central fleet.ignored ───────────────────────
-    // Destination write (updateMeta: withMetaLock + atomic write) lands BEFORE
-    // the legacy file is removed, so a crash re-folds on the next run and
-    // withIgnoredAdded's union-by-name makes that a no-op. A file that failed to
-    // parse (legacyIgnored === undefined) is left in place for that retry.
     if (legacyIgnored) {
         if (legacyIgnored.names.length > 0) {
             updateMeta((m) => withIgnoredAdded(m, legacyIgnored.names, legacyIgnored.updatedAt ?? new Date().toISOString()));
@@ -318,13 +231,6 @@ export function migrateDeviceConfigStores() {
             console.error(`device config migration: could not remove ${legacyIgnoredPath} (${err.message}); a later run retries`);
         }
     }
-    // ── 5. Central fleet.discovery / fleet.ignored → THIS box's device doc ─────
-    // (PHNX-3315) The shared maps every box used to rewrite fold into this box's
-    // deviceFleet, then are stripped from central. writeMetaUnlocked writes the
-    // device doc BEFORE the central strip, so a crash re-folds on the next run and
-    // the union-dedup (ignored beats approved; newest ignoredAt wins) makes the
-    // re-fold a no-op. Idempotent — once central holds neither key the gather
-    // guard above skips this whole pass.
     if (centralFleetState) {
         updateMeta((m) => {
             const disc = m.fleet?.discovery;
@@ -339,7 +245,7 @@ export function migrateDeviceConfigStores() {
                     if (status !== 'approved' && status !== 'ignored')
                         continue;
                     if (discovery[name] === 'ignored')
-                        continue; // ignored is never downgraded
+                        continue;
                     discovery[name] = status;
                 }
             }
@@ -359,8 +265,6 @@ export function migrateDeviceConfigStores() {
                 delete fleet.discovery;
                 delete fleet.ignored;
             }
-            // Drop an emptied fleet block entirely (mirrors step 3a's guard) so the
-            // strip does not leave a bare `fleet: { devices: {} }` behind.
             const fleetEmpty = !fleet ||
                 ((fleet.devices === undefined ||
                     (fleet.devices !== 'all' && Object.keys(fleet.devices).length === 0)) &&
@@ -375,30 +279,17 @@ export function migrateDeviceConfigStores() {
             return { ...m, deviceFleet, fleet };
         });
     }
-    // ── 6. Central hosts map → THIS box's device doc (PHNX-3315) ───────────────
-    // The shared host registry folds into this box's deviceHosts, then the central
-    // key is dropped. writeMetaUnlocked writes the device doc before the central
-    // strip, so a crash re-folds and the newest-addedAt union makes it a no-op.
-    // Idempotent — once central holds no `hosts:` the gather guard skips this.
     if (centralHostsPending) {
         updateMeta((m) => {
             const hosts = m.hosts;
             if (!hosts || Object.keys(hosts).length === 0)
                 return m;
-            // This box's own device-doc entries win over the shared legacy on a name
-            // collision (a re-fold after a crash must not clobber a fresher local edit).
             const deviceHosts = { ...hosts, ...m.deviceHosts };
             const { hosts: _drop, ...rest } = m;
             void _drop;
             return { ...rest, deviceHosts };
         });
     }
-    // ── 7. Central device-scoped native accounts → THIS box's device doc ───────
-    // (PHNX-3315) Fold `scope:'device'` natives and the bindings that target them
-    // out of central and into the device doc, removing their identity PII from the
-    // git-tracked shared file. The selection is recomputed INSIDE the lock so a
-    // concurrent write is never clobbered; the device-doc write precedes the
-    // central strip, so a crash re-folds and the id-keyed merge makes it a no-op.
     if (accountsPending) {
         updateMeta((m) => {
             const native = { ...m.accounts?.native };
@@ -437,8 +328,6 @@ export function migrateDeviceConfigStores() {
                 accounts.bindings = bindings;
             else
                 delete accounts.bindings;
-            // Drop the whole central `accounts` block only when nothing fleet-shared
-            // remains (no version natives, no bindings, no defaults).
             const accountsEmpty = !accounts.native && !accounts.bindings && !accounts.defaults;
             if (accountsEmpty) {
                 const { accounts: _drop, ...rest } = m;
@@ -449,7 +338,6 @@ export function migrateDeviceConfigStores() {
         });
     }
 }
-/** Shallow-set equality for folded doc content (values compared deep via JSON). */
 function sameDocContent(a, b) {
     const ak = Object.keys(a);
     const bk = Object.keys(b);
@@ -457,13 +345,6 @@ function sameDocContent(a, b) {
         return false;
     return ak.every((k) => k in b && JSON.stringify(a[k]) === JSON.stringify(b[k]));
 }
-/**
- * Compute a device doc's post-fold content: merge the config layers (oldest
- * auto-launch.json flags < the doc's own config: < the central #2458 block —
- * newest wins), fold a top-level defaultBrowserProfile into config:, and strip
- * pins from the tracked file. Returns null when the doc is corrupt (loudly —
- * left for manual repair) or the fold would not change its content.
- */
 function planDeviceDocFold(name, docPath, doc, centralConfig, autoFlags) {
     const config = {};
     Object.assign(config, autoFlags);
@@ -480,7 +361,6 @@ function planDeviceDocFold(name, docPath, doc, centralConfig, autoFlags) {
     if (isConfigMap(centralConfig))
         Object.assign(config, centralConfig);
     const next = {};
-    // Preserve fields the migration does not own (routines:, anything else).
     for (const [k, v] of Object.entries(doc)) {
         if (k === 'config' || k === 'defaultBrowserProfile' || k === 'agents' || k === 'isolatedAgents')
             continue;

package/dist/lib/devices/connect.d.ts

@@ -1,7 +1,5 @@
 import { type DeviceProfile } from './registry.js';
-/** Env var the askpass shim reads to know which bundle holds the password. */
 export declare const ASKPASS_BUNDLE_ENV = "AGENTS_SSH_BUNDLE";
-/** Env var the askpass shim reads to know which key in the bundle is the password. */
 export declare const ASKPASS_KEY_ENV = "AGENTS_SSH_KEY";
 /**
  * Env var that forces the askpass bundle resolve to be broker-only (`agentOnly`)
@@ -11,171 +9,22 @@ export declare const ASKPASS_KEY_ENV = "AGENTS_SSH_KEY";
  * sheet. See {@link buildSshInvocation}'s `agentOnly` option and `runAskpass`. (RUSH-1970)
  */
 export declare const ASKPASS_AGENT_ONLY_ENV = "AGENTS_SSH_AGENT_ONLY";
-/**
- * Build the `user@host` (or bare `host`) ssh target for a device and validate
- * it against the shared injection guard. Throws if the device has no address.
- */
 export declare function sshTargetFor(device: DeviceProfile): string;
-/**
- * The address a fleet fan-out probe should hand to `ssh` for a device: the
- * registry's known-good Tailscale dnsName/IP (via {@link sshTargetFor}) when
- * present, else the bare name (an address-less manual device dials by name as
- * before — never worse than the old behaviour).
- *
- * Prefer the registry address so a stale `~/.ssh/config` alias can never shadow
- * it: dialing the bare device name lets ssh resolve it through the user's config,
- * where a hand-written `Host <name>` block with a DHCP-drifted LAN IP silently
- * shadows the correct entry, times out, and makes a reachable box look dead.
- * Pure/testable.
- */
 export declare function fleetDialTarget(device: DeviceProfile): string;
-/**
- * Render `cmd` as the single command string ssh sends to the peer.
- *
- * Windows devices speak PowerShell, so the result is run through
- * `powershell -NoProfile -EncodedCommand`; POSIX devices get it as the remote
- * login shell sees it. Returns undefined when no command was given (interactive
- * login).
- *
- * TWO MODES, and the difference is load-bearing rather than a convenience.
- *
- * The default joins the tokens RAW. That is not a bug to be tidied away: every
- * existing caller of `agents ssh` relies on the remote shell interpreting what it
- * is handed — `agents ssh box 'bash -lc "cd x && make"'` arrives as ONE token
- * whose pipeline, globs and redirections the peer's shell must expand. Quoting
- * that would ship the whole line as a literal argument and break it.
- *
- * `{ argv: true }` is for a caller that genuinely holds an argv ARRAY and needs
- * each element delivered as exactly one token. Joining those raw destroys any
- * token containing a space or a metacharacter — `['--title', 'two words']`
- * arrives as three tokens, and `'a & b'` arrives as a backgrounded command — which
- * is what a native client hitting this path actually hit.
- *
- * So fidelity is opt-in at the call site that knows which shape it has, and the
- * quoting itself reuses the canonical helpers (`shellQuote`, {@link pwshQuote})
- * rather than introducing a third escaping scheme.
- */
 export declare function wrapRemoteCommand(device: DeviceProfile, cmd: string[], opts?: {
     argv?: boolean;
     prelude?: string[];
 }): string | undefined;
-/**
- * Single-quote one token for PowerShell's OWN parser. Inside a single-quoted pwsh
- * string the only special character is `'`, escaped by doubling.
- *
- * This is correct for a value PowerShell itself consumes, and NOT sufficient for
- * an argument handed on to a native program — see the Win32 note below.
- */
 export declare function pwshQuote(token: string): string;
-/**
- * True when `cmd` is a browser drive: `agents browser …`, `ag browser …`, or
- * the standalone `browser` binary (`cli/package.json` `bin.browser` →
- * `src/browser.ts`), including the quoted single-string form
- * `agents ssh box 'browser …'`. The `--device` passthrough stamps
- * {@link markFleetRemote} on this shape so the far-side consent gate can fire;
- * `agents ssh` must too (PHNX-3065).
- */
 export declare function isAgentsBrowserDrive(cmd: string[]): boolean;
-/**
- * Prefix a remote command with the provenance the far-side browser needs: the
- * `AGENTS_FLEET_REMOTE=1` consent marker AND the caller's resolved actor
- * (`AGENTS_ACTOR*`/`GIT_*`). Without the actor, a task created over
- * `agents ssh <host> 'agents browser …'` is stamped `UNRESOLVED@<host>` because
- * the peer re-resolves identity from its own (empty) env — the same RUSH-2028
- * gap the `--device` dispatch already closes via `withActorEnv`, applied here to
- * the `agents ssh` browser-drive seam so ownership is honest across BOTH paths.
- *
- * `wrapRemoteCommand` joins the argv with spaces (POSIX) or base64-encodes it for
- * PowerShell, so a shell-appropriate prelude rides through both: `env VAR=v …` on
- * POSIX, `$env:VAR='v'; …` on PowerShell. The marker stays the FIRST token so the
- * consent gate and the idempotency guard below both still key on it.
- *
- * `provenanceEnv` is injectable so tests can pin a deterministic actor; it
- * defaults to the live resolved actor. Already-marked argv (the `--device`
- * fan-out stamps the marker before {@link buildSshInvocation}) is left unchanged
- * so nothing is doubled.
- */
-/**
- * The provenance prefix as READY SHELL SYNTAX for the device's shell.
- *
- * These tokens are already quoted/escaped for their target shell — a POSIX
- * `K=V` pair is `shellQuote`d here, and a PowerShell assignment is a complete
- * statement with its own doubled quotes. That matters because argv mode quotes
- * every token it is handed: quoting THESE again turns
- * `'AGENTS_ACTOR=Some Name'` into `''\''AGENTS_ACTOR=Some Name'\'''` and turns a
- * pwsh assignment into an inert string literal. So the prelude is composed
- * SEPARATELY from the caller's argv rather than concatenated into it, and this is
- * the single definition both paths use.
- */
 export declare function fleetRemotePrelude(device: Pick<DeviceProfile, 'shell'>, provenanceEnv?: Record<string, string>): string[];
 export declare function markFleetRemote(cmd: string[], device: Pick<DeviceProfile, 'shell'>, provenanceEnv?: Record<string, string>): string[];
-/**
- * Build the remote command that starts an INTERACTIVE LOGIN shell inside a
- * mirrored project directory, falling back to the remote home when that
- * directory is absent. Returns undefined when there is nothing to mirror
- * (`mirrorCwd` is undefined, or resolves to the home root itself) so the caller
- * keeps the plain no-command interactive login.
- *
- * This is the interactive analogue of `agents run --device`'s cwd mirroring, and
- * it reuses the SAME machinery so there is no second resolver: the portable
- * `mirrorCwd` comes from `deriveMirroredCwd`, and — for POSIX — the best-effort
- * `cd` comes from `remoteCdPrefix({ mirror: true })`, whose `|| cd "$HOME"`
- * guarantees a missing checkout never fails the login (acceptance #2). It then
- * replaces the wrapper with a login shell (`exec "$SHELL" -l`); running under
- * the forced tty (`-tt`, see {@link buildSshInvocation}) makes that login shell
- * interactive, so prompt, startup files, and login behavior match a plain
- * `ssh <host>` (acceptance #1).
- *
- * PowerShell hosts get a profile-loading interactive shell (`-NoExit`, and
- * deliberately NOT `-NoProfile` so the user's profile still runs) that
- * `Set-Location`s into the mirrored dir when it exists. The path is carried
- * through `-EncodedCommand` (base64 UTF-16LE), so it is literal and
- * injection-safe regardless of spaces or shell metacharacters (acceptance #3).
- */
 export declare function buildInteractiveShellCommand(device: DeviceProfile, mirrorCwd: string | undefined): string | undefined;
-/** Host-key posture for {@link buildSshInvocation}. */
 interface SshHostKeyOptions {
-    /**
-     * True when the device's host key is already pinned in the managed
-     * known_hosts store — connections then verify with `StrictHostKeyChecking=yes`
-     * (a key swap is refused). False (the default) keeps `accept-new` for a
-     * genuine first enrollment, whose learned key lands in the managed store and
-     * pins the host for every subsequent connect. See {@link hostKeyCheckingOpts}.
-     */
     pinned?: boolean;
-    /** Managed known_hosts path override (tests). Defaults to the CLI-managed store. */
     knownHostsFile?: string;
 }
-/** OpenSSH argv that makes an explicit device key authoritative. */
 export declare function deviceIdentityArgs(device: DeviceProfile): string[];
-/**
- * Build the argv (after the `ssh` program name) and the environment overlay
- * for connecting to a device. For password auth this points `SSH_ASKPASS` at
- * the shim and disables pubkey + the host's interactive password prompt so the
- * shim is the only auth path. Pure (no spawn) so it is unit-testable.
- *
- * Host-key checking runs against the CLI-managed known_hosts store (never the
- * user's `~/.ssh/known_hosts`): strict once `hostKey.pinned` is set, else
- * `accept-new` to learn+pin the key on first connect (RUSH-1767).
- *
- * `opts.agentOnly` marks the connection as a read-only probe: for password auth
- * it sets {@link ASKPASS_AGENT_ONLY_ENV} in the overlay so the askpass resolve
- * stays broker-only and never pops a foreground biometric (RUSH-1970).
- *
- * `opts.interactiveCwd` is the portable (`~/…`) directory to mirror on an
- * interactive login (no `cmd`) — from `deriveMirroredCwd(process.cwd())`. When
- * it names a real home-relative sub-path, the login starts there via
- * {@link buildInteractiveShellCommand} (best-effort — a missing dir falls back
- * to the remote home), matching `agents run --device`. It is ignored when a `cmd`
- * is given: an explicit command keeps its current cwd (the remote home) and its
- * behavior unchanged (RUSH-2412).
- *
- * An `agents browser …` / `ag browser …` / standalone `browser …` command is
- * prefixed with {@link markFleetRemote} so the far-side consent gate sees
- * `AGENTS_FLEET_REMOTE=1` the same way `browser --device` does. The local `env`
- * overlay here is for the ssh *client* (askpass); it cannot carry the marker —
- * OpenSSH does not forward arbitrary env (PHNX-3065).
- */
 export declare function buildSshInvocation(device: DeviceProfile, cmd: string[], askpassShimPath: string, hostKey?: SshHostKeyOptions, opts?: {
     agentOnly?: boolean;
     interactiveCwd?: string;
@@ -184,26 +33,9 @@ export declare function buildSshInvocation(device: DeviceProfile, cmd: string[],
     args: string[];
     env: Record<string, string>;
 };
-/**
- * Build the askpass shim's `#!/bin/sh` body: a script that re-invokes this CLI
- * as `agents ssh __askpass`. The relaunch argv comes from {@link getCliLaunch},
- * never a hand-rolled `[process.execPath, process.argv[1], …]` — on a Bun
- * standalone binary `process.argv[1]` is the *virtual* embedded entry
- * `/$bunfs/root/agents`, which the CLI would then receive as a bogus subcommand
- * (`unknown command '/$bunfs/root/agents'`), print nothing, and hand ssh an
- * empty password. `getCliLaunch` resolves the physical executable so the shim
- * works on both the standalone and JS/dev builds. Every argv element is
- * shell-quoted. Pure (takes the launch as a parameter) so it is unit-testable.
- */
 export declare function buildAskpassShimBody(launch?: {
     command: string;
     args: string[];
 }): string;
-/**
- * Write (idempotently) the askpass shim — a tiny executable that re-invokes
- * this CLI as `agents ssh __askpass`. ssh execs `SSH_ASKPASS` with no usable
- * args, so the shim carries no secret itself; it only bridges ssh's askpass
- * protocol back into the CLI, which then resolves the bundle.
- */
 export declare function writeAskpassShim(): string;
 export {};