@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/commands/ssh.js

@@ -1,14 +1,3 @@
-/**
- * `agents devices` (registry) + `agents ssh` (smart wrapper).
- *
- * `agents devices` keeps a registry of SSH device profiles — platform, login
- * user, address, and auth — self-populated from `tailscale status --json`.
- * `agents ssh <name>` then connects through one hardened path: preflight
- * (offline → fail fast instead of a 2-minute hang), platform-aware exec
- * (PowerShell on Windows), and password-from-bundle auth via an askpass shim.
- * Rendering the registry to an ssh_config include also lets plain ssh / scp /
- * rsync / `agents sessions --device` resolve the same logical names.
- */
 import { spawnSync } from 'child_process';
 import * as fs from 'fs';
 import * as os from 'os';
@@ -63,14 +52,9 @@ import { filterAutoPool, listWorkerDevices } from '../lib/devices/pool.js';
 import { registerCommandGroups, setHelpSections } from '../lib/help.js';
 import { isSelfHost } from '../lib/devices/self-host.js';
 import { collectHeldWorktrees, collectHeldWorktreesUnder, summarizeHeld, aggregateHeld, pushStrandedBranch, } from '../lib/worktree/held.js';
-/** One-line summary of a device for `list`. `isSelf` marks the machine this
- * command is running on so it stands out from the rest of the tailnet.
- * `isInteractive` marks the configured interactive host (`devices config <name> interactive.host`). */
 function deviceSummary(d, isSelf = false, stats, isInteractive = false, roles) {
     d = resolveDeviceProfile(d);
     const addr = hostNameFor(d) ?? chalk.gray('no address');
-    // Prefer a fresh live verdict (this run's probe, else the written-back
-    // reachability) over the stale tailscale.online snapshot (RUSH-1965).
     const state = deviceOnlineState(d, stats);
     const online = state === 'online'
         ? chalk.green('online')
@@ -81,18 +65,11 @@ function deviceSummary(d, isSelf = false, stats, isInteractive = false, roles) {
     const marker = isSelf ? chalk.cyan('▸ ') : '  ';
     const name = isSelf ? chalk.bold.cyan(d.name.padEnd(16)) : chalk.bold(d.name.padEnd(16));
     const here = isSelf ? chalk.cyan('  ← this machine') : '';
-    // `roles` defaults to a single-device roster so a fleet-wide `role` default
-    // still reaches this device even when it has no per-device doc of its own.
     const roleMap = roles ?? listConfiguredDeviceRoles([d.name]);
-    // `personal` already means "the interactive box you sit at", so the star would
-    // just repeat it — show it only when the interactive host is NOT a personal box
-    // (e.g. an unmarked or worker box deliberately pinned as the artifact target).
     const interactive = isInteractive && roleMap[d.name] !== 'personal' ? chalk.yellow('  ★ interactive') : '';
     const role = roleTag(d.name, roleMap);
     return `${marker}${name} ${String(d.platform).padEnd(8)} ${(d.user ? d.user + '@' : '') + addr}  ${online}${reach}${here}${interactive}${role}`;
 }
-/** The fleet-wide role mark, rendered for a device row. Empty when unmarked —
- * an unmarked device is the common case and must not add a column of noise. */
 function roleTag(name, roles) {
     const role = roles[name];
     if (!role)
@@ -112,7 +89,6 @@ const HEADROOM_BADGE = {
     loaded: chalk.red('● loaded'),
     unknown: chalk.gray('· —'),
 };
-/** A right-aligned percentage cell, colored by severity (green/yellow/red). */
 function pctCell(v, width) {
     if (v === undefined)
         return chalk.gray('—'.padStart(width));
@@ -123,45 +99,19 @@ function pctCell(v, width) {
         return chalk.yellow(s);
     return chalk.red(s);
 }
-/** Floor for the `spec` column; the real width is measured from the rows.
- *
- * A fixed width cannot work here: `fmtBytes` emits an optional decimal, so a
- * spec string runs from `8c 16G 256G` (11) to `10c 23.5G 460G` (14) depending
- * purely on the hardware behind it. Anything narrower than the widest row
- * pushes load/mem/disk/headroom out of alignment row-to-row AND against the
- * header — which defeats the scannability this column exists for. */
 const SPEC_WIDTH_MIN = 12;
-/** The static hardware as one compact cell — `12c 64G 1T`: cores, total RAM,
- * total root disk via fmtBytes. `—` covers two cases: no probe has ever seen
- * the box, or the probe answered but yielded no usable core count (`parseNcpu`
- * finding none, or the Windows `ncpu` group failing the finite-and-positive
- * check) — the cell is keyed on `ncpu` because a spec string without it would
- * read as a machine with zero cores.
- *
- * Deliberately NOT gated on `reachable`: hardware does not change while a
- * machine is down, so an offline device keeps rendering the spec from its last
- * successful probe (`retainHardwareFacts`, RUSH-3096) rather than blanking a
- * fact that is still true. The volatile columns beside it — load, mem, disk
- * used — stay `—`, and `fleetCapacity` still counts only reachable boxes, so
- * a down machine never contributes to usable capacity.
- *
- * Unpadded; {@link renderDeviceTable} pads to the measured column width. */
 function specText(stats) {
     if (!stats?.ncpu)
         return '—';
     return `${stats.ncpu}c ${fmtBytes(stats.memTotalBytes)} ${fmtBytes(stats.diskTotalBytes)}`;
 }
-/** The widest spec string across the rows actually being rendered, floored at
- * SPEC_WIDTH_MIN so a short fleet still lines up with the header. */
 function specColumnWidth(names, statsMap) {
     return Math.max(SPEC_WIDTH_MIN, ...names.map((n) => stringWidth(specText(statsMap.get(n)))));
 }
-/** Colour + pad one spec cell to the measured column width. */
 function specCell(stats, width) {
     const text = specText(stats);
     return (text === '—' ? chalk.gray : chalk.greenBright)(text.padEnd(width));
 }
-/** The one-line `description` config value per device (absent when unset). */
 function listDeviceDescriptions(names) {
     const out = {};
     for (const n of names) {
@@ -171,37 +121,19 @@ function listDeviceDescriptions(names) {
     }
     return out;
 }
-/**
- * Fit a device row to the terminal width. The description is the FIRST thing
- * to truncate, then the role tag; the fixed columns (device, platform, spec,
- * load/mem/disk numbers, headroom, and the ▸/★/←/relay markers) never
- * truncate. `role` and `desc` arrive fully rendered (ansi + leading gap).
- */
 function fitDeviceRow(fixed, role, desc, width) {
     const w = (s) => stringWidth(stripAnsi(s));
     let over = w(fixed) + w(role) + w(desc) - width;
     if (over > 0 && desc) {
-        // `desc` is '  ' + gray(text) — truncate the text, keep the gap.
         const text = stripAnsi(desc).slice(2);
         const budget = w(text) - over;
         desc = budget > 0 ? '  ' + chalk.gray(truncateToWidth(text, budget)) : '';
         over = w(fixed) + w(role) + w(desc) - width;
     }
-    // A partial role word ("work…") reads as a bug — when it can't fit whole,
-    // it drops entirely. The numbers are never touched.
     if (over > 0 && role)
         role = '';
     return fixed + role + desc;
 }
-/**
- * Render the device list. When `statsMap` is provided, resource columns are
- * appended — a `spec` cell (cores / total RAM / total disk), normalized load,
- * memory and disk-used percentages, a headroom badge, and (in `full` mode)
- * free/total memory — with the per-device role and `description` riding the
- * tail, so it's obvious which boxes have room and what each box is for.
- * Without it (probe skipped) the classic reachability line is used. A fleet
- * capacity summary is appended whenever stats were gathered.
- */
 export function renderDeviceTable(reg, names, self, statsMap, full = false, interactiveHost, opts = {}) {
     if (!statsMap) {
         const roles = listConfiguredDeviceRoles(names);
@@ -229,8 +161,6 @@ export function renderDeviceTable(reg, names, self, statsMap, full = false, inte
         chalk.gray('description');
     lines.push(head);
     for (const name of names) {
-        // Effective profile: the operator's central config (ssh.*/platform/user)
-        // overlays the discovery record, so the table shows what would be dialed.
         const d = resolveDeviceProfile(reg[name]);
         const isSelf = name === self;
         const marker = isSelf ? chalk.cyan('▸ ') : '  ';
@@ -239,21 +169,8 @@ export function renderDeviceTable(reg, names, self, statsMap, full = false, inte
         const stats = statsMap.get(name);
         const role = roleTag(name, deviceRoles);
         const desc = descriptions[name] ? '  ' + chalk.gray(descriptions[name]) : '';
-        // Prefer this run's live probe, then the written-back verdict, over the
-        // stale tailscale.online snapshot — so a reachable box never renders
-        // "offline" while its live load/mem sit one column over (RUSH-1965).
         const offline = deviceOnlineState(d, stats) === 'offline';
         if (offline) {
-            // The spec cell rides the offline row: hardware is what the box IS, not
-            // what it is doing, so it stays legible while the machine is down
-            // (RUSH-3096). The live columns are omitted rather than dashed — there is
-            // no current load/mem/disk to report for a box that did not answer.
-            //
-            // The explicit gap is load-bearing: `specCell` pads to the MEASURED
-            // column width, so the widest spec on the fleet pads to nothing and the
-            // marker would collide with it ("455Goffline"). An online row gets its
-            // separation for free from `pctCell`'s right-alignment; this one has no
-            // numeric cell to lean on.
             lines.push(fitDeviceRow(`${marker}${label}${plat} ${specCell(stats, specWidth)}  ${chalk.gray('offline')}`, role, desc, width));
             continue;
         }
@@ -269,13 +186,9 @@ export function renderDeviceTable(reg, names, self, statsMap, full = false, inte
             : '';
         const badge = HEADROOM_BADGE[headroom(stats)];
         const here = isSelf ? chalk.cyan('  ← this machine') : '';
-        // A `personal` role already conveys "your interactive seat"; don't double-
-        // render the star on it. Keep it for a non-personal pinned interactive host.
         const interactive = name === interactiveHost && deviceRoles[name] !== 'personal' ? chalk.yellow('  ★ interactive') : '';
         lines.push(fitDeviceRow(`${marker}${label}${plat} ${specCell(stats, specWidth)}${load}${mem}${disk}${freeTotal}  ${badge}${relay}${here}${interactive}`, role, desc, width));
     }
-    // Fleet capacity summary — total cores, how much RAM is free right now, and
-    // total free root disk across the reachable fleet.
     const cap = fleetCapacity(statsMap.values());
     if (cap.reachable > 0) {
         const freePct = cap.memTotalBytes > 0 ? Math.round((cap.memFreeBytes / cap.memTotalBytes) * 100) : 0;
@@ -290,13 +203,6 @@ export function renderDeviceTable(reg, names, self, statsMap, full = false, inte
     }
     return lines;
 }
-/**
- * Live "Leased boxes" section for `agents devices` (F4, RUSH-1923), computed
- * from `crabboxList()` — these are ephemeral crabbox leases, NEVER written into
- * the device registry. Returns [] when crabbox is unavailable / has no creds /
- * reports no boxes, so the section is simply omitted. `nowSecs` is injected so
- * the row formatting is deterministic in tests.
- */
 export function renderLeasedBoxesSection(boxes, nowSecs) {
     if (boxes.length === 0)
         return [];
@@ -323,40 +229,25 @@ export function renderLeasedBoxesSection(boxes, nowSecs) {
     lines.push(chalk.gray('  Reuse a box with `agents run --box <slug>` · stop with `agents devices lease stop <slug>`'));
     return lines;
 }
-/** The leased-box rows for the devices list, or [] when crabbox can't be read. */
 function loadLeasedBoxesSection() {
     try {
         const boxes = crabboxList({ secretsBundle: process.env.AGENTS_LEASE_SECRETS_BUNDLE, timeoutMs: 5000 });
         return renderLeasedBoxesSection(boxes, Math.floor(Date.now() / 1000));
     }
     catch {
-        return []; // crabbox not installed / no provider creds — omit the section
+        return [];
     }
 }
-/**
- * Whether `agents devices list` shows the "Leased boxes" section (RUSH-2190).
- * Opt-in via --all only: loading it scans the keychain for bundle credentials
- * and can raise a Touch ID sheet after the table has printed, so the default
- * list must never reach for it. --no-stats stays the hard "instant, no provider
- * calls" opt-out even when --all is passed.
- */
 export function showLeasedBoxesSection(opts) {
     return opts.all === true && opts.stats !== false;
 }
-/**
- * `agents ssh <slug>` targeting a leased crabbox box. crabbox provisions a
- * per-lease identity key, so we ssh via crabbox's OWN emitted invocation
- * (`crabboxSshArgv`) — a raw `ssh crabbox@ip` fails publickey. Returns false when
- * `name` is not a known crabbox slug so the caller can fall through to the normal
- * "Unknown device" error.
- */
 function trySshLeasedBox(name, cmd) {
     let box;
     try {
         box = crabboxFind(name, { secretsBundle: process.env.AGENTS_LEASE_SECRETS_BUNDLE, timeoutMs: 5000 });
     }
     catch {
-        return false; // crabbox unavailable — not a leased-box target
+        return false;
     }
     if (!box)
         return false;
@@ -365,22 +256,13 @@ function trySshLeasedBox(name, cmd) {
         console.error(chalk.red(`Leased box '${name}' is not reachable yet (status: ${boxStatus(box)}).`));
         process.exit(1);
     }
-    // Crabbox ssh does not go through buildSshInvocation; stamp the same
-    // consent marker so a browser drive on a leased box is gated too.
     const remoteCmd = leasedBoxRemoteCmd(cmd);
     const res = spawnSync(sshArgv[0], [...sshArgv.slice(1), ...remoteCmd], { stdio: 'inherit' });
     process.exit(res.status ?? 1);
 }
-/**
- * Remote argv for `agents ssh <slug>` into a leased crabbox. Crabbox ssh does
- * not go through {@link buildSshInvocation}, so this stamps the same
- * AGENTS_FLEET_REMOTE consent marker a registered-device ssh would (PHNX-3065).
- * Exported so the branch is unit-testable without a live crabbox.
- */
 export function leasedBoxRemoteCmd(cmd) {
     return isAgentsBrowserDrive(cmd) ? markFleetRemote(cmd, { shell: 'posix' }) : cmd;
 }
-/** Resolve a device or exit with a clear error. */
 async function mustGetDevice(name) {
     const d = await getDevice(name);
     if (!d) {
@@ -389,14 +271,6 @@ async function mustGetDevice(name) {
     }
     return d;
 }
-/**
- * Interactive `agents devices sync`: discover tailscale nodes, present a
- * checkbox pre-checked with what's already registered, and reconcile the
- * choice. Checked = registered (and un-ignored). Unchecked = removed from the
- * registry AND added to the ignore-list, so auto-discovery never re-suggests
- * it — this is the "click to register/unregister" surface, with dismissals that
- * stick.
- */
 async function runInteractiveDeviceSync() {
     const spinner = ora('Reading tailscale status...').start();
     let nodes;
@@ -418,12 +292,6 @@ async function runInteractiveDeviceSync() {
     let selected;
     try {
         selected = await checkbox({
-            // Everything not already dismissed starts checked, so pressing Enter keeps
-            // the fleet as-is (matching what auto-sync would register). Unchecking a
-            // device removes it AND dismisses it so auto-sync never re-adds it.
-            // Sharee nodes (shared in by another user) start unchecked unless already
-            // registered — registering one must be a deliberate check, never the
-            // default Enter.
             message: 'Your fleet — uncheck a device to remove and stop suggesting it:',
             pageSize: Math.min(nodes.length, 20),
             choices: nodes.map((n) => {
@@ -464,16 +332,6 @@ async function runInteractiveDeviceSync() {
     ].filter(Boolean);
     console.log(parts.join(chalk.gray(' · ')));
 }
-/**
- * Print a per-device result table for fleet update/run.
- *
- * `verifications` is supplied only by the rollout (`agents fleet update`), which
- * re-probes what `agents` resolves to on each upgraded box. A box that upgraded
- * with `exit 0` but still resolves to another copy — the dev-install shadow of
- * RUSH-2446 — is rendered `stale` / `unverified`, counted as **not upgraded**,
- * and makes the command exit non-zero. An `exit 0` alone never reads as `ok` on
- * a rollout again.
- */
 function printFleetResults(results, verifications) {
     const nameW = Math.max(8, ...results.map((r) => r.name.length));
     console.log(chalk.bold('DEVICE'.padEnd(nameW)) + '  ' +
@@ -520,15 +378,9 @@ async function localHealthRow(self, stats) {
         clis: checkAllClis(),
         sync: checkSyncStatus(process.cwd()),
         orphans: countOrphans(),
-        // Local baseline inventory for cross-device divergence (RUSH-2027) — the
-        // yardstick every remote box is compared against.
         inventory: await collectLocalFleetInventory(process.cwd()),
     };
 }
-/** SSH into a host and read its already-computed fleet-status row (a cheap
- *  `fleet status --local --json` on the peer — NOT a fresh remote resource probe;
- *  the peer's daemon keeps that row warm). Bounded + reaped via sshExecAsync's
- *  timeout (RUSH-2114). */
 async function probeRemoteFleetStatus(target) {
     const isWin = /^win/i.test((target.platform ?? '').trim());
     const env = isWin ? undefined : { PATH: '$HOME/.agents/.cache/shims:$HOME/.local/bin:$PATH' };
@@ -556,23 +408,13 @@ async function probeRemoteHealth(target) {
         clis: parsed.clis ?? {},
         sync: parsed.sync ?? [],
         orphans: parsed.orphans ?? [],
-        // The remote self-reports its own cached auth rollup (fresh via its daemon),
-        // so the Auth column is current without a prior fleet-wide `fleet ping`.
-        // Older remotes that don't emit it fall back to this host's cache below.
         auth: parsed.auth,
-        // Harness inventory (resources / agent versions / repo state) for
-        // cross-device divergence detection (RUSH-2027). Undefined on an older CLI
-        // that doesn't emit the `fleet` field — the comparator skips it.
         inventory: parsed.fleet,
     };
 }
-/** Device-layer config only (not fleet defaults), keyed by the canonical YAML key. */
 function deviceConfigJson(name) {
     const config = {};
     for (const entry of listConfig({ device: name })) {
-        // The device's OWN layer only — a fleet-default value is not this
-        // device's setting (the effective profile fields already carry the
-        // merged view via resolveDeviceProfile).
         if (entry.source !== 'device')
             continue;
         config[entry.spec.yamlKey] = entry.value;
@@ -583,10 +425,6 @@ async function runFleetStatus(opts) {
     const reg = await loadDevices();
     const self = machineId();
     const forceRefresh = Boolean(opts.refresh || opts.live);
-    // `--local`: the publish endpoint the read-union reads over ssh. Probe THIS
-    // host only (resource stats + live-agent workload, no ssh) and print its row.
-    // Publishes into the local mirror as a side effect so a same-host reader is
-    // instantly warm too.
     if (opts.local) {
         const { publishLocalFleetStatus } = await import('../lib/fleet-status.js');
         const row = await publishLocalFleetStatus(self);
@@ -598,26 +436,15 @@ async function runFleetStatus(opts) {
     }
     const planned = planFleetTargets(reg);
     const probeable = planned.filter((t) => !t.skip).map((t) => t.device);
-    // Cache-first: serve remote stats from the daemon-warmed cache (instant),
-    // probe this machine locally, and only ssh out for missing/forced rows.
     const statsMap = opts.stats === false
         ? new Map()
         : (await loadFleetStats(probeable, { forceRefresh, selfName: self })).stats;
-    // Persist the live probe's reachability verdict so the online/offline word is
-    // read from a fresh probe, not a stale tailscale snapshot (RUSH-1965).
-    // Best-effort: a registry write must never break the status render.
     await writeReachability(collectReachabilityWriteBacks(reg, statsMap)).catch(() => { });
     const rows = [await localHealthRow(self, statsMap.get(self))];
     const remoteTargets = remoteFleetTargets(planned, self)
         .map((t) => ({
         name: t.device.name,
         platform: resolveDeviceProfile(t.device).platform,
-        // Fail fast: gate the expensive version+doctor dials on the reachability
-        // verdict the cheap stats probe already computed one step earlier. A box
-        // it found unreachable skips straight to an `unreachable` row instead of
-        // burning 15s+30s per box — so one genuinely-offline device can't stall
-        // the matrix for ~60s (RUSH-1964). See {@link fleetHealthSkip} for why
-        // this is trusted on the default path, not just under `--refresh`.
         skip: fleetHealthSkip(t.skip, statsMap.get(t.device.name)),
         dialTarget: fleetDialTarget(t.device),
         extraSshArgs: deviceIdentityArgs(t.device),
@@ -646,30 +473,16 @@ async function runFleetStatus(opts) {
             });
         }
     }
-    // Auth column: remote rows already carry the host's self-reported rollup from
-    // its `doctor --json`. Fill the rest (this machine; older remotes that don't
-    // emit it) from this host's local cache — written by `agents fleet ping` and
-    // the daemon's local refresh. A never-probed host rolls up to "—". No network.
     const authCache = readAuthHealthCache();
     for (const row of rows) {
         if (!row.auth)
             row.auth = summarizeHostAuth(authCache, row.name);
-        // Resolve the online/offline verdict and last-seen once (RUSH-1966) so the
-        // summary view reads one truth — the same `deviceOnlineState` ordering the
-        // registry write-back uses — instead of re-deriving it from error/skipped.
         const profile = reg[row.name];
         if (profile) {
             row.online = deviceOnlineState(profile, statsMap.get(row.name));
             row.lastSeen = profile.tailscale?.lastSeen ?? profile.reachability?.checkedAt;
         }
     }
-    // Live-agent workload (RUSH-2061): publish THIS host's row, then union peers'
-    // rows cache-first. The daemon no longer probes the fleet (publish-own /
-    // read-union), so cross-host counts are gathered HERE, on demand — a mirror row
-    // younger than the freshness window is served without ssh; a missing/stale one
-    // is read over ssh via `fleet status --local --json` (bounded + kill-on-timeout
-    // through sshExecAsync/fanOutDevices, RUSH-2114). Best-effort: agent counts are
-    // additive, so a failed gather never breaks the status render.
     try {
         const { publishLocalFleetStatus, readFleetStatus, writeFleetStatusRows } = await import('../lib/fleet-status.js');
         const selfRow = await publishLocalFleetStatus(self);
@@ -702,7 +515,6 @@ async function runFleetStatus(opts) {
         }
     }
     catch {
-        // best-effort — agent counts are additive to the health view
     }
     const report = buildFleetHealthReport(rows, new Date(), { self });
     if (opts.json) {
@@ -722,7 +534,6 @@ async function runFleetStatus(opts) {
         }, null, 2));
     }
     else if (opts.verbose) {
-        // Full grid: the auth/CLI/sync/version columns and the warnings rollup.
         for (const line of renderFleetWarnings(report))
             console.log(line);
         console.log();
@@ -730,14 +541,12 @@ async function runFleetStatus(opts) {
             console.log(line);
     }
     else {
-        // Default: rollup + NEEDS ATTENTION + OS-grouped quiet rows + footer.
         for (const line of renderFleetSummary(report, { self }))
             console.log(line);
     }
     if (opts.strict && report.hasWarnings)
         process.exitCode = 1;
 }
-/** SSH into a host and run its local auth probe, returning its rows. */
 async function probeRemoteAuth(target) {
     const isWin = /^win/i.test((target.platform ?? '').trim());
     const env = isWin ? undefined : { PATH: '$HOME/.agents/.cache/shims:$HOME/.local/bin:$PATH' };
@@ -749,27 +558,12 @@ async function probeRemoteAuth(target) {
     const parsed = JSON.parse(res.stdout);
     return parsed.rows ?? [];
 }
-/**
- * Race `fanOut` against an overall wall-clock deadline (RUSH-2041).
- *
- * If `fanOut` settles first the result passes through unchanged. If the
- * deadline fires first every pending remote target is mapped to `failed` (or
- * `skipped` for pre-skipped targets), so callers always get a complete result
- * array and the command exits promptly rather than hanging.
- *
- * Exported so the unit test can exercise the real path with a hanging probe
- * instead of reimplementing the logic.
- */
 export async function raceFleetPingDeadline(fanOut, remoteTargets, overallTimeoutMs) {
     const overallDeadline = new Promise((_, reject) => setTimeout(() => reject(new Error('fleet ping overall deadline exceeded')), overallTimeoutMs));
     try {
         return await Promise.race([fanOut, overallDeadline]);
     }
     catch (err) {
-        // Overall deadline hit before all devices settled — mark every pending
-        // device as failed so the command exits promptly. Individual probes that
-        // already settled are not retrievable (Promise.all internals), so we
-        // record all remote targets as timed out / skipped.
         const errMsg = err instanceof Error ? err.message : String(err);
         return remoteTargets.map((t) => ({
             name: t.name,
@@ -782,20 +576,9 @@ export async function raceFleetPingDeadline(fanOut, remoteTargets, overallTimeou
 async function runFleetPing(opts) {
     const self = machineId();
     const { refreshLocalFleetAuthState } = await import('../lib/daemon-ticks.js');
-    // --local: probe just this host. Used both directly and as the fan-out worker.
-    // force: this command promises "a real request for every account" (--strict
-    // gates on it), so it must never reuse the periodic tick's rate-limit-throttled
-    // cached verdict (RUSH-2998).
     if (opts.local) {
         const { authRows: rows } = await refreshLocalFleetAuthState({ force: true });
         if (opts.json) {
-            // Per-agent launchability from the SAME run-router path the local readiness
-            // check uses (`collectRunCandidates`/`isLaunchableSignedIn`), so a consumer
-            // can tell a box that simply could not probe — a worker's setup-token box,
-            // or a headed box that spent its usage-endpoint budget, both DROP their
-            // `no_evidence` row — from a box with no credential at all. From `rows`
-            // alone the two are indistinguishable, which broke `--host` routine
-            // readiness on every worker (PHNX-4116).
             const { collectRunCandidates } = await import('../lib/accounting/rotate.js');
             const launchable = (await Promise.all(ALL_AGENT_IDS.map(async (agent) => (await collectRunCandidates(agent)).some((candidate) => candidate.signedIn) ? agent : null))).filter((agent) => agent !== null);
             console.log(JSON.stringify({ host: self, rows, launchable }));
@@ -809,15 +592,9 @@ async function runFleetPing(opts) {
         }
         return;
     }
-    // Origin: probe locally, then fan out to the rest of the fleet in parallel.
     const reg = await loadDevices();
     const planned = planFleetTargets(reg);
     const results = [];
-    // force: same as the --local worker below — this command promises a real
-    // request for every account and --strict gates on it, so the self row must
-    // never reuse the periodic tick's rate-limit-throttled cached verdict. Each
-    // remote peer is force-probed via its own `devices ping --local` worker (see
-    // probeRemoteAuth); the self row must match (RUSH-2998).
     const { authRows: localRows } = await refreshLocalFleetAuthState({ force: true });
     results.push({ host: self, rows: localRows });
     const remoteTargets = remoteFleetTargets(planned, self).map((t) => ({
@@ -831,10 +608,6 @@ async function runFleetPing(opts) {
     const spinner = isInteractiveTerminal() && !opts.json
         ? ora(`Pinging ${probeable} device${probeable === 1 ? '' : 's'}…`).start()
         : undefined;
-    // Per-device: 15 s (matches the version probe budget; enough for the ~8 s
-    // provider-fetch inside the remote local auth probe, with headroom).
-    // Overall: 30 s hard cap so the command can never outlast a reasonable
-    // budget when several devices are simultaneously unreachable (RUSH-2041).
     const FLEET_PING_DEVICE_TIMEOUT_MS = 15_000;
     const FLEET_PING_OVERALL_TIMEOUT_MS = 30_000;
     let remote;
@@ -870,7 +643,6 @@ async function runFleetPing(opts) {
     if (opts.strict && anyBad)
         process.exitCode = 1;
 }
-/** SSH into a host and read its raw harness rows (the `--local --json` worker). */
 async function probeRemoteHarnesses(target, refresh) {
     const isWin = /^win/i.test((target.platform ?? '').trim());
     const env = isWin ? undefined : { PATH: '$HOME/.agents/.cache/shims:$HOME/.local/bin:$PATH' };
@@ -885,13 +657,6 @@ async function probeRemoteHarnesses(target, refresh) {
     const parsed = JSON.parse(res.stdout);
     return parsed.rows ?? [];
 }
-/**
- * Gather harness rows across the fleet: THIS host in process, every reachable
- * peer over SSH. Shared by both `harnesses` and `accounts` (they differ only in
- * how the rows are rendered). Honors an optional `--device` allowlist on both
- * the local and remote rows. Bounded by the same per-device + overall deadlines
- * as `fleet ping`, so one unreachable box can never stall the glance.
- */
 export async function collectFleetHarnesses(opts) {
     const self = machineId();
     const want = opts.devices?.length ? new Set(opts.devices) : null;
@@ -989,7 +754,6 @@ export async function runDevicesAccounts(opts) {
             console.log(line);
     }
 }
-/** Resolve an {@link AuthCellColor} to a chalk painter. Single map for cells + labels. */
 const CELL_PAINT = {
     green: chalk.green,
     yellow: chalk.yellow,
@@ -997,14 +761,6 @@ const CELL_PAINT = {
     gray: chalk.gray,
     dim: chalk.dim,
 };
-/**
- * Color a per-host×agent cell. The numerator counts accounts that are usable
- * right now — live-verified PLUS signed-in-but-unverifiable (codex/grok) — over
- * the total, so a logged-in codex fleet reads "1/1", not a scary "0/1". Color is
- * the shared {@link authCellColor}: red only for revoked (re-login), yellow for
- * soft/expired (self-refreshes), gray for present-but-unverifiable, green when
- * all live.
- */
 function authCell(summary, width) {
     if (summary.total === 0)
         return chalk.dim('·'.padEnd(width));
@@ -1012,15 +768,13 @@ function authCell(summary, width) {
     const padded = `${ok}/${summary.total}`.padEnd(width);
     return CELL_PAINT[authCellColor(summary)](padded);
 }
-/** Render the fleet auth matrix (device rows × agent columns) plus an optional per-account breakdown. */
 function renderAuthMatrix(results, opts) {
-    // Only show agent columns that appear somewhere in the results.
     const present = new Set();
     for (const r of results)
         for (const row of r.rows)
             present.add(row.agent);
     const agents = ALL_AGENT_IDS.filter((a) => present.has(a));
-    const cellW = 6; // 6 disambiguates opencode/openclaw (both 'openc' at 5)
+    const cellW = 6;
     const nameW = Math.max(6, ...results.map((r) => r.host.length));
     const lines = [chalk.bold('Fleet auth')];
     const header = `  ${'Device'.padEnd(nameW)}  ${agents.map((a) => a.slice(0, cellW).padEnd(cellW)).join(' ')}`;
@@ -1063,7 +817,6 @@ function renderAuthMatrix(results, opts) {
     }
     return lines;
 }
-/** Register the `agents devices` command tree (also aliased as `fleet`). */
 function registerDevicesCommands(program) {
     const devicesCmd = program
         .command('devices')
@@ -1133,9 +886,7 @@ function registerDevicesCommands(program) {
             process.exit(1);
         }
     });
-    // `agents fleet capture` — snapshot live state into agents.yaml fleet:.
     registerFleetCaptureCommand(devicesCmd);
-    // `agents fleet apply` — canonical fleet reconcile (top-level apply is retired).
     registerFleetApplyAlias(devicesCmd);
     devicesCmd
         .command('register <name>')
@@ -1148,14 +899,11 @@ function registerDevicesCommands(program) {
                 console.error(chalk.red(`'${name}' is not a current tailscale node. See 'agents devices sync'.`));
                 process.exit(1);
             }
-            await removeIgnored(name); // clear THIS box's dismissal, if any
+            await removeIgnored(name);
             const d = await upsertDevice(name, nodeToDeviceInput(node));
             setDeviceDiscoveryStatus(name, 'approved');
-            clearPendingSentinel(name); // drop the notification immediately
+            clearPendingSentinel(name);
             console.log(chalk.green(`Registered '${name}'`) + chalk.gray(` (${d.platform})`));
-            // A dismissal on another box still wins the union (ignored beats
-            // approved), so approving here does not un-dismiss it fleet-wide — say so
-            // rather than imply the node is now discoverable everywhere (PHNX-3315).
             const otherDismissals = loadIgnoredEntries().filter((e) => e.name === name);
             if (otherDismissals.length > 0 || getDeviceDiscoveryStatus(name) === 'ignored') {
                 const boxes = [...new Set(otherDismissals.map((e) => e.ignoredOn))].sort().join(', ') || 'another box';
@@ -1176,7 +924,7 @@ function registerDevicesCommands(program) {
             await removeDevice(name);
             await addIgnored(name);
             setDeviceDiscoveryStatus(name, 'ignored');
-            clearPendingSentinel(name); // drop the notification immediately
+            clearPendingSentinel(name);
             console.log(chalk.green(`Ignored '${name}'`) + chalk.gray(" — it won't be suggested again. Undo with `agents devices unignore`."));
         }
         catch (err) {
@@ -1189,13 +937,8 @@ function registerDevicesCommands(program) {
         .description('Undo `ignore`: allow a node to be discovered and registered again.')
         .action(async (name) => {
         const wasIgnored = getDeviceDiscoveryStatus(name) === 'ignored' || loadIgnoredEntries().some((e) => e.name === name);
-        // A box can edit only its OWN device doc (PHNX-3315), so this clears just
-        // this box's dismissal/approval decision.
         await removeIgnored(name);
         setDeviceDiscoveryStatus(name, undefined);
-        // Re-evaluate the cross-box union AFTER clearing our slice: another box's
-        // dismissal keeps the node ignored fleet-wide (ignored beats approved), so
-        // never report a false "no longer ignoring" — name the box(es) to clear.
         const remaining = loadIgnoredEntries().filter((e) => e.name === name);
         if (remaining.length > 0 || getDeviceDiscoveryStatus(name) === 'ignored') {
             const boxes = [...new Set(remaining.map((e) => e.ignoredOn))].sort().join(', ') || 'another box';
@@ -1252,13 +995,6 @@ function registerDevicesCommands(program) {
       is where dismissals are visible.
     `,
     });
-    // ─── devices config (unified settings surface) ────────────────────────────
-    //
-    // ONE command for every per-device setting: `agents devices config <name>
-    // [key] [value] [--unset] [--json]`. configure, note, set-interactive, set,
-    // prefer, and unprefer are deleted (PHNX-4051) — use this command directly.
-    // enable/disable stay as first-class sugar over auto-launch.enabled.
-    /** Parse a raw CLI string into a config key's typed value (bool/int pass validation, strings verbatim). */
     const parseConfigValueInput = (spec, raw) => {
         switch (spec.type) {
             case 'int': {
@@ -1281,16 +1017,13 @@ function registerDevicesCommands(program) {
     const writeJson = (payload) => {
         process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
     };
-    /** The device-scope config entries for `name` (what the config surface edits). */
     const deviceConfigEntries = (name) => listConfig({ device: name }).filter((e) => e.spec.scope === 'device');
-    /** Render one entry's effective value with its layer tag. */
     const entryValueText = (e) => {
         if (e.source === 'default')
             return chalk.gray('— (default)');
         const tag = e.source === 'fleet' ? chalk.yellow('  (fleet default)') : e.source === 'user' ? chalk.gray('  (user scope)') : '';
         return chalk.cyan(JSON.stringify(e.value)) + tag;
     };
-    /** Print the full resolved config for a device (bare invocation, non-menu). */
     const printDevicesConfig = (name, json) => {
         const entries = deviceConfigEntries(name);
         if (json) {
@@ -1305,7 +1038,6 @@ function registerDevicesCommands(program) {
             console.log(`  ${e.spec.name.padEnd(24)} ${entryValueText(e)}${chalk.gray(`  ${e.spec.description}`)}`);
         }
     };
-    /** Print the fleet-wide defaults layer (`config --fleet`, bare). */
     const printFleetConfig = (json) => {
         const entries = listConfig({ fleet: true }).filter((e) => e.spec.scope === 'device');
         if (json) {
@@ -1321,16 +1053,8 @@ function registerDevicesCommands(program) {
             console.log(`  ${e.spec.name.padEnd(24)} ${value}${chalk.gray(`  ${e.spec.description}`)}`);
         }
     };
-    /**
-     * The `devices config` engine — shared by the config command's action and
-     * every tombstone. `quiet` performs the write with no output (a tombstone
-     * that prints its own legacy shape). `fleet` targets the fleet-wide defaults
-     * layer instead of a device (`name` is then unused). Throws on a bad
-     * key/value; callers map that to exit 1.
-     */
     const runDevicesConfig = async (name, key, valueParts, opts) => {
-        const spec = key ? configKeySpec(key) : undefined; // unknown key → throw listing the valid keys
-        // ── Fleet-defaults layer (`--fleet`): no device involved.
+        const spec = key ? configKeySpec(key) : undefined;
         if (opts.fleet) {
             if (spec && spec.scope === 'user') {
                 throw new Error(`Config key '${spec.name}' is user-scope (already fleet-wide) — --fleet does not apply.`);
@@ -1378,8 +1102,6 @@ function registerDevicesCommands(program) {
             printFleetConfig(Boolean(opts.json));
             return;
         }
-        // User-scope keys (interactive.host) are stored centrally — the device name
-        // is syntax only, so an unregistered name is not an error for them.
         if (!spec || spec.scope === 'device')
             await mustGetDevice(name);
         if (opts.unset) {
@@ -1397,7 +1119,6 @@ function registerDevicesCommands(program) {
         if (spec && valueParts.length > 0) {
             let value;
             if (spec.type === 'string-list') {
-                // List keys (notes) APPEND — one entry per invocation.
                 const existing = getConfigValue(spec.name, { device: name }).value ?? [];
                 value = [...existing, valueParts.join(' ')];
             }
@@ -1425,29 +1146,17 @@ function registerDevicesCommands(program) {
             }
             return;
         }
-        // Bare: TTY → the interactive settings menu; piped/--json → print.
         if (opts.json || !isInteractiveTerminal()) {
             printDevicesConfig(name, Boolean(opts.json));
             return;
         }
         await runDevicesConfigMenu(name);
     };
-    /**
-     * The `devices role` engine — read or write the fleet-wide role mark, and say
-     * what it does to automatic placement.
-     *
-     * A role written here lands in that device's tracked per-device doc
-     * (`devices/<name>/agents.yaml` `config.role`) and syncs with repo
-     * push/pull. The vocabulary is `worker | personal | desktop`.
-     */
     const runDevicesRole = async (name, role, opts) => {
         if (!name) {
             if (role)
                 throw new Error('Name a device: agents devices role <name> <worker|personal|desktop>');
             const reg = await loadDevices();
-            // The full registered roster, not just online — a fleet-wide `role`
-            // default must reach a registered device even when it has no per-device
-            // doc of its own, or it silently falls out of the worker allowlist.
             const roles = listConfiguredDeviceRoles(Object.keys(reg));
             const mode = autoPoolMode();
             const online = Object.entries(reg)
@@ -1491,13 +1200,7 @@ function registerDevicesCommands(program) {
                 console.log(`  ${name.padEnd(20)} ${current ? chalk.cyan(current) : chalk.gray('— (unmarked)')}`);
             return;
         }
-        // configuredDeviceRole's key spec validates the value; a bad one throws with
-        // the accepted list, which the command's catch turns into exit 1.
         setConfiguredDeviceRole(name, role);
-        // Full registered roster, mirroring the bare-listing branch above — a
-        // fleet-wide `role` default must reach a doc-less registered device here
-        // too, or `autoPoolWorkers` under-reports the allowlist right after this
-        // write changed it.
         const roles = listConfiguredDeviceRoles(Object.keys(await loadDevices()));
         if (opts.json) {
             writeJson({ device: name, role, autoPoolWorkers: listWorkerDevices({ roles }) });
@@ -1513,9 +1216,6 @@ function registerDevicesCommands(program) {
         }
         console.log(chalk.gray('Sync it to the fleet with `agents repo push`.'));
     };
-    /** The interactive settings menu: pick a key, edit it, repeat. TTY-only.
-     * Shows EFFECTIVE values (with a fleet tag when inherited); edits always
-     * write the device layer. */
     const runDevicesConfigMenu = async (name) => {
         const { select, input, confirm } = await import('@inquirer/prompts');
         const DONE = '__done__';
@@ -1573,7 +1273,7 @@ function registerDevicesCommands(program) {
         }
         catch (err) {
             if (isPromptCancelled(err))
-                return; // ctrl-c / esc — leave the menu quietly
+                return;
             throw err;
         }
     };
@@ -1589,7 +1289,6 @@ function registerDevicesCommands(program) {
         .action(async (name, key, valueParts, opts) => {
         try {
             if (opts.fleet) {
-                // Positionals shift left: the first one is the key, the rest the value.
                 const fleetValue = [key, ...(valueParts ?? [])].filter((v) => v !== undefined);
                 await runDevicesConfig(undefined, name, fleetValue, opts);
                 return;
@@ -1709,8 +1408,6 @@ function registerDevicesCommands(program) {
         .option('--json', 'output machine-readable JSON')
         .action(async (name, textParts, opts) => {
         try {
-            // Thin sugar over the 'description' config key — the same engine that
-            // backs `agents devices config <name> description`, not a second path.
             await runDevicesConfig(name, 'description', textParts ?? [], opts);
         }
         catch (err) {
@@ -1751,13 +1448,9 @@ function registerDevicesCommands(program) {
         let statsMap;
         let freshness;
         if (opts.stats !== false) {
-            // Cache-first: serve remote devices from the daemon-warmed cache
-            // (instant), probe this machine locally, and only ssh out for missing or
-            // forced (--refresh/--live) rows — so a warm read never hangs on a box.
             const probeable = planFleetTargets(reg)
                 .filter((t) => !t.skip)
                 .map((t) => t.device);
-            // Only spin when we'll actually ssh (forced, or a cold/partial cache).
             const cache = readStatsCache();
             const willSsh = forceRefresh || probeable.some((d) => d.name !== self && (!cache[d.name] || !isFreshDeviceStats(cache[d.name])));
             const spinner = willSsh && isInteractiveTerminal()
@@ -1771,8 +1464,6 @@ function registerDevicesCommands(program) {
             finally {
                 spinner?.stop();
             }
-            // Write the live verdict back so this and every other consumer read one
-            // reachability truth instead of the stale tailscale snapshot (RUSH-1965).
             if (statsMap)
                 await writeReachability(collectReachabilityWriteBacks(reg, statsMap)).catch(() => { });
         }
@@ -1786,9 +1477,6 @@ function registerDevicesCommands(program) {
                 return {
                     ...resolveDeviceProfile(reg[name]),
                     interactive: name === interactiveHost,
-                    // Roles as machine-readable fields: `role` is what the operator
-                    // marked (absent when unmarked), `autoPool` is the answer that
-                    // matters to a caller — may `--device auto` pick this box.
                     ...(jsonRoles[name] ? { role: jsonRoles[name] } : {}),
                     ...(typeof description === 'string' && description ? { description } : {}),
                     autoPool: autoPool.has(name),
@@ -1799,21 +1487,12 @@ function registerDevicesCommands(program) {
             return;
         }
         console.log(chalk.bold(`Devices (${names.length})`));
-        // Dismissed nodes are not devices (never in the registry) — surface their
-        // count under the table so a "missing" node is explainable from the list.
         const ignoredCount = loadIgnoredEntries().length;
         for (const line of renderDeviceTable(reg, names, self, statsMap, opts.full, interactiveHost, { ignoredCount }))
             console.log(line);
         if (freshness?.servedFromCache && freshness.oldestFetchedAt != null) {
             console.log(chalk.gray(`  updated ${formatCheckedAge(freshness.oldestFetchedAt)} — pass --refresh (--live) for a live probe`));
         }
-        // Ephemeral crabbox leases live alongside the registered fleet but are never
-        // written into the registry — surface them as their own live section, but only
-        // behind --all (RUSH-2190). Reading them routes through crabboxEnv, whose
-        // bundle auto-detect scans the keychain and can raise a Touch ID sheet AFTER
-        // the table has printed — unacceptable for the default list, which hooks and
-        // other non-interactive callers rely on. The predicate is exported so the
-        // gate itself is unit-tested; keep it the ONLY condition guarding this call.
         if (showLeasedBoxesSection(opts)) {
             for (const line of loadLeasedBoxesSection())
                 console.log(line);
@@ -1870,10 +1549,6 @@ function registerDevicesCommands(program) {
         .option('--local', "this machine only: print THIS host's status row (resource stats + live-agent workload). The publish endpoint the fleet-status read-union reads over ssh.")
         .option('--verbose', 'show the full per-device auth/CLI/sync/version grid instead of the summary')
         .action(async (opts, cmd) => {
-        // The root program also defines a global `--verbose`; commander binds a
-        // shared long flag to the program, not the leaf. Read the effective value
-        // from the merged globals so `fleet status --verbose` works at either level
-        // (same pattern as `fleet ping --verbose`).
         const verbose = opts.verbose ?? Boolean(cmd.optsWithGlobals().verbose);
         await runFleetStatus({ ...opts, verbose });
     });
@@ -1885,11 +1560,6 @@ function registerDevicesCommands(program) {
         .option('--verbose', 'show a per-account breakdown, not just the per-host rollup')
         .option('--strict', 'exit non-zero when any account is revoked (expired is soft — it self-refreshes)')
         .action(async (opts, cmd) => {
-        // The root program also defines a global `--verbose` (startup self-heal
-        // detail), and commander binds a shared long flag to the program, not the
-        // leaf — so `fleet ping --verbose` never set opts.verbose and the
-        // per-account breakdown was silently unreachable. Read the effective value
-        // from the merged globals so the flag works at either level.
         const verbose = opts.verbose ?? Boolean(cmd.optsWithGlobals().verbose);
         await runFleetPing({ ...opts, verbose });
     });
@@ -1906,8 +1576,6 @@ function registerDevicesCommands(program) {
             plan = await resolveWorkerDevice({ platforms: csvList(opts.platform) });
         }
         catch (err) {
-            // Fail loud with the resolver's own message. Never print a device name
-            // we did not actually pick: a caller reading stdout would ship a tree to it.
             console.error(err instanceof Error ? err.message : String(err));
             process.exitCode = 1;
             return;
@@ -1916,8 +1584,6 @@ function registerDevicesCommands(program) {
             console.log(JSON.stringify(plan, null, 2));
             return;
         }
-        // stdout is the name alone (`box="$(agents devices pick)"`); the human
-        // detail goes to stderr so it never pollutes that capture.
         const detail = plan.candidates
             .map((c) => `${c.device}:${c.loadPercent === undefined ? '?' : `${Math.round(c.loadPercent)}%`}`)
             .join(' ');
@@ -1989,9 +1655,6 @@ email) into a single row. Use \`agents devices harnesses\` for the per-install v
         .option('--platform <platform>', 'windows | linux | macos')
         .action(async (name, target, opts) => {
         try {
-            // The one place a device name is CHOSEN rather than observed, so the one
-            // place the reserved-sentinel policy belongs. upsertDevice itself stays
-            // shape-only — `devices sync` feeds it tailnet node names in a loop.
             assertRegistrableDeviceName(name);
             const { host, user } = splitUserHost(target);
             const isIp = /^\d{1,3}(\.\d{1,3}){3}$/.test(host);
@@ -2085,9 +1748,6 @@ is reported \`failed\` (exit non-zero), never a stranded \`ok\`.
         console.log(chalk.gray(`Running \`${cmd.join(' ')}\` on ${targets.filter((t) => !t.skip).length} online device(s)…`));
         const self = machineId();
         const results = runFleet(targets, cmd, { self });
-        // `exit 0` from the upgrade only proves the npm global moved. Ask each box
-        // what `agents` actually resolves to before calling the rollout a success
-        // (RUSH-2446) — a dev install shadowing the global keeps running old code.
         const verifications = verifyFleetRollout(targets, results, version, { self });
         printFleetResults(results, verifications);
     });
@@ -2171,13 +1831,6 @@ function fmtWtSize(n) {
     }
     return `${v.toFixed(v < 10 ? 1 : 0)}${units[i]}`;
 }
-/**
- * `agents fleet worktrees` — surface the held set the sweep only counts. Never
- * removes anything; `--push` publishes on-no-remote stranded branches. This is
- * the CLI-native surfacing half of PHNX-3520 (the sweep itself lives in
- * phnx-labs/.agents; it still emits a bare count until a sibling change teaches
- * it to consume this).
- */
 async function runWorktreesHeld(opts) {
     if (opts.bucket && !isHeldBucket(opts.bucket)) {
         console.error(chalk.red(`Unknown bucket '${opts.bucket}'. Use one of: ${BUCKET_ORDER.join(', ')}`));
@@ -2236,7 +1889,6 @@ async function runWorktreesHeld(opts) {
         console.log('\n' + chalk.yellow(`${stranded} branch${stranded === 1 ? '' : 'es'} with unmerged commits on no remote. Recover: agents fleet worktrees --push`));
     }
 }
-/** `--push`: publish every on-no-remote stranded branch. Never deletes. */
 async function runWorktreesPush(held, opts) {
     const candidates = held.filter((w) => w.bucket === 'unmerged-commits' && !w.hasRemoteBranch && w.branch);
     if (candidates.length === 0) {
@@ -2267,7 +1919,6 @@ async function runWorktreesPush(held, opts) {
     }
     console.log('\n' + chalk.green(`Published ${pushed}/${candidates.length} stranded branch${candidates.length === 1 ? '' : 'es'}.`));
 }
-/** `--fleet`: run this same read-only surface on every online device, aggregate. */
 async function runWorktreesHeldFleet(opts) {
     const reg = await loadDevices();
     const targets = planFleetTargets(reg);
@@ -2296,10 +1947,6 @@ async function runWorktreesHeldFleet(opts) {
             console.error(chalk.gray(`  ${name}: unparseable output (older CLI?)`));
         }
     }
-    // Apply the bucket filter to the per-device inputs BEFORE aggregating, so
-    // `total`, per-`devices` totals, and `buckets` all describe the same filtered
-    // set — zeroing buckets after the sum leaves `total` counting rows the output
-    // no longer lists.
     const scoped = opts.bucket
         ? perDevice.map((d) => ({ device: d.device, held: d.held.filter((w) => w.bucket === opts.bucket) }))
         : perDevice;
@@ -2322,12 +1969,6 @@ async function runWorktreesHeldFleet(opts) {
         }
     }
 }
-/**
- * `agents devices ps` — list tasks dispatched to devices (`agents run --device
- * <name> --no-follow`). Heals any 'running' record whose local follower died
- * (dropped connection, laptop sleep) against the remote `.exit` before listing,
- * so a finished run never shows stuck at 'running'.
- */
 async function doDeviceTaskPs(json) {
     const tasks = reconcileRunningTasks(listTasks());
     if (json) {
@@ -2347,9 +1988,7 @@ async function doDeviceTaskPs(json) {
         console.log(t.id.padEnd(11) + nameCol + t.host.padEnd(16) + t.agent.padEnd(10) + status.padEnd(11) + promptCol);
     }
 }
-/** `agents devices stop <id>` — terminate a running dispatched task from the origin machine. */
 async function doDeviceTaskStop(ref) {
-    // Heal first so we don't try to kill a process that already exited.
     const current = resolveTaskRef(ref);
     if (!current) {
         console.log(chalk.red(`Unknown task "${ref}".`));
@@ -2380,11 +2019,6 @@ async function doDeviceTaskStop(ref) {
         process.exitCode = 1;
     }
 }
-/**
- * Parse `--argv`'s JSON array, or report exactly what was wrong and return
- * undefined. Fails loud rather than coercing: a caller that meant to pass argv
- * and typo'd the JSON must not silently get shell-string semantics instead.
- */
 export function parseArgvJson(raw, log = (line) => console.error(line)) {
     let parsed;
     try {
@@ -2407,7 +2041,6 @@ export function parseArgvJson(raw, log = (line) => console.error(line)) {
     }
     return parsed;
 }
-/** Register the `agents ssh` smart wrapper. */
 function registerSshWrapper(program) {
     const sshCmd = program
         .command('ssh <name> [cmd...]')
@@ -2444,8 +2077,6 @@ arrives intact. The positional form keeps its existing semantics — the remote
 shell parses it — so the two are mutually exclusive rather than interchangeable.
 `)
         .action(async (name, cmd, opts) => {
-        // `--argv` is a DIFFERENT delivery contract, not a spelling of the
-        // positional form, so accepting both would have to silently pick one.
         if (opts.argv !== undefined && cmd.length > 0) {
             console.error(chalk.red('Pass either --argv <json> or a positional command, not both.'));
             console.error(chalk.gray('--argv delivers exact tokens; the positional form is parsed by the remote shell.'));
@@ -2462,20 +2093,10 @@ shell parses it — so the two are mutually exclusive rather than interchangeabl
             }
             cmd = argvTokens;
         }
-        // Hidden askpass bridge: ssh execs the shim, which re-invokes us here.
         if (name === '__askpass') {
             await runAskpass();
             return;
         }
-        // `auto` is the same affinity sentinel `agents run --device auto` resolves
-        // (RUSH-2185) — pick the concrete device up front via the SAME engine
-        // (resolveDeviceAffinity), rather than leaning on matchHost's generic
-        // self-resolution (../lib/hosts/registry.js): `agents ssh` connects OUT to
-        // a remote device, so a pick that lands on THIS machine is refused with a
-        // clear message instead of self-SSHing — which also holds when this
-        // machine was never itself enrolled as a device (matchHost would have
-        // nothing to resolve "self" to, and mis-report the pick as "Unknown
-        // device").
         let target = name;
         if (isDeviceInteractive(name)) {
             const pinned = resolveInteractiveDevice();
@@ -2495,23 +2116,13 @@ shell parses it — so the two are mutually exclusive rather than interchangeabl
             process.stderr.write(chalk.gray(`[agents] device=auto → ${plan.host}\n`));
             target = plan.host;
         }
-        // Accept the full fleet target grammar: a registered `name`, a
-        // `user@device` (same device, login user overridden — dialed via its
-        // Tailscale route, not LAN DNS), or an ad-hoc `user@host`/`host` literal.
-        // A bare unregistered alias still errors as "Unknown device".
         const resolvedTarget = await resolveDeviceTarget(target);
         if (!resolvedTarget) {
-            // Not a registered device — it may be a leased crabbox box slug. ssh into
-            // it directly (crabbox@<tailnet|ip>:2222) before giving up.
-            trySshLeasedBox(target, cmd); // exits the process on a match
+            trySshLeasedBox(target, cmd);
             console.error(chalk.red(`Unknown device '${target}'. See 'agents devices list'.`));
             process.exit(1);
         }
-        // The effective profile: central config (ssh.*/platform/user) overlaid on
-        // the discovery record.
         const device = resolveDeviceProfile(resolvedTarget);
-        // Preflight: a device Tailscale last saw offline would otherwise hang
-        // for the full ConnectTimeout. Fail fast with a clear message instead.
         if (device.tailscale && !device.tailscale.online) {
             console.error(chalk.red(`Device '${device.name}' is offline (Tailscale last saw it ${device.tailscale.lastSeen ?? 'a while ago'}).`));
             console.error(chalk.gray("Run 'agents devices sync' to refresh reachability."));
@@ -2522,22 +2133,11 @@ shell parses it — so the two are mutually exclusive rather than interchangeabl
         }
         try {
             const shim = writeAskpassShim();
-            // Pin the host key on first connect and verify strictly thereafter: the
-            // managed known_hosts store must exist before ssh writes the learned key
-            // into it, and a host already recorded there is checked with
-            // StrictHostKeyChecking=yes (RUSH-1767).
             ensureManagedKnownHostsDir();
             const addr = hostNameFor(device);
             const pinned = addr ? isHostPinned(addr) : false;
-            // Interactive login (no cmd): mirror the caller's project directory on
-            // the target when the same home-relative checkout exists there, matching
-            // `agents run --device` (deriveMirroredCwd). Best-effort — a missing dir
-            // falls back to the remote home. An explicit `cmd` keeps its cwd (RUSH-2412).
             const mirrorCwd = cmd.length === 0 ? deriveMirroredCwd(process.cwd()) : undefined;
             const { args, env } = buildSshInvocation(device, cmd, shim, { pinned }, { interactiveCwd: mirrorCwd, ...(argvTokens ? { argv: true } : {}) });
-            // Interactive login: make the local terminal's terminfo (e.g.
-            // xterm-ghostty) available on the remote so backspace/colors/clear work.
-            // Best-effort + cached per host — never blocks the login (see terminfo.ts).
             if (cmd.length === 0 && shouldSyncTerminfo({ term: process.env.TERM, shell: device.shell, interactive: process.stdout.isTTY ?? false })) {
                 const { args: tinfoArgs, env: tinfoEnv } = buildSshInvocation(device, ['tic', '-x', '-'], shim, { pinned });
                 syncTerminfoToDevice({ device, host: terminfoHostKey(device, addr), term: process.env.TERM, sshArgs: tinfoArgs, sshEnv: tinfoEnv });
@@ -2553,15 +2153,8 @@ shell parses it — so the two are mutually exclusive rather than interchangeabl
             process.exit(1);
         }
     });
-    // Keep the hidden askpass invocation out of help.
     void sshCmd;
 }
-/**
- * The askpass side of password auth. Invoked by the shim (which ssh execs with
- * SSH_ASKPASS): read the target bundle/key from the environment the wrapper
- * set, resolve it through the existing Keychain path, and print the password
- * to stdout for ssh to consume.
- */
 async function runAskpass() {
     const bundle = process.env[ASKPASS_BUNDLE_ENV];
     const key = process.env[ASKPASS_KEY_ENV] ?? 'password';
@@ -2569,9 +2162,6 @@ async function runAskpass() {
         console.error(`askpass: ${ASKPASS_BUNDLE_ENV} not set`);
         process.exit(1);
     }
-    // A read-only stats probe sets ASKPASS_AGENT_ONLY_ENV to force a broker-only
-    // resolve even under a TTY — so `agents devices` never pops Touch ID just to
-    // render load/mem for an uncached password-auth device (RUSH-1970).
     const agentOnly = true;
     try {
         const { env } = await readAndResolveBundleEnv(bundle, { caller: 'agents ssh', keys: [key], keyMode: 'storage', agentOnly });
@@ -2587,7 +2177,6 @@ async function runAskpass() {
         process.exit(1);
     }
 }
-/** Register both `agents ssh` and `agents devices`. */
 export function registerSshCommands(program) {
     registerSshWrapper(program);
     registerDevicesCommands(program);