@phnx-labs/agents-cli 1.20.28 → 1.20.29

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

@@ -0,0 +1,78 @@
+/** Operating-system family of a device, used to pick the remote shell. */
+export type DevicePlatform = 'windows' | 'linux' | 'macos' | 'unknown';
+/** Remote shell dialect derived from the platform. */
+export type DeviceShell = 'powershell' | 'posix';
+/** How `agents ssh` authenticates to a device. Both are first-class, fully
+ * non-interactive: `key` uses the ssh agent / on-disk keys, `password` pulls
+ * the secret from a Keychain-backed secrets bundle via an askpass shim. */
+export type DeviceAuthMethod = 'key' | 'password';
+/** How to reach a device on the network. */
+export interface DeviceAddress {
+    /** Where the address came from: a Tailscale node, or a manual entry. */
+    via: 'tailscale' | 'manual';
+    /** Fully-qualified DNS name (Tailscale MagicDNS), without a trailing dot. */
+    dnsName?: string;
+    /** Raw IP address (IPv4 preferred). */
+    ip?: string;
+}
+/** Authentication settings for a device. */
+export interface DeviceAuth {
+    method: DeviceAuthMethod;
+    /** Secrets bundle holding the password (when method === 'password'). */
+    bundle?: string;
+    /** Key within the bundle whose value is the password. Defaults to 'password'. */
+    bundleKey?: string;
+}
+/** Last-known Tailscale reachability snapshot for a device. */
+export interface DeviceTailscale {
+    online: boolean;
+    /** True when the last handshake was a direct (non-relayed) connection. */
+    direct: boolean;
+    /** DERP relay region code (e.g. 'sfo'); empty when direct. */
+    relay?: string;
+    lastSeen?: string;
+}
+/** A single registered device. */
+export interface DeviceProfile {
+    name: string;
+    platform: DevicePlatform;
+    shell: DeviceShell;
+    user?: string;
+    address: DeviceAddress;
+    auth: DeviceAuth;
+    tailscale?: DeviceTailscale;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Map of device name to profile. */
+export type DeviceRegistry = Record<string, DeviceProfile>;
+/** Throw if `name` is not usable as an ssh alias (no spaces, quotes, etc.). */
+export declare function assertValidDeviceName(name: string): void;
+/** Map a Tailscale `OS` field to our platform enum. */
+export declare function platformFromOs(os: string | undefined): DevicePlatform;
+/** The remote shell a platform speaks. */
+export declare function shellForPlatform(platform: DevicePlatform): DeviceShell;
+/**
+ * Load all devices from the registry file. Returns an empty object only when
+ * the file does not exist. A malformed file is a hard error — silently
+ * returning {} would let the next write wipe the user's device list.
+ */
+export declare function loadDevices(): Promise<DeviceRegistry>;
+/** Get a single device profile, or null if it is not registered. */
+export declare function getDevice(name: string): Promise<DeviceProfile | null>;
+/** Fields a caller may supply when creating or updating a device. */
+export interface DeviceInput {
+    platform?: DevicePlatform;
+    user?: string;
+    address?: DeviceAddress;
+    auth?: DeviceAuth;
+    tailscale?: DeviceTailscale;
+}
+/**
+ * Create the device if absent, otherwise merge the supplied fields into the
+ * existing profile. `shell` is always re-derived from the (possibly new)
+ * platform so the two can never drift. Returns the resulting profile.
+ */
+export declare function upsertDevice(name: string, input: DeviceInput): Promise<DeviceProfile>;
+/** Remove a device. Returns false if it was not registered. */
+export declare function removeDevice(name: string): Promise<boolean>;

package/dist/lib/devices/registry.js

@@ -0,0 +1,168 @@
+/**
+ * Device registry.
+ *
+ * Manages the persistent registry of SSH device profiles stored at
+ * ~/.agents/.history/devices/registry.json. Each profile records what we had
+ * to re-derive by hand the first time we reached a host: its platform (so we
+ * know PowerShell vs POSIX), the login user, how to address it (Tailscale
+ * DNS name / IP), and how to authenticate (pubkey, or a password pulled from
+ * a secrets bundle).
+ *
+ * Like the team registry this is per-machine runtime state (it embeds a host
+ * list + addresses) and lives under .history/ so it is NOT pulled in by
+ * `agents repo push`. The load/save/lock plumbing is a deliberate clone of
+ * src/lib/teams/registry.ts so the data-loss guarantees match exactly.
+ */
+import * as fs from 'fs/promises';
+import * as fsSync from 'fs';
+import * as path from 'path';
+import { randomBytes } from 'crypto';
+import lockfile from 'proper-lockfile';
+import { getDevicesRegistryPath } from '../state.js';
+function registryPath() {
+    return getDevicesRegistryPath();
+}
+/** Valid logical device name: the ssh-alias charset, so it renders into an
+ * unambiguous `Host` stanza and is safe as an ssh target. */
+const DEVICE_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+/** Throw if `name` is not usable as an ssh alias (no spaces, quotes, etc.). */
+export function assertValidDeviceName(name) {
+    if (!DEVICE_NAME_RE.test(name)) {
+        throw new Error(`Invalid device name ${JSON.stringify(name)}. Use letters, digits, '.', '_', '-' (no spaces) — e.g. 'win-mini'.`);
+    }
+}
+/** Map a Tailscale `OS` field to our platform enum. */
+export function platformFromOs(os) {
+    switch ((os ?? '').toLowerCase()) {
+        case 'windows':
+            return 'windows';
+        case 'linux':
+            return 'linux';
+        case 'macos':
+        case 'darwin':
+            return 'macos';
+        default:
+            return 'unknown';
+    }
+}
+/** The remote shell a platform speaks. */
+export function shellForPlatform(platform) {
+    return platform === 'windows' ? 'powershell' : 'posix';
+}
+/**
+ * Atomic JSON write: write to a unique sibling tmp file then rename over the
+ * target. rename(2) is atomic on POSIX, so a crashed write leaves the old file
+ * untouched instead of producing a half-written registry that loadDevices()
+ * would reject.
+ */
+async function atomicWriteJson(p, data) {
+    await fs.mkdir(path.dirname(p), { recursive: true });
+    const tmp = `${p}.tmp.${process.pid}.${randomBytes(4).toString('hex')}`;
+    await fs.writeFile(tmp, JSON.stringify(data, null, 2));
+    try {
+        await fs.rename(tmp, p);
+    }
+    catch (err) {
+        await fs.unlink(tmp).catch(() => { });
+        throw err;
+    }
+}
+/**
+ * Run `fn` while holding an exclusive cross-process lock on the registry file.
+ * proper-lockfile requires the target to exist, so we touch it first. Stale
+ * locks (from crashed callers) auto-expire after `stale` ms.
+ */
+async function withRegistryLock(p, fn) {
+    await fs.mkdir(path.dirname(p), { recursive: true });
+    if (!fsSync.existsSync(p)) {
+        try {
+            await fs.writeFile(p, '{}', { flag: 'wx' });
+        }
+        catch (err) {
+            if (err && err.code !== 'EEXIST')
+                throw err;
+        }
+    }
+    const release = await lockfile.lock(p, {
+        retries: { retries: 60, minTimeout: 25, maxTimeout: 250, factor: 1.5 },
+        stale: 10_000,
+    });
+    try {
+        return await fn();
+    }
+    finally {
+        await release();
+    }
+}
+/**
+ * Load all devices from the registry file. Returns an empty object only when
+ * the file does not exist. A malformed file is a hard error — silently
+ * returning {} would let the next write wipe the user's device list.
+ */
+export async function loadDevices() {
+    const p = registryPath();
+    let raw;
+    try {
+        raw = await fs.readFile(p, 'utf-8');
+    }
+    catch (err) {
+        if (err && err.code === 'ENOENT')
+            return {};
+        throw err;
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`Device registry corrupted at ${p}: ${err?.message ?? err}. Inspect and restore from backup.`);
+    }
+}
+async function saveDevices(reg) {
+    await atomicWriteJson(registryPath(), reg);
+}
+/** Get a single device profile, or null if it is not registered. */
+export async function getDevice(name) {
+    const reg = await loadDevices();
+    return reg[name] ?? null;
+}
+/**
+ * Create the device if absent, otherwise merge the supplied fields into the
+ * existing profile. `shell` is always re-derived from the (possibly new)
+ * platform so the two can never drift. Returns the resulting profile.
+ */
+export async function upsertDevice(name, input) {
+    assertValidDeviceName(name);
+    const p = registryPath();
+    return withRegistryLock(p, async () => {
+        const reg = await loadDevices();
+        const now = new Date().toISOString();
+        const prev = reg[name];
+        const platform = input.platform ?? prev?.platform ?? 'unknown';
+        const merged = {
+            name,
+            platform,
+            shell: shellForPlatform(platform),
+            user: input.user ?? prev?.user,
+            address: input.address ?? prev?.address ?? { via: 'manual' },
+            auth: input.auth ?? prev?.auth ?? { method: 'key' },
+            tailscale: input.tailscale ?? prev?.tailscale,
+            createdAt: prev?.createdAt ?? now,
+            updatedAt: now,
+        };
+        reg[name] = merged;
+        await saveDevices(reg);
+        return merged;
+    });
+}
+/** Remove a device. Returns false if it was not registered. */
+export async function removeDevice(name) {
+    const p = registryPath();
+    return withRegistryLock(p, async () => {
+        const reg = await loadDevices();
+        if (!reg[name])
+            return false;
+        delete reg[name];
+        await saveDevices(reg);
+        return true;
+    });
+}

