@phnx-labs/agents-cli 1.20.32 → 1.20.34

package/dist/lib/session/provenance.js

@@ -0,0 +1,157 @@
+/**
+ * Session provenance — where an active agent process actually lives.
+ *
+ * `detectHost()` in active.ts walks the ppid chain to name the *terminal app*
+ * (iterm / code / tmux). That answers "what UI is above it" but not the three
+ * things the Agent Feed needs to group and route:
+ *
+ *   1. Which machine    — os.hostname(), for the HOSTS sidebar.
+ *   2. Local vs SSH     — is SSH_CONNECTION in the process env?
+ *   3. Exact tmux pane  — TMUX_PANE ('%3'), the send-keys target.
+ *
+ * All three are inherited env vars, so we read them straight off the running
+ * process (no cooperation from the agent needed): `/proc/<pid>/environ` on
+ * Linux, `ps eww` on macOS. The read is best-effort — a process we can't stat
+ * (gone, or owned by another uid) yields `undefined`, never a guess.
+ *
+ * `reply` is a read-only hint, not a send channel: it reports whether a rail
+ * that can type back into this session exists today (tmux pane => addressable;
+ * inherited/ignored stdin => null). The feed uses it to decide whether to show
+ * a Send box. Actually delivering the keystrokes is Gap 2 (pty/tmux send-keys).
+ */
+import * as os from 'os';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { readFile } from 'fs/promises';
+const execFileAsync = promisify(execFile);
+/** Env vars that carry provenance. Kept small so the macOS `ps` scan stays cheap. */
+export const PROVENANCE_ENV_KEYS = [
+    'SSH_CONNECTION',
+    'SSH_TTY',
+    'TMUX',
+    'TMUX_PANE',
+    'TERM_PROGRAM',
+    'STY',
+];
+/** Parse the NUL-separated body of /proc/<pid>/environ into a plain object. */
+export function parseProcEnviron(buf) {
+    const env = {};
+    for (const pair of buf.split('\0')) {
+        if (!pair)
+            continue;
+        const eq = pair.indexOf('=');
+        if (eq <= 0)
+            continue;
+        env[pair.slice(0, eq)] = pair.slice(eq + 1);
+    }
+    return env;
+}
+/**
+ * How many whitespace-separated tokens each key's value spans. macOS
+ * `ps eww -o command=` space-joins the env after the command, so a value that
+ * itself contains spaces (SSH_CONNECTION is four fields) can't be recovered by
+ * boundary-guessing when the next token is an *unknown* var. Every provenance
+ * key except SSH_CONNECTION is a single token, so we read exactly its arity.
+ */
+const ENV_VALUE_TOKENS = { SSH_CONNECTION: 4 };
+/**
+ * Pull known env vars out of a macOS `ps eww` command+env line. For each
+ * `KEY=` match we consume the declared number of tokens (default 1), so
+ * SSH_CONNECTION's internal spaces survive while a following unknown var
+ * (e.g. `PWD=…`) is not swallowed into the previous value.
+ */
+export function extractKnownEnv(text, keys) {
+    const alt = keys.map((k) => k.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|');
+    const boundary = new RegExp(`(?:^|\\s)(${alt})=`, 'g');
+    const env = {};
+    let m;
+    while ((m = boundary.exec(text)) !== null) {
+        const key = m[1];
+        const rest = text.slice(m.index + m[0].length);
+        const tokens = rest.split(/\s+/);
+        const want = ENV_VALUE_TOKENS[key] ?? 1;
+        env[key] = tokens.slice(0, want).join(' ');
+    }
+    return env;
+}
+/** `<client_ip> <client_port> <server_ip> <server_port>` → structured origin. */
+export function parseSshConnection(value) {
+    const parts = value.trim().split(/\s+/);
+    if (parts.length < 4)
+        return undefined;
+    const clientPort = parseInt(parts[1], 10);
+    const serverPort = parseInt(parts[3], 10);
+    if (!Number.isFinite(clientPort) || !Number.isFinite(serverPort))
+        return undefined;
+    return { clientIp: parts[0], clientPort, serverIp: parts[2], serverPort };
+}
+/** Build a SessionProvenance from a raw env map + the local hostname. Pure. */
+export function deriveProvenance(env, hostname) {
+    const ssh = env.SSH_CONNECTION ? parseSshConnection(env.SSH_CONNECTION) : undefined;
+    let mux;
+    if (env.TMUX) {
+        mux = {
+            kind: 'tmux',
+            socket: env.TMUX.split(',')[0] || undefined,
+            pane: env.TMUX_PANE || undefined,
+        };
+    }
+    else if (env.STY) {
+        mux = { kind: 'screen', session: env.STY };
+    }
+    // A tmux pane is the one rail that lets an external process type into an
+    // already-running interactive agent (`tmux send-keys -t <pane>`). Everything
+    // else (inherited stdin from `agents run`, ignored stdin from teams) is not
+    // externally addressable without relaunching under a pty/tmux rail.
+    const reply = mux?.kind === 'tmux' && mux.pane
+        ? { rail: 'tmux', target: mux.pane, socket: mux.socket }
+        : null;
+    return {
+        host: hostname,
+        transport: ssh ? 'ssh' : 'local',
+        ssh,
+        term: env.TERM_PROGRAM || undefined,
+        mux,
+        reply,
+    };
+}
+/** Read a process's environment. Linux: /proc. macOS: `ps eww`. Best-effort. */
+async function readProcEnv(pid) {
+    if (process.platform === 'linux') {
+        try {
+            const buf = await readFile(`/proc/${pid}/environ`, 'utf8');
+            return parseProcEnviron(buf);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (process.platform === 'darwin') {
+        try {
+            const { stdout } = await execFileAsync('ps', ['eww', '-p', String(pid), '-o', 'command='], {
+                encoding: 'utf8',
+                maxBuffer: 1024 * 1024,
+            });
+            if (!stdout.trim())
+                return undefined;
+            return extractKnownEnv(stdout, PROVENANCE_ENV_KEYS);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+/**
+ * Resolve provenance for a live pid. Returns undefined when the process env
+ * can't be read (process gone, foreign uid, unsupported platform) — we never
+ * fabricate a 'local' answer we can't back with the env.
+ */
+export async function detectProvenance(pid) {
+    if (!pid || pid < 1)
+        return undefined;
+    const env = await readProcEnv(pid);
+    if (!env)
+        return undefined;
+    return deriveProvenance(env, os.hostname());
+}

package/dist/lib/shims.d.ts

@@ -83,6 +83,18 @@ export declare const SHIM_SCHEMA_VERSION = 19;
  * is written to ~/.agents/shims/{cliCommand} and made executable.
  */
 export declare function generateShimScript(agent: AgentId): string;
+/**
+ * Which shim files to materialize for a platform. Pure — testable on any host.
+ *
+ * POSIX writes the extensionless `#!/bin/bash` shim — the file PATH resolution
+ * execs. Windows writes only the `.cmd` companion: PATHEXT makes it the runnable
+ * form, and the bash file (mode 0o755 is a no-op there) is never executed — so
+ * emitting it is dead weight that only ever confuses `where agents`.
+ */
+export declare function shimTargetsFor(platform: NodeJS.Platform): {
+    bash: boolean;
+    cmd: boolean;
+};
 /**
  * Create a shim for an agent.
  */
@@ -219,6 +231,14 @@ export declare function getConfigSymlinkVersion(agent: AgentId): string | null;
 /**
  * Check if shim exists for an agent.
  */
+/**
+ * The on-disk shim FILENAME for a platform — derived from `shimTargetsFor` (the
+ * write-side source of truth) so the exists/remove/version checks can never
+ * drift from what `createShim` actually writes: `<cmd>.cmd` on Windows (the only
+ * file written there), the bare `<cmd>` script on POSIX. Pure — testable on any
+ * host.
+ */
+export declare function onDiskShimFile(cliCommand: string, platform: NodeJS.Platform): string;
 export declare function shimExists(agent: AgentId): boolean;
 /**
  * Regenerate the shim if it's missing or outdated. Returns a status describing

package/dist/lib/shims.js

@@ -528,6 +528,19 @@ fi
 exec "$BINARY"${launchArgs} "$@"
 `;
 }
+/**
+ * Which shim files to materialize for a platform. Pure — testable on any host.
+ *
+ * POSIX writes the extensionless `#!/bin/bash` shim — the file PATH resolution
+ * execs. Windows writes only the `.cmd` companion: PATHEXT makes it the runnable
+ * form, and the bash file (mode 0o755 is a no-op there) is never executed — so
+ * emitting it is dead weight that only ever confuses `where agents`.
+ */
+export function shimTargetsFor(platform) {
+    if (platform === 'win32')
+        return { bash: false, cmd: true };
+    return { bash: true, cmd: false };
+}
 /**
  * Create a shim for an agent.
  */
@@ -536,12 +549,15 @@ export function createShim(agent) {
     const shimsDir = getShimsDir();
     const agentConfig = AGENTS[agent];
     const shimPath = path.join(shimsDir, agentConfig.cliCommand);
-    const script = generateShimScript(agent);
-    fs.writeFileSync(shimPath, script, { mode: 0o755 });
-    // Windows can't execute the bash shim directly. Drop a `.cmd` companion next
-    // to it that delegates to the node-side transparent resolver (`agents __shim`),
-    // so the version resolution stays single-sourced instead of reimplemented in batch.
-    if (IS_WINDOWS) {
+    const targets = shimTargetsFor(process.platform);
+    if (targets.bash) {
+        fs.writeFileSync(shimPath, generateShimScript(agent), { mode: 0o755 });
+    }
+    // Windows can't execute the bash shim directly. Drop a `.cmd` companion — which
+    // delegates to the node-side transparent resolver (`agents __shim`) so version
+    // resolution stays single-sourced instead of reimplemented in batch — and skip
+    // the vestigial bash file entirely.
+    if (targets.cmd) {
         writeWindowsCmdShim(shimPath + '.cmd', agentConfig.cliCommand);
     }
     return shimPath;
@@ -557,6 +573,7 @@ function writeWindowsCmdShim(cmdPath, spec) {
     const indexJs = getAgentsBinForGeneratedShim();
     const content = `@echo off\r\n` +
         `rem Auto-generated by agents-cli - do not edit\r\n` +
+        `rem ${SHIM_VERSION_MARKER} ${SHIM_SCHEMA_VERSION}\r\n` +
         `node "${indexJs}" __shim ${spec} %*\r\n`;
     fs.writeFileSync(cmdPath, content);
 }
@@ -567,17 +584,18 @@ export function removeShim(agent) {
     const shimsDir = getShimsDir();
     const agentConfig = AGENTS[agent];
     const shimPath = path.join(shimsDir, agentConfig.cliCommand);
-    if (fs.existsSync(shimPath)) {
-        fs.unlinkSync(shimPath);
-        if (IS_WINDOWS) {
-            try {
-                fs.unlinkSync(shimPath + '.cmd');
-            }
-            catch { }
+    // Remove whichever companions exist: the extensionless script (POSIX, or a
+    // legacy Windows install that wrote it) AND the `.cmd` (Windows). Keying only
+    // off the extensionless path would orphan the `.cmd` on Windows, where
+    // createShim now writes only the `.cmd`.
+    let removed = false;
+    for (const p of [shimPath, shimPath + '.cmd']) {
+        if (fs.existsSync(p)) {
+            fs.unlinkSync(p);
+            removed = true;
         }
-        return true;
     }
-    return false;
+    return removed;
 }
 /**
  * Current versioned-alias schema. Bump whenever `generateVersionedAliasScript`
@@ -1376,11 +1394,26 @@ async function copyDirContents(src, dest, strategy = 'keep-dest', context) {
 /**
  * Check if shim exists for an agent.
  */
+/**
+ * The on-disk shim FILENAME for a platform — derived from `shimTargetsFor` (the
+ * write-side source of truth) so the exists/remove/version checks can never
+ * drift from what `createShim` actually writes: `<cmd>.cmd` on Windows (the only
+ * file written there), the bare `<cmd>` script on POSIX. Pure — testable on any
+ * host.
+ */
+export function onDiskShimFile(cliCommand, platform) {
+    return shimTargetsFor(platform).cmd ? `${cliCommand}.cmd` : cliCommand;
+}
+/**
+ * The actual on-disk shim path for the current platform. This is what
+ * exists/version checks must stat — `getShimPath` returns the logical
+ * (extensionless) launch path, which is not always a real file on Windows.
+ */
+function onDiskShimPath(agent) {
+    return path.join(getShimsDir(), onDiskShimFile(AGENTS[agent].cliCommand, process.platform));
+}
 export function shimExists(agent) {
-    const shimsDir = getShimsDir();
-    const agentConfig = AGENTS[agent];
-    const shimPath = path.join(shimsDir, agentConfig.cliCommand);
-    return fs.existsSync(shimPath);
+    return fs.existsSync(onDiskShimPath(agent));
 }
 /**
  * Read the schema version embedded in an existing on-disk shim. Returns
@@ -1390,7 +1423,7 @@ function readShimSchemaVersion(agent) {
     if (!shimExists(agent))
         return null;
     try {
-        const content = fs.readFileSync(getShimPath(agent), 'utf8');
+        const content = fs.readFileSync(onDiskShimPath(agent), 'utf8');
         // Look at the first ~10 lines only — the marker lives in the header.
         const header = content.split('\n', 10).join('\n');
         const match = header.match(new RegExp(SHIM_VERSION_MARKER + '\\s*(\\d+)'));

package/dist/lib/ssh-exec.d.ts

@@ -19,6 +19,7 @@ export declare function assertValidSshTarget(host: string): void;
 export declare function shellQuote(s: string): string;
 /** Hardened ssh options applied to every connection. */
 export declare const SSH_OPTS: readonly string[];
+export declare function controlOpts(): string[];
 export interface SshExecOptions {
     /** Piped to the remote command's stdin (never interpolated into the shell). */
     input?: string;
@@ -26,6 +27,8 @@ export interface SshExecOptions {
     timeoutMs?: number;
     /** Extra ssh flags inserted before the target (e.g. `-tt`). */
     extraSshArgs?: string[];
+    /** Reuse a persistent control socket across calls (see `controlOpts`). */
+    multiplex?: boolean;
 }
 export interface SshExecResult {
     /** Remote exit status, or null if ssh itself failed / timed out. */
@@ -43,3 +46,22 @@ export interface SshExecResult {
 export declare function sshExec(target: string, remoteCmd: string, opts?: SshExecOptions): SshExecResult;
 /** True if `target` is reachable over ssh (a passwordless `true` succeeds quickly). */
 export declare function sshReachable(target: string, timeoutMs?: number): boolean;
+export interface SshStreamOptions {
+    /**
+     * Allocate a remote pseudo-terminal (`ssh -tt`) so an interactive remote
+     * command (a picker, a prompt) renders live on the local terminal. Callers
+     * pass this when the *local* process is itself a TTY; piped/scripted callers
+     * leave it off and forward a non-interactive invocation instead.
+     */
+    tty?: boolean;
+    /** Reuse a persistent control socket across calls (see `controlOpts`). */
+    multiplex?: boolean;
+}
+/**
+ * Foreground counterpart to `sshExec`: run `remoteCmd` on `target` with the
+ * local stdio wired straight through (`stdio: 'inherit'`), so output streams as
+ * it is produced and — with `tty` — keystrokes reach a remote picker. Blocks
+ * until the remote command exits and returns its exit code (255 is ssh's own
+ * connection-layer failure; any other non-zero is the remote command's code).
+ */
+export declare function sshStream(target: string, remoteCmd: string, opts?: SshStreamOptions): number;

package/dist/lib/ssh-exec.js

@@ -8,6 +8,9 @@
  * canonical definition; `commands/secrets.ts` re-exports it.
  */
 import { spawnSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import { getCacheDir } from './state.js';
 /**
  * SSH target: a bare ssh-config host alias (e.g. `yosemite-s0`) or `user@host`.
  * The strict allowlist blocks shell metacharacters so a target can't be
@@ -32,6 +35,42 @@ export const SSH_OPTS = [
     '-o', 'BatchMode=yes',
     '-o', 'ConnectTimeout=10',
 ];
+/**
+ * OpenSSH connection-multiplexing options. The first connection to a host opens
+ * a control socket; subsequent connections (even from a *separate* `agents`
+ * invocation) reuse it, skipping the TCP+auth handshake — so repeated
+ * `--host <name>` calls to the same box feel local instead of paying ~100-300ms
+ * each. `ControlPersist=60s` keeps the master alive briefly after the last
+ * client exits. `%C` (a short fixed-length hash of local-host/remote/port/user)
+ * keeps the socket path well under macOS's 104-char `sun_path` limit.
+ *
+ * The socket directory is created lazily; if ssh can't open the control socket
+ * it falls back to a normal connection (multiplexing is an optimisation, never a
+ * requirement), so this can never make a reachable host unreachable.
+ */
+let controlDirEnsured = false;
+export function controlOpts() {
+    // OpenSSH on Windows has no ControlMaster/ControlPath (unix-socket) support —
+    // passing those options makes ssh error out. Multiplexing is a pure latency
+    // optimisation, so on Windows we simply skip it and use a fresh connection.
+    if (process.platform === 'win32')
+        return [];
+    const dir = path.join(getCacheDir(), 'ssh');
+    if (!controlDirEnsured) {
+        try {
+            fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        }
+        catch {
+            /* best-effort — ssh degrades to a fresh connection if the dir is missing */
+        }
+        controlDirEnsured = true;
+    }
+    return [
+        '-o', 'ControlMaster=auto',
+        '-o', `ControlPath=${path.join(dir, 'cm-%C')}`,
+        '-o', 'ControlPersist=60s',
+    ];
+}
 /**
  * Run `remoteCmd` on `target` over ssh and capture stdout/stderr/exit.
  *
@@ -40,7 +79,8 @@ export const SSH_OPTS = [
  */
 export function sshExec(target, remoteCmd, opts = {}) {
     assertValidSshTarget(target);
-    const args = [...SSH_OPTS, ...(opts.extraSshArgs ?? []), target, remoteCmd];
+    const mux = opts.multiplex ? controlOpts() : [];
+    const args = [...SSH_OPTS, ...mux, ...(opts.extraSshArgs ?? []), target, remoteCmd];
     const res = spawnSync('ssh', args, {
         input: opts.input,
         encoding: 'utf-8',
@@ -57,5 +97,22 @@ export function sshExec(target, remoteCmd, opts = {}) {
 }
 /** True if `target` is reachable over ssh (a passwordless `true` succeeds quickly). */
 export function sshReachable(target, timeoutMs = 10000) {
-    return sshExec(target, 'true', { timeoutMs }).code === 0;
+    return sshExec(target, 'true', { timeoutMs, multiplex: true }).code === 0;
+}
+/**
+ * Foreground counterpart to `sshExec`: run `remoteCmd` on `target` with the
+ * local stdio wired straight through (`stdio: 'inherit'`), so output streams as
+ * it is produced and — with `tty` — keystrokes reach a remote picker. Blocks
+ * until the remote command exits and returns its exit code (255 is ssh's own
+ * connection-layer failure; any other non-zero is the remote command's code).
+ */
+export function sshStream(target, remoteCmd, opts = {}) {
+    assertValidSshTarget(target);
+    const mux = opts.multiplex ? controlOpts() : [];
+    const tty = opts.tty ? ['-tt'] : [];
+    const args = [...SSH_OPTS, ...mux, ...tty, target, remoteCmd];
+    const res = spawnSync('ssh', args, { stdio: 'inherit' });
+    if (typeof res.status === 'number')
+        return res.status;
+    return 255; // spawn error / signal — treat as a connection-layer failure
 }

package/dist/lib/ssh-tunnel.d.ts

@@ -90,11 +90,6 @@ export declare function buildPushScript(): string;
 export declare function buildRegisterTaskScript(port: number, taskName: string): string;
 /** PowerShell that unregisters the task and stops any running daemon process. */
 export declare function buildUnregisterTaskScript(taskName: string): string;
-/**
- * `setup --host`: push the exe, then register + start the LOGON task. Both hops
- * go through `sshExec` (BatchMode key auth — the same hardening the browser
- * driver and `agents ssh` use). Throws with the remote stderr on any failure.
- */
 export declare function setupRemoteHelper(name: string): Promise<{
     target: string;
     taskName: string;

package/dist/lib/ssh-tunnel.js

@@ -22,7 +22,8 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
 import { randomBytes } from 'crypto';
-import { sshExec } from './ssh-exec.js';
+import { Transform } from 'stream';
+import { sshExec, SSH_OPTS } from './ssh-exec.js';
 import { encodePowerShell } from './browser/drivers/ssh.js';
 import { getDevice } from './devices/registry.js';
 import { sshTargetFor } from './devices/connect.js';
@@ -199,20 +200,76 @@ export function buildUnregisterTaskScript(taskName) {
  * go through `sshExec` (BatchMode key auth — the same hardening the browser
  * driver and `agents ssh` use). Throws with the remote stderr on any failure.
  */
+/**
+ * Base64-encode a byte stream in 3-byte-aligned chunks so the concatenated
+ * output is valid (every chunk boundary lands on a base64 quantum).
+ */
+class Base64Encode extends Transform {
+    leftover = Buffer.alloc(0);
+    _transform(chunk, _enc, cb) {
+        const buf = this.leftover.length ? Buffer.concat([this.leftover, chunk]) : chunk;
+        const usable = buf.length - (buf.length % 3);
+        this.leftover = Buffer.from(buf.subarray(usable));
+        if (usable > 0)
+            this.push(buf.subarray(0, usable).toString('base64'));
+        cb();
+    }
+    _flush(cb) {
+        if (this.leftover.length)
+            this.push(this.leftover.toString('base64'));
+        cb();
+    }
+}
+/**
+ * Stream a local file to a remote command's stdin over ssh, base64-encoded on
+ * the fly. Async spawn + piping honors backpressure; the previous
+ * `spawnSync({ input })` blob deadlocked once the ssh socket buffer filled
+ * (~4MB) on large files (the 157MB Windows helper reproduced this reliably),
+ * and worse, reported a false success leaving a 0-byte remote file. Rejects on
+ * any pipe error so a broken transfer fails loudly instead.
+ */
+function streamFileOverSsh(target, remoteCmd, filePath, timeoutMs = 600_000) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('ssh', [...SSH_OPTS, target, remoteCmd], {
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        let stderr = '';
+        let stdout = '';
+        child.stderr.on('data', (d) => (stderr += d.toString()));
+        child.stdout.on('data', (d) => (stdout += d.toString()));
+        const timer = setTimeout(() => {
+            child.kill('SIGKILL');
+            reject(new Error(`ssh push to ${target} timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        const fail = (e) => {
+            clearTimeout(timer);
+            child.kill('SIGKILL');
+            reject(e);
+        };
+        child.on('error', fail);
+        child.stdin.on('error', fail); // EPIPE if the remote decoder dies mid-stream
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            resolve({ code, stderr: stderr || stdout });
+        });
+        const src = fs.createReadStream(filePath);
+        src.on('error', fail);
+        // disk -> aligned base64 -> ssh stdin; .pipe() applies backpressure
+        src.pipe(new Base64Encode()).pipe(child.stdin);
+    });
+}
 export async function setupRemoteHelper(name) {
     const { target } = await resolveRemoteDevice(name);
     const exe = resolveWinHelperExe();
     if (!exe) {
         throw new Error(`Windows helper exe not built. Run: bash scripts/build-win.sh`);
     }
-    // Push: base64 the exe locally, stream it over ssh stdin to the decoder.
-    const b64 = fs.readFileSync(exe).toString('base64');
-    const push = sshExec(target, encodePowerShell(buildPushScript()), {
-        input: b64,
-        timeoutMs: 600_000, // ~156MB over the wire — allow up to 10 minutes
-    });
+    // Push: stream the exe from disk, base64-encoded on the fly, to the remote
+    // decoder. Streaming (vs a single spawnSync `input` blob) honors ssh socket
+    // backpressure — the blob path deadlocks once the socket buffer fills (~4MB).
+    const push = await streamFileOverSsh(target, encodePowerShell(buildPushScript()), exe);
     if (push.code !== 0) {
-        throw new Error(`pushing helper exe to '${name}' failed (exit ${push.code ?? 'null'}): ${push.stderr.trim() || push.stdout.trim()}`);
+        throw new Error(`pushing helper exe to '${name}' failed (exit ${push.code ?? 'null'}): ${push.stderr.trim()}`);
     }
     // Register + start the LOGON task.
     const reg = sshExec(target, encodePowerShell(buildRegisterTaskScript(REMOTE_HELPER_PORT, REMOTE_TASK_NAME)), {

package/dist/lib/startup/command-registry.d.ts

@@ -49,6 +49,7 @@ export declare const loadPrune: ModuleLoader;
 export declare const loadTrash: ModuleLoader;
 export declare const loadRestore: ModuleLoader;
 export declare const loadDoctor: ModuleLoader;
+export declare const loadStatus: ModuleLoader;
 export declare const loadProfiles: ModuleLoader;
 export declare const loadSecrets: ModuleLoader;
 export declare const loadWallet: ModuleLoader;

package/dist/lib/startup/command-registry.js

@@ -27,6 +27,7 @@ export const loadPrune = async () => (await import('../../commands/prune.js')).r
 export const loadTrash = async () => (await import('../../commands/trash.js')).registerTrashCommands;
 export const loadRestore = async () => (await import('../../commands/trash.js')).registerRestoreCommand;
 export const loadDoctor = async () => (await import('../../commands/doctor.js')).registerDoctorCommand;
+export const loadStatus = async () => (await import('../../commands/status.js')).registerStatusCommand;
 export const loadProfiles = async () => (await import('../../commands/profiles.js')).registerProfilesCommands;
 export const loadSecrets = async () => (await import('../../commands/secrets.js')).registerSecretsCommands;
 export const loadWallet = async () => (await import('../../commands/wallet.js')).registerWalletCommands;
@@ -110,6 +111,7 @@ export const COMMAND_LOADERS = {
     trash: [loadTrash],
     restore: [loadRestore],
     doctor: [loadDoctor],
+    status: [loadStatus],
     profiles: [loadProfiles],
     secrets: [loadSecrets],
     wallet: [loadWallet],

package/dist/lib/sync-status.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Unified sync-status engine — the SINGLE source of truth for "is this resource
+ * synced to this agent version?" consumed by `agents doctor`, `agents view`, the
+ * menu-bar app, and any Agency surface.
+ *
+ * Why this exists: before this module there were four different notions of
+ * "synced" living in four files:
+ *   - doctor:  isStale() vs .sync-manifest.json  — catches SOURCE drift only.
+ *   - view:    git working-tree state of ~/.agents/ — a resource can show green
+ *              while its installed copy is stale/deleted/corrupted (false positive).
+ *   - lists:   file-exists-in-home — never reports content drift at all.
+ *   - menubar: read doctor --json (so it inherited doctor's source-only blind spot).
+ *
+ * The reliable signal is diffVersionResources() (src/lib/doctor-diff.ts): it reads
+ * the ACTUAL version home and compares it to the resolved sources, so it catches
+ * every drift class — source-side changes AND home-side rot (deleted / corrupted /
+ * hand-edited installed copies) AND orphans. This module wraps it once, maps its
+ * per-resource DiffStatus onto one stable enum, folds in `.system` repo freshness,
+ * and lets every surface render the same warnings instead of re-deriving them.
+ */
+import { AgentId } from './types.js';
+import { type DoctorKind } from './doctor-diff.js';
+/**
+ * One stable status per resource, unified across every surface.
+ *  - `synced`  — installed copy matches the resolved source (DiffStatus 'ok').
+ *  - `drifted` — installed copy exists but differs from source (DiffStatus 'diff').
+ *  - `missing` — source exists, nothing installed in the version home ('missing').
+ *  - `orphan`  — installed in the home with no source ('extra'); prune's job, not sync's.
+ */
+export type ResourceSyncStatus = 'synced' | 'drifted' | 'missing' | 'orphan';
+export interface ResourceStatusRow {
+    agent: AgentId;
+    version: string;
+    kind: DoctorKind;
+    name: string;
+    status: ResourceSyncStatus;
+    /** Human-readable specifics for a drifted row (e.g. plugin version delta). */
+    detail?: string;
+}
+export interface AgentVersionStatus {
+    agent: AgentId;
+    version: string;
+    isDefault: boolean;
+    /** False = no .sync-manifest.json: this version was never synced (cold). */
+    everSynced: boolean;
+    counts: {
+        synced: number;
+        drifted: number;
+        missing: number;
+        orphan: number;
+    };
+    /** drifted + missing > 0 — a real reconcile is owed. Orphans do NOT set this
+     * (heal never deletes; orphan removal is `agents prune cleanup`). */
+    needsSync: boolean;
+    resources: ResourceStatusRow[];
+}
+export interface SystemRepoStatus {
+    dir: string;
+    /** Commits the local `.system` checkout is behind its tracking branch, as of
+     * the last background fetch (no network is performed here). 0 = up to date. */
+    behind: number;
+    ahead: number;
+    branch: string | null;
+    /** True when the dir isn't a git repo or has no upstream — behind is unknown. */
+    unknown: boolean;
+}
+export interface UnifiedSyncStatus {
+    system: SystemRepoStatus;
+    agents: AgentVersionStatus[];
+    totals: {
+        drifted: number;
+        missing: number;
+        orphan: number;
+        /** Versions with a manifest that are behind on content. */
+        versionsNeedingSync: number;
+        /** Versions that were never synced at all. */
+        versionsNeverSynced: number;
+        /** Distinct agent ids that own at least one version needing sync. */
+        agentsNeedingSync: number;
+    };
+}
+export interface SyncStatusOptions {
+    cwd?: string;
+    /** Restrict to specific agent ids; undefined = every supported agent. */
+    agents?: AgentId[];
+    /** Restrict to specific resource kinds; undefined = all. */
+    kinds?: DoctorKind[];
+}
+/**
+ * Read `.system` repo freshness WITHOUT touching the network. `git status`
+ * reports ahead/behind against the remote-tracking ref, which the detached
+ * auto-pull worker keeps warm via periodic `git fetch`. This is the same number
+ * the menu-bar surfaces; we read it once, here, so every surface agrees.
+ */
+export declare function getSystemRepoStatus(): Promise<SystemRepoStatus>;
+/**
+ * Compute unified sync status across the fleet. Resolves against non-project
+ * layers only (`excludeProject: true`) — the GLOBAL version home is never
+ * reconciled against per-cwd `<cwd>/.agents/` resources, so counting them as
+ * "missing" there would be a false gap (matches doctor's overview semantics).
+ */
+export declare function computeSyncStatus(options?: SyncStatusOptions): Promise<UnifiedSyncStatus>;