@phnx-labs/agents-cli 1.20.31 → 1.20.33

package/dist/lib/hosts/remote-cmd.js

@@ -0,0 +1,56 @@
+/**
+ * Pure argv helpers for `--host` passthrough — build the remote `agents …`
+ * invocation and strip the local-only routing flags before forwarding.
+ *
+ * Kept free of any SSH/process side effects so the two-layer quoting and the
+ * flag-stripping edge cases (glued short forms, `=value`, variadic) are unit
+ * testable without a live host. The transport itself lives in `ssh-exec.ts`
+ * (`sshExec`/`sshStream`); orchestration lives in `passthrough.ts`.
+ */
+import { shellQuote } from '../ssh-exec.js';
+/**
+ * Remove routing flags (and their values) from a command's args, leaving the
+ * rest untouched and in order so they forward verbatim to the remote binary.
+ * Handles every form commander accepts: `--host h`, `--host=h`, `-H h`, `-H=h`,
+ * and the glued short form `-Hh`.
+ *
+ * @param args the command's args (already past the command name).
+ */
+export function stripRoutingFlags(args, specs) {
+    const out = [];
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        const spec = specs.find((s) => {
+            if (a === `--${s.long}` || a.startsWith(`--${s.long}=`))
+                return true;
+            if (s.short && (a === `-${s.short}` || a.startsWith(`-${s.short}=`) || new RegExp(`^-${s.short}.+`).test(a)))
+                return true;
+            return false;
+        });
+        if (!spec) {
+            out.push(a);
+            continue;
+        }
+        // Consume a separate value token only for the exact-match (space-separated) forms.
+        const isExact = a === `--${spec.long}` || (spec.short && a === `-${spec.short}`);
+        if (spec.takesValue && isExact && i + 1 < args.length)
+            i++;
+    }
+    return out;
+}
+/** The routing flags every `--host`-capable command shares. */
+export const HOST_ROUTING_SPECS = [
+    { long: 'host', short: 'H', takesValue: true },
+    { long: 'remote-cwd', takesValue: true },
+];
+/**
+ * Build the single command string for `ssh <target> <cmd>`. The forwarded args
+ * are quoted for the inner login shell, then the whole `agents …` invocation is
+ * quoted again so it survives `bash -lc <...>` — `bash -lc` so the remote login
+ * PATH resolves `agents`. An optional `cd` runs first for `--remote-cwd`.
+ */
+export function buildRemoteAgentsInvocation(forwardedArgs, remoteCwd) {
+    const inner = ['agents', ...forwardedArgs].map(shellQuote).join(' ');
+    const withCwd = remoteCwd ? `cd ${shellQuote(remoteCwd)} && ${inner}` : inner;
+    return `bash -lc ${shellQuote(withCwd)}`;
+}

package/dist/lib/secrets/bundles.js

@@ -21,7 +21,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import * as yaml from 'yaml';
-import { deleteKeychainToken, getKeychainToken, getKeychainTokens, hasKeychainToken, listKeychainItems, parseBundleValue, resolveRef, secretsKeychainItem, setKeychainToken, } from './index.js';
+import { deleteKeychainToken, getKeychainToken, getKeychainTokens, hasKeychainToken, keychainUsesFileFallback, listKeychainItems, parseBundleValue, resolveRef, secretsKeychainItem, setKeychainToken, } from './index.js';
 import { fileStore } from './filestore.js';
 import { emit } from '../events.js';
 import { readMeta } from '../state.js';
