@phnx-labs/agents-cli 1.20.68 → 1.20.70

package/dist/lib/computer-rpc.js

@@ -163,14 +163,20 @@ export function writeComputerPeers(allowedExecPaths) {
     }
     fs.writeFileSync(resolvePeersPath(), JSON.stringify({ allow: allowedExecPaths }, null, 2), { mode: 0o600 });
 }
-// Resolve the helper executable inside the dist .app bundle. Used by the
-// stdio fallback and by install-helper to find the source bundle.
+// Resolve the helper executable inside the dist .app bundle. Used by the stdio
+// fallback and by install-helper to find the source bundle. Only TRUSTED sources
+// are listed here: a local checkout build and the bundled tarball copy. The
+// download cache is deliberately NOT a candidate — a cached bundle is
+// user-writable and must only ever be read through downloadMacHelperApp(), which
+// re-verifies its signature + Team ID + notarization on every cache hit
+// (lib/computer/download.ts). Listing the cache here would let a same-user
+// process plant a differently-signed .app that install-helper trusts.
 export function resolveHelperExec() {
     const here = path.dirname(fileURLToPath(import.meta.url));
     const candidates = [
         // Local build (running from the agents-cli checkout). apps/cli/dist/lib -> repo root (4 up) -> native/computer-mac.
         path.resolve(here, '..', '..', '..', '..', 'native', 'computer-mac', 'dist', 'ComputerHelper.app', 'Contents', 'MacOS', 'ComputerHelper'),
-        // Bundled with the npm package (later: CDN download lands here).
+        // Bundled with the npm package.
         path.resolve(here, '..', 'computer-helper', 'ComputerHelper.app', 'Contents', 'MacOS', 'ComputerHelper'),
     ];
     for (const c of candidates) {

package/dist/lib/daemon.js

@@ -625,6 +625,42 @@ export async function runDaemon() {
     };
     const launchHealthInterval = setInterval(() => { void runLaunchHealthCheck(); }, 6 * 60 * 60_000);
     const launchHealthKickoff = setTimeout(() => { void runLaunchHealthCheck(); }, 90_000);
+    // Fleet cache warm: keep the caches that `agents devices list`, `fleet status`,
+    // and `agents view` read cache-first actually fresh, so a default read never
+    // has to ssh out. Two cheap refreshes: (1) this host's auth-health verdicts
+    // (also feeds the `doctor --json` Auth rollup other hosts read), and (2) the
+    // fleet resource-stats cache (one bounded parallel probe of the tailnet). Both
+    // best-effort + overlap-guarded like the probes above. ~every 3 min, plus once
+    // ~60s after startup (staggered off launch).
+    let warmingFleetCache = false;
+    const runFleetCacheWarm = async () => {
+        if (warmingFleetCache)
+            return;
+        warmingFleetCache = true;
+        try {
+            const { machineId } = await import('./machine-id.js');
+            const self = machineId();
+            const { probeLocalFleetAuth, writeFleetAuthRows } = await import('./auth-health.js');
+            const { getCliVersion } = await import('./version.js');
+            const authRows = await probeLocalFleetAuth({ cliVersion: getCliVersion() });
+            writeFleetAuthRows(self, authRows);
+            const { loadDevices } = await import('./devices/registry.js');
+            const { planFleetTargets } = await import('./devices/fleet.js');
+            const { loadFleetStats } = await import('./devices/stats-cache.js');
+            const reg = await loadDevices();
+            const probeable = planFleetTargets(reg).filter((t) => !t.skip).map((t) => t.device);
+            const res = await loadFleetStats(probeable, { forceRefresh: true, selfName: self });
+            log('INFO', `fleet cache warm: ${authRows.length} auth row(s), ${res.stats.size} device stat(s)`);
+        }
+        catch (err) {
+            log('ERROR', `fleet cache warm failed: ${err.message}`);
+        }
+        finally {
+            warmingFleetCache = false;
+        }
+    };
+    const fleetCacheInterval = setInterval(() => { void runFleetCacheWarm(); }, 3 * 60_000);
+    const fleetCacheKickoff = setTimeout(() => { void runFleetCacheWarm(); }, 60_000);
     const handleReload = () => {
         log('INFO', 'Reloading jobs (SIGHUP)');
         scheduler.reloadAll();
@@ -657,6 +693,8 @@ export async function runDaemon() {
         clearTimeout(tmuxReconcileKickoff);
         clearInterval(launchHealthInterval);
         clearTimeout(launchHealthKickoff);
+        clearInterval(fleetCacheInterval);
+        clearTimeout(fleetCacheKickoff);
         hostedBroker?.close();
         removeDaemonPid();
         removeHeartbeat();

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

@@ -43,6 +43,21 @@ 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

package/dist/lib/devices/connect.js

@@ -16,6 +16,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { assertValidSshTarget, shellQuote } from '../ssh-exec.js';
+import { getCliLaunch } from '../cli-entry.js';
 import { encodePwshBase64 } from '../pwsh.js';
 import { getCacheDir } from '../state.js';
 import { hostKeyCheckingOpts } from './known-hosts.js';
@@ -92,6 +93,21 @@ export function buildSshInvocation(device, cmd, askpassShimPath, hostKey = {}) {
         args.push(remote);
     return { args, env };
 }
+/**
+ * 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 function buildAskpassShimBody(launch = getCliLaunch(['ssh', '__askpass'])) {
+    const exec = [launch.command, ...launch.args].map(shellQuote).join(' ');
+    return `#!/bin/sh\n# Generated by agents-cli — bridges ssh SSH_ASKPASS back into the CLI.\nexec ${exec}\n`;
+}
 /**
  * Write (idempotently) the askpass shim — a tiny executable that re-invokes
  * this CLI as `agents ssh __askpass`. ssh execs `SSH_ASKPASS` with no usable
@@ -102,10 +118,6 @@ export function writeAskpassShim() {
     const dir = path.join(getCacheDir(), 'devices');
     fs.mkdirSync(dir, { recursive: true });
     const shimPath = path.join(dir, 'askpass.sh');
-    // process.execPath = the node/bun binary; argv[1] = this CLI's entry script.
-    const node = process.execPath;
-    const entry = process.argv[1] ?? '';
-    const body = `#!/bin/sh\n# Generated by agents-cli — bridges ssh SSH_ASKPASS back into the CLI.\nexec ${shellQuote(node)} ${shellQuote(entry)} ssh __askpass\n`;
-    fs.writeFileSync(shimPath, body, { mode: 0o700 });
+    fs.writeFileSync(shimPath, buildAskpassShimBody(), { mode: 0o700 });
     return shimPath;
 }

package/dist/lib/devices/health-report.d.ts

@@ -1,4 +1,5 @@
 import { type DeviceStats } from './health.js';
+import { type HostAuthSummary } from '../auth-health.js';
 export interface FleetCliStatus {
     installed: boolean;
     path: string | null;
@@ -28,6 +29,9 @@ export interface FleetHealthRow {
     clis: Record<string, FleetCliStatus>;
     sync: FleetSyncStatus[];
     orphans: FleetOrphanStatus[];
+    /** Cached auth-health rollup for this host (the Auth column). Undefined when
+     *  the host has never been probed (`agents fleet ping`) or the cache is cold. */
+    auth?: HostAuthSummary;
 }
 export interface FleetWarning {
     kind: 'unreachable' | 'drift' | 'cli' | 'version-skew';
@@ -44,3 +48,10 @@ export interface FleetHealthReport {
 export declare function buildFleetHealthReport(rows: FleetHealthRow[], now?: Date): FleetHealthReport;
 export declare function renderFleetWarnings(report: FleetHealthReport): string[];
 export declare function renderFleetMatrix(report: FleetHealthReport): string[];
+/**
+ * "as of …" line so cache-served output is honest about age and points at the
+ * refresh flag. Stats age comes from `stats.fetchedAt`, auth age from the
+ * cached rollup's `oldestCheckedAt`; either may be absent. Returns null when the
+ * table carries no timestamped data at all (nothing to date).
+ */
+export declare function freshnessFooter(rows: FleetHealthRow[], now?: number): string | null;

package/dist/lib/devices/health-report.js

@@ -1,6 +1,7 @@
 import chalk from 'chalk';
-import { padToWidth, terminalWidth, truncateToWidth } from '../session/width.js';
+import { padToWidth, stringWidth, terminalWidth, truncateToWidth } from '../session/width.js';
 import { fmtBytes, headroom } from './health.js';
+import { formatCheckedAge } from '../auth-health.js';
 function driftRows(row) {
     return row.sync.filter((s) => s.status !== 'fresh');
 }
@@ -121,6 +122,47 @@ function loadLabel(stats) {
     const mem = stats.memPercent === undefined ? '-' : `${Math.round(stats.memPercent)}%`;
     return `${load}/${mem}`;
 }
+/**
+ * Compact per-host auth cell. Four buckets, deliberately distinct so the column
+ * doesn't cry wolf on healthy accounts:
+ *   `●{live}`     green  — live-verified
+ *   `·{present}`  gray   — signed in but no live probe (codex/grok/…): benign
+ *   `◐{degraded}` yellow — soft/self-healing (expired/limited/error)
+ *   `○{revoked}`  red    — server rejected the token: re-login now
+ * A host with no cached auth rows shows "—"; an unreachable/skipped row shows
+ * "-" like the other probe columns.
+ */
+function authLabel(row) {
+    if (row.error || row.skipped)
+        return chalk.gray('-');
+    const s = row.auth;
+    if (!s || s.total === 0)
+        return chalk.gray('—');
+    const parts = [];
+    if (s.live > 0)
+        parts.push(chalk.green(`●${s.live}`));
+    if (s.present > 0)
+        parts.push(chalk.gray(`·${s.present}`));
+    if (s.degraded > 0)
+        parts.push(chalk.yellow(`◐${s.degraded}`));
+    if (s.revoked > 0)
+        parts.push(chalk.red(`○${s.revoked}`));
+    // All-zero can't happen (total > 0); but if only present/degraded exist we
+    // still lead with them — never show an empty cell for a probed host.
+    return parts.length > 0 ? parts.join(' ') : chalk.gray('—');
+}
+/** Oldest epoch-ms timestamp across rows for a field, or null when none present. */
+function oldestAcross(rows, pick) {
+    let oldest = null;
+    for (const row of rows) {
+        const t = pick(row);
+        if (t == null)
+            continue;
+        if (oldest === null || t < oldest)
+            oldest = t;
+    }
+    return oldest;
+}
 export function renderFleetWarnings(report) {
     if (report.warnings.length === 0)
         return [chalk.green('Fleet warnings: none')];
@@ -134,14 +176,19 @@ export function renderFleetMatrix(report) {
         return [chalk.gray('No registered devices. Run `agents devices` to register some.')];
     const nameW = Math.min(22, Math.max(6, ...report.devices.map((r) => r.name.length)));
     const versionW = Math.min(14, Math.max(7, ...report.devices.map((r) => (r.version ?? '-').length)));
+    // Auth cells are variable-length (up to four space-separated buckets, e.g.
+    // `●2 ·3 ◐1 ○1`); size the column to the widest so a mixed-auth row can't
+    // overflow the fixed slot and shove every later column out of alignment.
+    const authW = Math.max(9, ...report.devices.map((r) => stringWidth(authLabel(r))));
     const width = terminalWidth();
     // 4 = leading "  " + the per-row status glyph + its trailing space (rows prefix
     // `  ${statusGlyph} `; the header reserves the same 4 cols so every column lines up).
-    const fixed = 4 + nameW + 2 + 8 + 2 + 9 + 2 + 9 + 2 + versionW + 2 + 9 + 2 + 9;
+    // Columns: Device, OS(8), Health(9), Sync(9), CLI(9), Auth(authW), Version, Load/Mem(9), then Note.
+    const fixed = 4 + nameW + 2 + 8 + 2 + 9 + 2 + 9 + 2 + 9 + 2 + authW + 2 + versionW + 2 + 9;
     const noteW = Math.max(12, width - fixed);
     const lines = [
         chalk.bold('Fleet status'),
-        chalk.gray(`    ${padToWidth('Device', nameW)}  ${padToWidth('OS', 8)}  ${padToWidth('Health', 9)}  ${padToWidth('Sync', 9)}  ${padToWidth('CLI', 9)}  ${padToWidth('Version', versionW)}  ${padToWidth('Load/Mem', 9)}  Note`),
+        chalk.gray(`    ${padToWidth('Device', nameW)}  ${padToWidth('OS', 8)}  ${padToWidth('Health', 9)}  ${padToWidth('Sync', 9)}  ${padToWidth('CLI', 9)}  ${padToWidth('Auth', authW)}  ${padToWidth('Version', versionW)}  ${padToWidth('Load/Mem', 9)}  Note`),
     ];
     for (const row of report.devices) {
         const note = row.error ?? row.skipped ?? (row.orphans.length > 0 ? `${row.orphans.length} orphaned version${row.orphans.length === 1 ? '' : 's'}` : '');
@@ -150,10 +197,32 @@ export function renderFleetMatrix(report) {
             `${padToWidth(headroomLabel(row), 9)}  ` +
             `${padToWidth(driftLabel(row), 9)}  ` +
             `${padToWidth(cliLabel(row), 9)}  ` +
+            `${padToWidth(authLabel(row), authW)}  ` +
             `${padToWidth(truncateToWidth(row.version ?? '-', versionW), versionW)}  ` +
             `${padToWidth(loadLabel(row.stats), 9)}  ` +
             chalk.gray(truncateToWidth(note || `free ${fmtBytes(row.stats?.memFreeBytes)}`, noteW)));
     }
-    lines.push(chalk.gray('  ● fresh · ◐ drift · ○ unreachable/skipped'));
+    lines.push(chalk.gray('  ● fresh · ◐ drift · ○ unreachable/skipped · Auth ●live ·present ◐degraded ○revoked'));
+    const foot = freshnessFooter(report.devices);
+    if (foot)
+        lines.push(chalk.gray(foot));
     return lines;
 }
+/**
+ * "as of …" line so cache-served output is honest about age and points at the
+ * refresh flag. Stats age comes from `stats.fetchedAt`, auth age from the
+ * cached rollup's `oldestCheckedAt`; either may be absent. Returns null when the
+ * table carries no timestamped data at all (nothing to date).
+ */
+export function freshnessFooter(rows, now = Date.now()) {
+    const oldestStats = oldestAcross(rows, (r) => r.stats?.fetchedAt);
+    const oldestAuth = oldestAcross(rows, (r) => r.auth?.oldestCheckedAt);
+    const parts = [];
+    if (oldestStats != null)
+        parts.push(`stats ${formatCheckedAge(oldestStats, now)}`);
+    if (oldestAuth != null)
+        parts.push(`auth ${formatCheckedAge(oldestAuth, now)}`);
+    if (parts.length === 0)
+        return null;
+    return `  updated ${parts.join(' · ')} — pass --refresh (--live) for a live probe`;
+}

package/dist/lib/devices/stats-cache.d.ts

@@ -0,0 +1,36 @@
+import { probeFleetStats, probeLocalStats, type DeviceStats } from './health.js';
+import type { DeviceProfile } from './registry.js';
+/** Read the whole cache (best-effort; a missing/corrupt file yields an empty map). */
+export declare function readStatsCache(): Record<string, DeviceStats>;
+/**
+ * Merge freshly-probed rows into the on-disk cache (best-effort write). Rows for
+ * devices not in `entries` are preserved, so a partial probe (gap-fill, or a
+ * single-device refresh) never drops the rest of the fleet's cached stats.
+ */
+export declare function writeStatsCache(entries: Record<string, DeviceStats>): void;
+export interface FleetStatsResult {
+    /** name → stats for every requested device (cache-served + freshly probed). */
+    stats: Map<string, DeviceStats>;
+    /** Oldest `fetchedAt` among the returned rows, or null when empty. Drives the
+     *  "as of …" freshness note. */
+    oldestFetchedAt: number | null;
+    /** True when at least one row was served from cache rather than probed this call. */
+    servedFromCache: boolean;
+}
+export interface LoadFleetStatsOptions {
+    /** Skip the cache and live-probe every device (the `--refresh`/`--live` path). */
+    forceRefresh?: boolean;
+    /** Device name of THIS machine — always probed locally (no ssh), never cached-served. */
+    selfName?: string;
+    /** Injectable probes + cache IO for tests (default to the real ssh/local/disk ones). */
+    probeFleet?: typeof probeFleetStats;
+    probeLocal?: typeof probeLocalStats;
+    readCache?: typeof readStatsCache;
+    writeCache?: typeof writeStatsCache;
+}
+/**
+ * Load fleet stats cache-first. See the module doc for the default vs
+ * `--refresh` behaviour. Never throws — an unreachable box degrades to a
+ * `reachable: false` row exactly as the live probe does.
+ */
+export declare function loadFleetStats(devices: DeviceProfile[], opts?: LoadFleetStatsOptions): Promise<FleetStatsResult>;

package/dist/lib/devices/stats-cache.js

@@ -0,0 +1,115 @@
+/**
+ * Disk cache for fleet {@link DeviceStats} so `agents devices list` and
+ * `agents fleet status` render instantly from the last probe instead of
+ * live-SSHing every registered box on every invocation.
+ *
+ * The old behaviour probed the whole fleet over ssh on every call
+ * ({@link probeFleetStats}) — with a dozen devices, a few of them cold or
+ * timing out, that turned a status glance into a multi-second hang. This module
+ * makes the reads cache-first:
+ *
+ * - **Default:** serve remote devices from the cache (instant); always probe
+ *   *this* machine locally (no ssh, sub-ms) so the "this machine" row is live;
+ *   probe only the remote devices missing from the cache (first run / a
+ *   newly-added box), then persist them.
+ * - **`--refresh` / `--live`:** skip the cache and live-probe every device,
+ *   rewriting the cache.
+ *
+ * The daemon warms this cache (~every 3 min, see `lib/daemon.ts
+ * runFleetCacheWarm`), so in steady state a default read has zero
+ * remote ssh round-trips and returns immediately with data that is at most a
+ * few minutes old — surfaced to the user as an "as of …" freshness note.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getCacheDir } from '../state.js';
+import { probeFleetStats, probeLocalStats } from './health.js';
+const CACHE_FILE = '.fleet-stats.json';
+function cacheFilePath() {
+    return path.join(getCacheDir(), CACHE_FILE);
+}
+/** Read the whole cache (best-effort; a missing/corrupt file yields an empty map). */
+export function readStatsCache() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(cacheFilePath(), 'utf-8'));
+        if (parsed && parsed.entries && typeof parsed.entries === 'object')
+            return parsed.entries;
+    }
+    catch {
+        // missing or corrupt — treat as empty
+    }
+    return {};
+}
+/**
+ * Merge freshly-probed rows into the on-disk cache (best-effort write). Rows for
+ * devices not in `entries` are preserved, so a partial probe (gap-fill, or a
+ * single-device refresh) never drops the rest of the fleet's cached stats.
+ */
+export function writeStatsCache(entries) {
+    try {
+        const dir = getCacheDir();
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        const merged = {
+            version: 1,
+            entries: { ...readStatsCache(), ...entries },
+        };
+        fs.writeFileSync(cacheFilePath(), JSON.stringify(merged, null, 2));
+    }
+    catch {
+        // best-effort; a failed write just means the next read falls back to a live probe
+    }
+}
+/**
+ * Load fleet stats cache-first. See the module doc for the default vs
+ * `--refresh` behaviour. Never throws — an unreachable box degrades to a
+ * `reachable: false` row exactly as the live probe does.
+ */
+export async function loadFleetStats(devices, opts = {}) {
+    const probeFleet = opts.probeFleet ?? probeFleetStats;
+    const probeLocal = opts.probeLocal ?? probeLocalStats;
+    const readCache = opts.readCache ?? readStatsCache;
+    const writeCache = opts.writeCache ?? writeStatsCache;
+    const self = opts.selfName;
+    const cache = opts.forceRefresh ? {} : readCache();
+    const stats = new Map();
+    const toProbe = [];
+    let servedFromCache = false;
+    for (const d of devices) {
+        if (d.name === self) {
+            // This machine is always probed locally — cheap, no ssh, always live.
+            toProbe.push(d);
+            continue;
+        }
+        const cached = cache[d.name];
+        if (cached) {
+            stats.set(d.name, cached);
+            servedFromCache = true;
+        }
+        else {
+            toProbe.push(d);
+        }
+    }
+    if (toProbe.length > 0) {
+        const probed = await probeFleet(toProbe, { selfName: self });
+        const fresh = {};
+        for (const [name, s] of probed) {
+            stats.set(name, s);
+            fresh[name] = s;
+        }
+        if (Object.keys(fresh).length > 0)
+            writeCache(fresh);
+    }
+    // Guarantee a row for this machine even when it isn't in the passed device
+    // list (e.g. self not registered as an ssh target) — matches the old callers'
+    // explicit local fallback.
+    if (self && !stats.has(self)) {
+        stats.set(self, await probeLocal(self));
+    }
+    let oldest = null;
+    for (const s of stats.values()) {
+        if (oldest === null || s.fetchedAt < oldest)
+            oldest = s.fetchedAt;
+    }
+    return { stats, oldestFetchedAt: oldest, servedFromCache };
+}

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

@@ -0,0 +1,44 @@
+import { type DeviceProfile } from './registry.js';
+/**
+ * Decide whether an interactive login warrants a terminfo push. Pure so the
+ * gating logic is unit-testable without touching ssh or the filesystem.
+ *
+ * @param interactive true only for a real login (no remote command) on a human tty.
+ */
+export declare function shouldSyncTerminfo(params: {
+    term?: string;
+    shell: DeviceProfile['shell'];
+    interactive: boolean;
+}): boolean;
+/**
+ * Cache key for a device: the remote **user@host**, not just the host. terminfo
+ * is compiled into the *per-user* `~/.terminfo`, so `alice@box` and `bob@box`
+ * are distinct sync targets — keying on host alone would let the first user's
+ * stamp suppress the second user's (never-installed) sync. Mirrors
+ * {@link sshTargetFor}'s user handling; falls back to the device name when the
+ * address is unresolved.
+ */
+export declare function terminfoHostKey(device: Pick<DeviceProfile, 'user' | 'name'>, addr: string | undefined): string;
+/** True when a fresh successful-sync stamp exists for this host+TERM. */
+export declare function terminfoSynced(host: string, term: string, cacheRoot?: string): boolean;
+/** Record a successful sync so repeat logins skip the push. Best-effort. */
+export declare function markTerminfoSynced(host: string, term: string, cacheRoot?: string): void;
+/** Export the local terminfo source for a TERM, or null if it can't be produced. */
+export declare function localTerminfoSource(term: string): string | null;
+/**
+ * Best-effort: ensure `device` has the terminfo entry for the local `$TERM`
+ * before an interactive login. Never throws; returns whether a push succeeded
+ * (false when skipped, already-cached, or failed). `sshArgs`/`sshEnv` are the
+ * SAME host-key + auth options the real login uses, minus the interactive tty —
+ * so a password-auth device resolves through the askpass shim without a second
+ * human prompt.
+ */
+export declare function syncTerminfoToDevice(opts: {
+    device: DeviceProfile;
+    host: string;
+    term: string | undefined;
+    /** ssh argv for a non-interactive `tic -x -` exec against this device. */
+    sshArgs: string[];
+    /** Env overlay for that ssh (askpass wiring for password devices). */
+    sshEnv: Record<string, string>;
+}): boolean;

package/dist/lib/devices/terminfo.js

@@ -0,0 +1,167 @@
+/**
+ * Terminfo propagation for `agents ssh` interactive logins.
+ *
+ * Modern terminals (Ghostty, kitty, Alacritty, WezTerm, foot, rio) advertise a
+ * custom `TERM` (e.g. `xterm-ghostty`) whose terminfo entry ships with the
+ * terminal, not with the remote host's ncurses. SSH into a box that lacks the
+ * entry and the session is subtly broken: wrong backspace, missing colors, a
+ * garbled clear/alt-screen. Ghostty's own shell integration fixes this for the
+ * bare `ssh` command, but `agents ssh` (Tailscale-relayed, spawned directly)
+ * bypasses that wrapper — so we handle it here.
+ *
+ * Strategy: on an interactive POSIX login, if the local `$TERM` is one the
+ * remote is unlikely to have, export it locally (`infocmp -x`) and compile it on
+ * the remote (`tic -x -`, writes to the user's `~/.terminfo`, no sudo). This is
+ * the canonical, terminal-agnostic technique.
+ *
+ * Two invariants keep it safe and cheap:
+ *  - **Fail-safe.** Every failure is swallowed. A push that errors, times out,
+ *    or hits a remote without `tic` leaves the user exactly where they are today
+ *    — it never blocks or delays the actual login beyond the short push timeout.
+ *  - **Cached.** A successful sync stamps a local marker keyed by host+TERM, so
+ *    only the first login to each host pays the one extra round-trip; every
+ *    repeat login is zero-cost.
+ */
+import { spawnSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import { getCacheDir } from '../state.js';
+/**
+ * Terminfo names that ncurses ships essentially everywhere, so pushing them is
+ * wasted work. Anything NOT in this set (the exotic terminal entries) is a sync
+ * candidate. Kept deliberately conservative: when unsure, we push — `tic` is
+ * idempotent and the result is cached.
+ */
+const UNIVERSAL_TERMS = new Set([
+    'dumb',
+    'ansi',
+    'vt100',
+    'vt102',
+    'vt220',
+    'linux',
+    'cygwin',
+    'xterm',
+    'xterm-color',
+    'xterm-16color',
+    'xterm-256color',
+    'screen',
+    'screen-256color',
+    'tmux',
+    'tmux-256color',
+    'rxvt',
+    'rxvt-unicode',
+    'rxvt-unicode-256color',
+]);
+/** How long a successful sync suppresses re-syncing the same host+TERM. */
+const CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+/** Cap on the push so a stalled remote can't delay the login indefinitely. */
+const PUSH_TIMEOUT_MS = 8000;
+/**
+ * Decide whether an interactive login warrants a terminfo push. Pure so the
+ * gating logic is unit-testable without touching ssh or the filesystem.
+ *
+ * @param interactive true only for a real login (no remote command) on a human tty.
+ */
+export function shouldSyncTerminfo(params) {
+    if (!params.interactive)
+        return false;
+    if (params.shell === 'powershell')
+        return false; // Windows console ignores terminfo
+    const term = params.term?.trim();
+    if (!term)
+        return false;
+    if (UNIVERSAL_TERMS.has(term))
+        return false;
+    return true;
+}
+/**
+ * Cache key for a device: the remote **user@host**, not just the host. terminfo
+ * is compiled into the *per-user* `~/.terminfo`, so `alice@box` and `bob@box`
+ * are distinct sync targets — keying on host alone would let the first user's
+ * stamp suppress the second user's (never-installed) sync. Mirrors
+ * {@link sshTargetFor}'s user handling; falls back to the device name when the
+ * address is unresolved.
+ */
+export function terminfoHostKey(device, addr) {
+    const host = addr ?? device.name;
+    return device.user ? `${device.user}@${host}` : host;
+}
+/** Directory holding per-host+TERM sync stamps. `cacheRoot` override is for tests. */
+function stampDir(cacheRoot) {
+    return path.join(cacheRoot ?? getCacheDir(), 'devices', 'terminfo');
+}
+/** Filesystem-safe stamp name for a host+TERM pair. */
+function stampFile(host, term, cacheRoot) {
+    const safe = `${host}__${term}`.replace(/[^A-Za-z0-9._-]/g, '_');
+    return path.join(stampDir(cacheRoot), safe);
+}
+/** True when a fresh successful-sync stamp exists for this host+TERM. */
+export function terminfoSynced(host, term, cacheRoot) {
+    try {
+        const st = fs.statSync(stampFile(host, term, cacheRoot));
+        return Date.now() - st.mtimeMs < CACHE_TTL_MS;
+    }
+    catch {
+        return false;
+    }
+}
+/** Record a successful sync so repeat logins skip the push. Best-effort. */
+export function markTerminfoSynced(host, term, cacheRoot) {
+    try {
+        fs.mkdirSync(stampDir(cacheRoot), { recursive: true });
+        fs.writeFileSync(stampFile(host, term, cacheRoot), `${new Date().toISOString()}\n`);
+    }
+    catch {
+        /* a cache write failure just means we re-sync next time — never fatal */
+    }
+}
+/** Export the local terminfo source for a TERM, or null if it can't be produced. */
+export function localTerminfoSource(term) {
+    try {
+        const res = spawnSync('infocmp', ['-x', term], {
+            encoding: 'utf8',
+            timeout: 4000,
+        });
+        if (res.status === 0 && res.stdout && res.stdout.trim().length > 0) {
+            return res.stdout;
+        }
+    }
+    catch {
+        /* infocmp missing or errored — nothing we can push */
+    }
+    return null;
+}
+/**
+ * Best-effort: ensure `device` has the terminfo entry for the local `$TERM`
+ * before an interactive login. Never throws; returns whether a push succeeded
+ * (false when skipped, already-cached, or failed). `sshArgs`/`sshEnv` are the
+ * SAME host-key + auth options the real login uses, minus the interactive tty —
+ * so a password-auth device resolves through the askpass shim without a second
+ * human prompt.
+ */
+export function syncTerminfoToDevice(opts) {
+    const term = opts.term?.trim();
+    if (!term)
+        return false;
+    if (terminfoSynced(opts.host, term))
+        return false;
+    const source = localTerminfoSource(term);
+    if (!source)
+        return false;
+    try {
+        const res = spawnSync('ssh', opts.sshArgs, {
+            input: source,
+            env: { ...process.env, ...opts.sshEnv },
+            timeout: PUSH_TIMEOUT_MS,
+            stdio: ['pipe', 'ignore', 'ignore'],
+        });
+        if (res.status === 0) {
+            markTerminfoSynced(opts.host, term);
+            return true;
+        }
+    }
+    catch {
+        /* connection failed / timed out — fail-safe, login proceeds unaffected */
+    }
+    return false;
+}