package/dist/lib/devices/ssh-config.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Render the device registry into an OpenSSH `ssh_config` include block.
+ *
+ * Writing a managed include (e.g. `~/.ssh/config.d/agents`) makes every tool
+ * that speaks ssh — plain `ssh`/`scp`/`rsync`/`git`, and `agents sessions
+ * --host` — resolve the registry's logical device names transparently, without
+ * each of them learning about the registry. `agents ssh` stays the value-add
+ * layer (preflight, password-from-bundle auth, platform-aware exec) on top.
+ *
+ * `renderSshConfig` is a pure function (registry in, config text out) so the
+ * exact rendering is unit-testable.
+ */
+import { type DeviceProfile, type DeviceRegistry } from './registry.js';
+/** The HostName an ssh client should dial for a device: DNS name first, then IP. */
+export declare function hostNameFor(device: DeviceProfile): string | undefined;
+/**
+ * Render the whole registry into ssh_config text. Devices are emitted in
+ * stable alphabetical order (so the file does not churn between runs) and
+ * addressless devices are skipped.
+ */
+export declare function renderSshConfig(reg: DeviceRegistry): string;

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

@@ -0,0 +1,33 @@
+const HEADER = [
+    '# Managed by `agents devices` — do not edit by hand.',
+    '# Regenerate with: agents devices render',
+    '# Include from ~/.ssh/config with:  Include config.d/agents',
+].join('\n');
+/** The HostName an ssh client should dial for a device: DNS name first, then IP. */
+export function hostNameFor(device) {
+    return device.address.dnsName ?? device.address.ip;
+}
+/** Render a single device into an ssh_config `Host` stanza, or null if it has no address. */
+function renderHost(device) {
+    const hostName = hostNameFor(device);
+    if (!hostName)
+        return null;
+    const lines = [`Host ${device.name}`, `    HostName ${hostName}`];
+    if (device.user)
+        lines.push(`    User ${device.user}`);
+    return lines.join('\n');
+}
+/**
+ * Render the whole registry into ssh_config text. Devices are emitted in
+ * stable alphabetical order (so the file does not churn between runs) and
+ * addressless devices are skipped.
+ */
+export function renderSshConfig(reg) {
+    const stanzas = [];
+    for (const name of Object.keys(reg).sort()) {
+        const stanza = renderHost(reg[name]);
+        if (stanza)
+            stanzas.push(stanza);
+    }
+    return [HEADER, '', ...stanzas, ''].join('\n');
+}

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