@@ -379,25 +379,34 @@ export function listBundles() {
     // prompt instead of N. Bundle metadata items carry user-presence ACLs (same
     // as secret values), so a naive loop over readBundle() spawns a fresh
     // LAContext per item — meaning N biometric prompts for `secrets list`.
-    let keychainServices = [];
-    try {
-        keychainServices = listKeychainItems(BUNDLE_META_PREFIX);
-    }
-    catch {
-        keychainServices = [];
-    }
-    const keychainNames = keychainServices
-        .map((s) => s.slice(BUNDLE_META_PREFIX.length))
-        .filter((n) => BUNDLE_NAME_PATTERN.test(n));
-    if (keychainNames.length > 0) {
-        const fetched = getKeychainTokens(keychainNames.map(bundleMetaItem));
-        for (const name of keychainNames) {
-            const json = fetched.get(bundleMetaItem(name));
-            if (json === undefined)
-                continue;
-            const bundle = parseBundleMeta(name, json, 'keychain');
-            if (bundle)
-                out.push(bundle);
+    //
+    // SKIP this entirely when the keychain backend is routing to the encrypted
+    // file store (Linux headless / locked-collection fallback): there,
+    // listKeychainItems() returns the SAME items the file enumeration below
+    // reads, so running both would list every file-backed bundle twice — once
+    // mislabeled `keychain`, once correctly `[file]`. Under the fallback the
+    // file store is the single source of truth, so the block below covers all.
+    if (!keychainUsesFileFallback()) {
+        let keychainServices = [];
+        try {
+            keychainServices = listKeychainItems(BUNDLE_META_PREFIX);
+        }
+        catch {
+            keychainServices = [];
+        }
+        const keychainNames = keychainServices
+            .map((s) => s.slice(BUNDLE_META_PREFIX.length))
+            .filter((n) => BUNDLE_NAME_PATTERN.test(n));
+        if (keychainNames.length > 0) {
+            const fetched = getKeychainTokens(keychainNames.map(bundleMetaItem));
+            for (const name of keychainNames) {
+                const json = fetched.get(bundleMetaItem(name));
+                if (json === undefined)
+                    continue;
+                const bundle = parseBundleMeta(name, json, 'keychain');
+                if (bundle)
+                    out.push(bundle);
+            }
         }
     }
     // File-backed bundles live in the encrypted-file store. Enumeration is a

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

@@ -86,6 +86,17 @@ export declare function getKeychainTokens(items: string[]): Map<string, string>;
 export declare function setKeychainToken(item: string, value: string): void;
 /** Delete a keychain/keyring item. Returns true if it existed. Never prompts for biometry. */
 export declare function deleteKeychainToken(item: string): boolean;
+/**
+ * True when the active keychain backend transparently routes reads/writes to
+ * the encrypted-file store instead of the OS credential store. This only
+ * happens on Linux under the headless / locked-collection fallback
+ * (src/lib/secrets/linux.ts); macOS and the test backend always return false.
+ *
+ * Callers that ALSO enumerate the file store directly (e.g. `listBundles`)
+ * use this to avoid double-counting: under the fallback `listKeychainItems`
+ * and the direct file enumeration return the same items.
+ */
+export declare function keychainUsesFileFallback(): boolean;
 /** Enumerate keychain/keyring item names starting with the given prefix. */
 export declare function listKeychainItems(prefix: string): string[];
 /**

package/dist/lib/secrets/index.js

@@ -23,7 +23,7 @@ import { execFileSync, spawnSync } from 'child_process';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { linuxBackend } from './linux.js';
+import { linuxBackend, usesFileFallback as linuxUsesFileFallback } from './linux.js';
 import { getKeychainHelperPath } from './install-helper.js';
 const SERVICE_PREFIX = 'agents-cli';
 const SECRETS_ITEM_PREFIX = `${SERVICE_PREFIX}.secrets.`;
@@ -278,6 +278,23 @@ export function deleteKeychainToken(item) {
         stdio: ['ignore', 'pipe', 'pipe'],
     }).status === 0;
 }
+/**
+ * True when the active keychain backend transparently routes reads/writes to
+ * the encrypted-file store instead of the OS credential store. This only
+ * happens on Linux under the headless / locked-collection fallback
+ * (src/lib/secrets/linux.ts); macOS and the test backend always return false.
+ *
+ * Callers that ALSO enumerate the file store directly (e.g. `listBundles`)
+ * use this to avoid double-counting: under the fallback `listKeychainItems`
+ * and the direct file enumeration return the same items.
+ */
+export function keychainUsesFileFallback() {
+    if (backend)
+        return false;
+    if (isLinux())
+        return linuxUsesFileFallback();
+    return false;
+}
 /** Enumerate keychain/keyring item names starting with the given prefix. */
 export function listKeychainItems(prefix) {
     if (backend)

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

@@ -18,6 +18,20 @@
  */
 import type { KeychainBackend } from './index.js';
 export { encryptForFallback, decryptForFallback, fileBackend, type EncFile, } from './filestore.js';
+/**
+ * True when secret operations currently route to the encrypted-file store
+ * instead of the Secret Service (the headless / locked-collection fallback).
+ *
+ * Runs the same `preflight()` decision every read and write uses, so it can't
+ * drift from where bytes actually land. `preflight()` throws only in the
+ * interactive / no-secret-tool / no-passphrase case — where nothing is stored
+ * — so treat that as "not on the file path".
+ *
+ * `listBundles()` needs this: under the fallback the keychain enumeration
+ * (`linuxBackend.list`) and the file enumeration read the SAME store, so
+ * without this signal every file-backed bundle would be listed twice.
+ */
+export declare function usesFileFallback(): boolean;
 /** secret-tool lookup attributes:
  *   service=agents-cli account=<user> item=<itemName> */
 export declare function hasSecretToolToken(item: string): boolean;

package/dist/lib/secrets/linux.js

@@ -86,6 +86,27 @@ function preflight() {
     }
     return 'secret-tool';
 }
+/**
+ * True when secret operations currently route to the encrypted-file store
+ * instead of the Secret Service (the headless / locked-collection fallback).
+ *
+ * Runs the same `preflight()` decision every read and write uses, so it can't
+ * drift from where bytes actually land. `preflight()` throws only in the
+ * interactive / no-secret-tool / no-passphrase case — where nothing is stored
+ * — so treat that as "not on the file path".
+ *
+ * `listBundles()` needs this: under the fallback the keychain enumeration
+ * (`linuxBackend.list`) and the file enumeration read the SAME store, so
+ * without this signal every file-backed bundle would be listed twice.
+ */
+export function usesFileFallback() {
+    try {
+        return preflight() === 'file';
+    }
+    catch {
+        return false;
+    }
+}
 // ---------- secret-tool ops with fallback ----------
 /** secret-tool lookup attributes:
  *   service=agents-cli account=<user> item=<itemName> */

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

@@ -1,4 +1,5 @@
 import { type SessionActivity, type AwaitingReason, type DetectedPr, type DetectedWorktree, type DetectedTicket } from './state.js';
+import { type SessionProvenance } from './provenance.js';
 export type ActiveContext = 'terminal' | 'teams' | 'cloud' | 'headless';
 export type ActiveStatus = 'running' | 'idle' | 'queued' | 'input_required';
 export interface ActiveSession {
@@ -30,6 +31,13 @@ export interface ActiveSession {
     status: ActiveStatus;
     /** How many live PIDs resolve to this same session (subagents/forks). 1 unless collapsed. */
     pidCount?: number;
+    /**
+     * Where the process actually lives — machine host, local vs SSH, tmux pane,
+     * and whether a rail exists to type back into it. Read from the process env
+     * (`/proc/<pid>/environ` on Linux, `ps eww` on macOS) during enrichment.
+     * Absent for cloud sessions (no local pid) and any pid whose env is unreadable.
+     */
+    provenance?: SessionProvenance;
     teamName?: string;
     agentId?: string;
     cloudProvider?: string;

package/dist/lib/session/active.js

@@ -29,6 +29,7 @@ import { latestSessionFileForCwd } from './db.js';
 import { extractSessionTopic } from './prompt.js';
 import { readSessionTail } from './tail.js';
 import { inferSessionState } from './state.js';
+import { detectProvenance } from './provenance.js';
 const execFileAsync = promisify(execFile);
 const HOME = os.homedir();
 const LIVE_TERMINALS_FILE = path.join(getTerminalsDir(), 'live-terminals.json');
@@ -536,7 +537,23 @@ export async function getActiveSessions(opts = {}) {
         if (s.pid)
             knownPids.add(s.pid);
     const unattributed = opts.skipHeadless ? [] : await listUnattributedActive(knownPids);
-    return dedupeBySession([...teams, ...terminals, ...cloud, ...unattributed]);
+    const merged = dedupeBySession([...teams, ...terminals, ...cloud, ...unattributed]);
+    await enrichProvenance(merged);
+    return merged;
+}
+/**
+ * Attach provenance (host / local-vs-SSH / tmux pane / reply rail) to every
+ * session that has a live pid. Mutates in place. Runs after dedupe so we probe
+ * each session once, not once per fork pid. Probes run in parallel — each is a
+ * single /proc read (Linux) or `ps` call (macOS); failures leave `provenance`
+ * undefined rather than blocking the listing.
+ */
+async function enrichProvenance(sessions) {
+    await Promise.all(sessions.map(async (s) => {
+        if (s.provenance || !s.pid)
+            return;
+        s.provenance = await detectProvenance(s.pid);
+    }));
 }
 /**
  * Collapse rows that resolve to the *same* session — a session with many

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

@@ -0,0 +1,56 @@
+export interface SshOrigin {
+    clientIp: string;
+    clientPort: number;
+    serverIp: string;
+    serverPort: number;
+}
+export interface MuxLocation {
+    kind: 'tmux' | 'screen';
+    /** tmux server socket path (first comma-field of $TMUX). Undefined for screen. */
+    socket?: string;
+    /** Exact pane id from $TMUX_PANE, e.g. '%3' — the send-keys target. */
+    pane?: string;
+    /** screen session name from $STY, e.g. '12345.pts-0.host'. */
+    session?: string;
+}
+/** How the feed can type back into a session, derived from rails that exist today. */
+export type ReplyRail = {
+    rail: 'tmux';
+    target: string;
+    socket?: string;
+} | null;
+export interface SessionProvenance {
+    /** Machine the process runs on — os.hostname(). Drives HOSTS grouping. */
+    host: string;
+    /** 'ssh' when SSH_CONNECTION is present in the process env, else 'local'. */
+    transport: 'local' | 'ssh';
+    /** Populated when transport === 'ssh'. */
+    ssh?: SshOrigin;
+    /** TERM_PROGRAM: 'iTerm.app', 'vscode', 'WezTerm', 'tmux', 'Apple_Terminal', … */
+    term?: string;
+    /** Multiplexer the process sits inside, from $TMUX / $STY. */
+    mux?: MuxLocation;
+    /** Whether an existing rail can type back into this session (see module doc). */
+    reply: ReplyRail;
+}
+/** Env vars that carry provenance. Kept small so the macOS `ps` scan stays cheap. */
+export declare const PROVENANCE_ENV_KEYS: readonly ["SSH_CONNECTION", "SSH_TTY", "TMUX", "TMUX_PANE", "TERM_PROGRAM", "STY"];
+/** Parse the NUL-separated body of /proc/<pid>/environ into a plain object. */
+export declare function parseProcEnviron(buf: string): Record<string, string>;
+/**
+ * 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 declare function extractKnownEnv(text: string, keys: readonly string[]): Record<string, string>;
+/** `<client_ip> <client_port> <server_ip> <server_port>` → structured origin. */
+export declare function parseSshConnection(value: string): SshOrigin | undefined;
+/** Build a SessionProvenance from a raw env map + the local hostname. Pure. */
+export declare function deriveProvenance(env: Record<string, string>, hostname: string): SessionProvenance;
+/**
+ * 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 declare function detectProvenance(pid: number): Promise<SessionProvenance | undefined>;

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/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;