@@ -0,0 +1,31 @@
+import { type DeviceInput, type DevicePlatform } from './registry.js';
+/** A single node distilled from `tailscale status --json`. */
+export interface TailscaleNode {
+    name: string;
+    platform: DevicePlatform;
+    dnsName?: string;
+    ip?: string;
+    online: boolean;
+    direct: boolean;
+    relay?: string;
+    lastSeen?: string;
+}
+/**
+ * Slugify a raw Tailscale HostName into a valid logical device name (ssh alias
+ * charset). Used only as a fallback — when a node has a DNSName we prefer its
+ * first label, which is the canonical slug Tailscale itself derived.
+ */
+export declare function slugifyHostName(hostName: string): string;
+/**
+ * Parse `tailscale status --json` output into one node per tailnet device,
+ * including Self. Throws on malformed JSON. Nodes without a HostName are
+ * skipped (they cannot be addressed by a logical name).
+ */
+export declare function parseTailscaleStatus(json: string): TailscaleNode[];
+/** Turn a parsed Tailscale node into the registry fields it can populate. */
+export declare function nodeToDeviceInput(node: TailscaleNode): DeviceInput;
+/**
+ * Run `tailscale status --json` and return its raw stdout. Throws a clear
+ * error when the binary is missing or the daemon is not reachable.
+ */
+export declare function tailscaleStatusJson(): string;

package/dist/lib/devices/tailscale.js

@@ -0,0 +1,126 @@
+/**
+ * Tailscale ingestion for the device registry.
+ *
+ * `tailscale status --json` already hands us most of a device registry for
+ * free — per node: `OS` (→ platform), `Online`/`LastSeen` (→ reachability),
+ * `Relay` vs `CurAddr` (→ direct-vs-relayed latency hint), `DNSName`, and
+ * `TailscaleIPs`. `parseTailscaleStatus` turns that JSON into draft device
+ * profiles so `agents devices sync` can self-populate instead of you
+ * hand-entering hosts. Kept a pure function (JSON in, profiles out) so it is
+ * unit-testable without a live tailnet.
+ */
+import { spawnSync } from 'child_process';
+import { platformFromOs, } from './registry.js';
+/** Strip MagicDNS's trailing dot so the name is usable as an ssh HostName. */
+function trimDnsDot(dns) {
+    if (!dns)
+        return undefined;
+    return dns.endsWith('.') ? dns.slice(0, -1) : dns;
+}
+/** First IPv4 in the node's address list (preferred over IPv6 for ssh). */
+function firstIpv4(ips) {
+    if (!ips)
+        return undefined;
+    return ips.find((ip) => /^\d{1,3}(\.\d{1,3}){3}$/.test(ip)) ?? ips[0];
+}
+/**
+ * Slugify a raw Tailscale HostName into a valid logical device name (ssh alias
+ * charset). Used only as a fallback — when a node has a DNSName we prefer its
+ * first label, which is the canonical slug Tailscale itself derived.
+ */
+export function slugifyHostName(hostName) {
+    return hostName
+        .toLowerCase()
+        .replace(/['’"]/g, '') // drop quotes/apostrophes (so "Bisma's" → "bismas", matching MagicDNS)
+        .replace(/[^a-z0-9._-]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+/**
+ * The logical name for a node. macOS computer names contain spaces and
+ * apostrophes ("Bisma's MacBook Pro") and iOS devices all report HostName
+ * "localhost" — both break as ssh aliases and the latter collides in the
+ * registry. The MagicDNS label (first segment of DNSName) is already a unique,
+ * valid slug per device, so prefer it; fall back to a slugified HostName.
+ */
+function deviceNameFor(raw, dnsName) {
+    const label = dnsName?.split('.')[0];
+    if (label && label.length > 0)
+        return label;
+    const host = raw.HostName?.trim();
+    if (!host)
+        return null;
+    const slug = slugifyHostName(host);
+    return slug.length > 0 ? slug : null;
+}
+function toNode(raw) {
+    const dnsName = trimDnsDot(raw.DNSName);
+    const name = deviceNameFor(raw, dnsName);
+    if (!name)
+        return null;
+    // A non-empty CurAddr means the last handshake was a direct connection;
+    // an empty CurAddr with a Relay means traffic is going through DERP.
+    const direct = Boolean(raw.CurAddr && raw.CurAddr.length > 0);
+    return {
+        name,
+        platform: platformFromOs(raw.OS),
+        dnsName,
+        ip: firstIpv4(raw.TailscaleIPs),
+        online: Boolean(raw.Online),
+        direct,
+        relay: raw.Relay || undefined,
+        lastSeen: raw.LastSeen,
+    };
+}
+/**
+ * Parse `tailscale status --json` output into one node per tailnet device,
+ * including Self. Throws on malformed JSON. Nodes without a HostName are
+ * skipped (they cannot be addressed by a logical name).
+ */
+export function parseTailscaleStatus(json) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch (err) {
+        throw new Error(`Could not parse tailscale status JSON: ${err?.message ?? err}`);
+    }
+    const out = [];
+    if (parsed.Self) {
+        const self = toNode(parsed.Self);
+        if (self)
+            out.push(self);
+    }
+    for (const raw of Object.values(parsed.Peer ?? {})) {
+        const node = toNode(raw);
+        if (node)
+            out.push(node);
+    }
+    return out;
+}
+/** Turn a parsed Tailscale node into the registry fields it can populate. */
+export function nodeToDeviceInput(node) {
+    return {
+        platform: node.platform,
+        address: { via: 'tailscale', dnsName: node.dnsName, ip: node.ip },
+        tailscale: {
+            online: node.online,
+            direct: node.direct,
+            relay: node.relay,
+            lastSeen: node.lastSeen,
+        },
+    };
+}
+/**
+ * Run `tailscale status --json` and return its raw stdout. Throws a clear
+ * error when the binary is missing or the daemon is not reachable.
+ */
+export function tailscaleStatusJson() {
+    const res = spawnSync('tailscale', ['status', '--json'], { encoding: 'utf-8' });
+    if (res.error && res.error.code === 'ENOENT') {
+        throw new Error('tailscale not found on PATH. Install Tailscale, or add devices manually with `agents devices add`.');
+    }
+    if (res.status !== 0) {
+        throw new Error(`tailscale status failed: ${(res.stderr || res.stdout || '').trim() || `exit ${res.status}`}`);
+    }
+    return res.stdout ?? '';
+}

package/dist/lib/secrets/remote.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Remote secrets — read and use `agents secrets` bundles that live on another
+ * host, over the same hardened SSH path that `agents secrets export --host`
+ * (the write inverse) already uses.
+ *
+ * This is the READ / USE direction:
+ *   - browse:  drive the remote `agents secrets list|view` and stream its
+ *              stdout back verbatim (lossless, no parsing).
+ *   - use:     resolve a remote bundle to an env map (JSON over ssh stdout) and
+ *              inject it ephemerally — never written to this machine's keychain.
+ *
+ * Trust model: relies on the operator's existing SSH access to the host (same
+ * boundary as `export --host` / `run --host`). Bundle names are shell-quoted
+ * into the remote command; resolved VALUES return over ssh stdout; a forwarded
+ * file-backend passphrase travels over ssh stdin (first line) so it never lands
+ * in argv / `ps` / remote shell history. Nothing is persisted locally.
+ */
+import { type SshExecResult } from '../ssh-exec.js';
+/**
+ * Resolve a `--host` value to an ssh target string. Tries the `agents hosts`
+ * registry first (enrolled name → ssh-config alias / `user@host`); on a miss,
+ * treats the value as a raw ssh target and validates it against injection.
+ */
+export declare function resolveSshTarget(nameOrAlias: string): Promise<string>;
+/**
+ * Merge `--host <single>` and `--hosts <a,b,c>` into an ordered, de-duplicated
+ * list. Both flags compose; either alone works. Empty when neither is set.
+ */
+export declare function parseHostsOption(opts: {
+    host?: string;
+    hosts?: string;
+}): string[];
+/**
+ * Split a `bundle@host` reference. No `@` → a local bundle (host undefined).
+ * Bundle names can't contain `@` (BUNDLE_NAME_PATTERN), so the FIRST `@`
+ * separates the bundle from the ssh target — and the target itself may be a
+ * `user@host` (e.g. `r2.backups@muqsit@box` → bundle `r2.backups`, host
+ * `muqsit@box`).
+ */
+export declare function splitBundleRef(ref: string): {
+    bundle: string;
+    host?: string;
+};
+/**
+ * Run `agents secrets <args>` on a remote host over ssh and return the raw
+ * result. Used by the browse commands — the remote's human-readable stdout is
+ * streamed back unchanged. `tty` forces an interactive ssh session (`-tt`) so a
+ * remote Touch-ID / passphrase prompt can surface (e.g. `view --reveal`).
+ */
+export declare function remoteSecretsRaw(target: string, args: string[], opts?: {
+    tty?: boolean;
+    input?: string;
+}): SshExecResult;
+/**
+ * Resolve a remote bundle to a plaintext env map by driving the remote's
+ * `agents secrets export <bundle> --plaintext --format json`. Values cross over
+ * ssh stdout (encrypted in transit), parsed in memory, never persisted.
+ *
+ * The remote unlocks the bundle with ITS OWN credentials — the owner host's
+ * keychain/secrets-agent, or its own `AGENTS_SECRETS_PASSPHRASE` (in the login
+ * env) for a file-backed bundle. We deliberately do NOT forward this machine's
+ * passphrase: the remote bundle is encrypted with the remote's passphrase, so
+ * overriding it would break the read. (A macOS remote under non-interactive
+ * SSH will block on Touch-ID — use `view`/`exec` with a remote `file` bundle,
+ * an already-unlocked remote secrets-agent, or an interactive `-tt` session.)
+ */
+export declare function remoteResolveEnv(target: string, bundle: string): Promise<Record<string, string>>;

package/dist/lib/secrets/remote.js

@@ -0,0 +1,133 @@
+/**
+ * Remote secrets — read and use `agents secrets` bundles that live on another
+ * host, over the same hardened SSH path that `agents secrets export --host`
+ * (the write inverse) already uses.
+ *
+ * This is the READ / USE direction:
+ *   - browse:  drive the remote `agents secrets list|view` and stream its
+ *              stdout back verbatim (lossless, no parsing).
+ *   - use:     resolve a remote bundle to an env map (JSON over ssh stdout) and
+ *              inject it ephemerally — never written to this machine's keychain.
+ *
+ * Trust model: relies on the operator's existing SSH access to the host (same
+ * boundary as `export --host` / `run --host`). Bundle names are shell-quoted
+ * into the remote command; resolved VALUES return over ssh stdout; a forwarded
+ * file-backend passphrase travels over ssh stdin (first line) so it never lands
+ * in argv / `ps` / remote shell history. Nothing is persisted locally.
+ */
+import { sshExec, assertValidSshTarget, shellQuote } from '../ssh-exec.js';
+import { resolveHost } from '../hosts/registry.js';
+import { sshTargetFor } from '../hosts/types.js';
+const REMOTE_TIMEOUT_MS = 30_000;
+/**
+ * Resolve a `--host` value to an ssh target string. Tries the `agents hosts`
+ * registry first (enrolled name → ssh-config alias / `user@host`); on a miss,
+ * treats the value as a raw ssh target and validates it against injection.
+ */
+export async function resolveSshTarget(nameOrAlias) {
+    const host = await resolveHost(nameOrAlias);
+    if (host)
+        return sshTargetFor(host);
+    assertValidSshTarget(nameOrAlias);
+    return nameOrAlias;
+}
+/**
+ * Merge `--host <single>` and `--hosts <a,b,c>` into an ordered, de-duplicated
+ * list. Both flags compose; either alone works. Empty when neither is set.
+ */
+export function parseHostsOption(opts) {
+    const out = [];
+    const seen = new Set();
+    const push = (h) => {
+        const t = h.trim();
+        if (t && !seen.has(t)) {
+            seen.add(t);
+            out.push(t);
+        }
+    };
+    if (opts.host)
+        push(opts.host);
+    if (opts.hosts)
+        for (const h of opts.hosts.split(','))
+            push(h);
+    return out;
+}
+/**
+ * Split a `bundle@host` reference. No `@` → a local bundle (host undefined).
+ * Bundle names can't contain `@` (BUNDLE_NAME_PATTERN), so the FIRST `@`
+ * separates the bundle from the ssh target — and the target itself may be a
+ * `user@host` (e.g. `r2.backups@muqsit@box` → bundle `r2.backups`, host
+ * `muqsit@box`).
+ */
+export function splitBundleRef(ref) {
+    const at = ref.indexOf('@');
+    if (at === -1)
+        return { bundle: ref };
+    const bundle = ref.slice(0, at);
+    const host = ref.slice(at + 1);
+    if (!bundle || !host) {
+        throw new Error(`Invalid remote bundle reference ${JSON.stringify(ref)}. Expected 'bundle@host'.`);
+    }
+    return { bundle, host };
+}
+/**
+ * Run `agents secrets <args>` on a remote host over ssh and return the raw
+ * result. Used by the browse commands — the remote's human-readable stdout is
+ * streamed back unchanged. `tty` forces an interactive ssh session (`-tt`) so a
+ * remote Touch-ID / passphrase prompt can surface (e.g. `view --reveal`).
+ */
+export function remoteSecretsRaw(target, args, opts = {}) {
+    const inner = ['agents', 'secrets', ...args].map(shellQuote).join(' ');
+    const remoteCmd = `bash -lc ${shellQuote(inner)}`;
+    return sshExec(target, remoteCmd, {
+        timeoutMs: REMOTE_TIMEOUT_MS,
+        input: opts.input,
+        extraSshArgs: opts.tty ? ['-tt'] : undefined,
+    });
+}
+/**
+ * Resolve a remote bundle to a plaintext env map by driving the remote's
+ * `agents secrets export <bundle> --plaintext --format json`. Values cross over
+ * ssh stdout (encrypted in transit), parsed in memory, never persisted.
+ *
+ * The remote unlocks the bundle with ITS OWN credentials — the owner host's
+ * keychain/secrets-agent, or its own `AGENTS_SECRETS_PASSPHRASE` (in the login
+ * env) for a file-backed bundle. We deliberately do NOT forward this machine's
+ * passphrase: the remote bundle is encrypted with the remote's passphrase, so
+ * overriding it would break the read. (A macOS remote under non-interactive
+ * SSH will block on Touch-ID — use `view`/`exec` with a remote `file` bundle,
+ * an already-unlocked remote secrets-agent, or an interactive `-tt` session.)
+ */
+export async function remoteResolveEnv(target, bundle) {
+    assertValidSshTarget(target);
+    const exportCmd = `agents secrets export ${shellQuote(bundle)} --plaintext --format json`;
+    const res = sshExec(target, `bash -lc ${shellQuote(exportCmd)}`, {
+        timeoutMs: REMOTE_TIMEOUT_MS,
+    });
+    if (res.code !== 0) {
+        const msg = (res.stderr || res.stdout || '').trim();
+        const why = res.timedOut ? 'timed out' : res.code === null ? 'ssh failed' : `exit ${res.code}`;
+        throw new Error(`Failed to resolve '${bundle}' on ${target} (${why})${msg ? `: ${msg}` : ''}`);
+    }
+    // Tolerate login-shell banner noise on stdout: take the outer { … } object.
+    const raw = res.stdout;
+    const start = raw.indexOf('{');
+    const end = raw.lastIndexOf('}');
+    const jsonText = start >= 0 && end >= start ? raw.slice(start, end + 1) : raw.trim();
+    let parsed;
+    try {
+        parsed = JSON.parse(jsonText);
+    }
+    catch {
+        throw new Error(`Could not parse secrets JSON from '${bundle}' on ${target}. ` +
+            `Is the remote agents-cli new enough for 'secrets export --format json'?`);
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`Unexpected payload resolving '${bundle}' on ${target}.`);
+    }
+    const env = {};
+    for (const [k, v] of Object.entries(parsed)) {
+        env[k] = typeof v === 'string' ? v : String(v);
+    }
+    return env;
+}

package/dist/lib/session/db.d.ts

@@ -35,6 +35,7 @@ export interface SessionRow {
 export interface ScanStamp {
     fileMtimeMs: number;
     fileSize: number;
+    scannedAt?: number;
 }
 /** Filter and pagination options for querying the sessions table. */
 export interface QueryOptions {