@phnx-labs/agents-cli 1.20.34 → 1.20.36

package/dist/lib/shims.d.ts

@@ -77,7 +77,7 @@ export interface ConflictInfo {
  *         top-level entry add/remove — deep edits to plugin contents won't
  *         trigger auto-resync, run `agents sync` for that.
  */
-export declare const SHIM_SCHEMA_VERSION = 19;
+export declare const SHIM_SCHEMA_VERSION = 22;
 /**
  * Generate the full bash shim script for the given agent. The returned string
  * is written to ~/.agents/shims/{cliCommand} and made executable.
@@ -126,8 +126,27 @@ export declare function removeShim(agent: AgentId): boolean;
  *        hardcoded node_modules/.bin, which never exists for these three and
  *        made every versioned alias (the path `agents teams` pins to) fail
  *        with "<agent>@<version> not installed". Also emit GROK_HOME.
- */
-export declare const VERSIONED_ALIAS_SCHEMA_VERSION = 8;
+ *   v9 — kimi was wrong in v8: it npm-installs @moonshot-ai/kimi-code into
+ *        node_modules/.bin/kimi (grok/droid ship native binaries elsewhere,
+ *        kimi does not). The ~/.kimi-code/bin path never existed for an npm
+ *        install and the `command -v kimi` fallback resolved to this alias's
+ *        sibling dispatcher shim, re-exec-looping forever. Resolve kimi via the
+ *        generic node_modules/.bin branch.
+ *  v10 — guard grok's `command -v grok` fallback against resolving to our own
+ *        shims dir (same infinite re-exec loop), mirroring droid.
+ *  v11 — export DISABLE_AUTOUPDATER=1 for claude aliases so a pinned per-version
+ *        install can't self-mutate via Claude Code's background auto-updater.
+ *        Explicit user value wins.
+ *  v12 — Windows: stop writing the extensionless bash alias next to the `.cmd`
+ *        (and delete a lingering one). The version suffix contains dots, so
+ *        cmd.exe and PowerShell treat `claude@2.1.201` as a complete filename
+ *        with extension `.201`, exact-match the bash script AHEAD of PATHEXT
+ *        probing, and ShellExecute it to the `.sh` editor association — the
+ *        editor opens the script and the agent never launches. The `.cmd` is
+ *        now the only Windows artifact and carries this alias marker so
+ *        staleness checks read it directly.
+ */
+export declare const VERSIONED_ALIAS_SCHEMA_VERSION = 12;
 /**
  * Generate a versioned alias script that directly execs a specific version.
  * e.g., claude@2.0.65 -> directly runs that version's binary
@@ -149,20 +168,39 @@ export declare function isVersionedAliasCurrent(agent: AgentId, version: string)
  */
 export declare function ensureVersionedAliasCurrent(agent: AgentId, version: string): 'created' | 'updated' | 'current';
 /**
- * Get the filesystem path for a versioned alias script.
+ * Get the filesystem path for a versioned alias script — the logical
+ * (extensionless) launch name. On Windows this is not a real file (see
+ * versionedAliasOnDiskFile); stat/read checks must use the on-disk path.
  */
 export declare function getVersionedAliasPath(agent: AgentId, version: string): string;
+/**
+ * The file createVersionedAlias actually materializes for a platform:
+ * `<cmd>@<version>.cmd` on Windows, the bare bash script on POSIX. Pure —
+ * testable on any host. Mirrors onDiskShimFile for the main shim.
+ */
+export declare function versionedAliasOnDiskFile(cliCommand: string, version: string, platform: NodeJS.Platform): string;
 /**
  * Create a versioned alias for a specific agent version.
  * e.g., claude@2.0.65
+ *
+ * Same platform split as createShim (shimTargetsFor): POSIX writes the
+ * extensionless bash script; Windows writes ONLY the `.cmd`. Unlike the main
+ * shim — where the bash file was merely dead weight — a bash alias next to the
+ * versioned `.cmd` is actively harmful: the dotted version suffix makes
+ * cmd.exe/PowerShell treat `claude@2.1.201` as a complete filename (extension
+ * `.201`), so the exact match wins over PATHEXT probing and the shell
+ * ShellExecutes the bash script to the `.sh` editor association — the editor
+ * opens, the agent never launches. Any legacy bash alias is deleted here.
  */
 export declare function createVersionedAlias(agent: AgentId, version: string): string;
 /**
- * Remove a versioned alias for a specific agent version.
+ * Remove a versioned alias for a specific agent version. Removes whichever
+ * companions exist — the extensionless script (POSIX, or a legacy Windows
+ * install that wrote it) AND the `.cmd` (Windows) — mirroring removeShim.
  */
 export declare function removeVersionedAlias(agent: AgentId, version: string): boolean;
 /**
- * Check if a versioned alias exists.
+ * Check if a versioned alias exists (the on-disk artifact for this platform).
  */
 export declare function versionedAliasExists(agent: AgentId, version: string): boolean;
 /**

package/dist/lib/shims.js

@@ -202,7 +202,16 @@ async function promptConflictStrategy(conflictInfos) {
  *         top-level entry add/remove — deep edits to plugin contents won't
  *         trigger auto-resync, run `agents sync` for that.
  */
-export const SHIM_SCHEMA_VERSION = 19;
+// v20 — stop treating kimi like grok/droid: it npm-installs into
+//        node_modules/.bin/kimi, so resolve it via the generic branch. The old
+//        ~/.kimi-code/bin special-case never existed for npm installs and
+//        re-exec-looped through `command -v kimi` (the dispatcher itself).
+// v21 — guard grok's `command -v grok` fallback against resolving to our own
+//        shims dir (same infinite re-exec loop), mirroring droid.
+// v22 — export DISABLE_AUTOUPDATER=1 for claude shims so a pinned per-version
+//        install can't self-mutate: Claude Code's background auto-updater would
+//        otherwise rewrite the pinned binary in place. Explicit user value wins.
+export const SHIM_SCHEMA_VERSION = 22;
 /** Internal marker string used to embed the schema version in shim scripts. */
 const SHIM_VERSION_MARKER = 'agents-shim-version:';
 function shellQuote(value) {
@@ -230,6 +239,10 @@ export function generateShimScript(agent) {
 # selected version's config directory so switching versions also switches the
 # live Claude account.
 export CLAUDE_CONFIG_DIR="$VERSION_DIR/home/${configDirName}"
+# Managed installs are pinned in a per-version dir; Claude Code's background
+# auto-updater would rewrite the pinned binary in place. Disable it so a pin
+# stays a pin. An explicit user value always wins.
+export DISABLE_AUTOUPDATER="\${DISABLE_AUTOUPDATER:-1}"
 # On Linux sandboxes (no keychain), fall back to a per-version token file.
 # The env var always wins if already set; no-op on macOS.
 if [ "\$(uname -s)" = "Linux" ] && [ -z "\${CLAUDE_CODE_OAUTH_TOKEN:-}" ] && [ -f "\$CLAUDE_CONFIG_DIR/.oauth_token" ]; then
@@ -401,19 +414,25 @@ if [ "$AGENT" = "grok" ]; then
     fi
   fi
   if [ -z "$BINARY" ] || [ ! -x "$BINARY" ]; then
-    # Last resort: whatever is on PATH (user may have installed grok globally)
+    # Last resort: whatever is on PATH (user may have installed grok globally).
+    # Refuse anything under our own shims dir: the shims dir sits ahead of
+    # ~/.local/bin on PATH, so "command -v grok" resolves to THIS dispatcher.
+    # exec-ing it would re-enter and spin in an infinite re-exec loop (the same
+    # bug the droid branch below guards against). Fall through to the clean
+    # "not installed" error instead.
     BINARY=$(command -v grok 2>/dev/null || echo "")
+    case "$BINARY" in
+      "$AGENTS_USER_DIR/.cache/shims/"*) BINARY="" ;;
+    esac
   fi
-# Kimi special case: binary lives in ~/.kimi-code/bin/, not node_modules.
-# We still use the agents-cli version dir purely for KIMI_CODE_HOME isolation.
-elif [ "$AGENT" = "kimi" ]; then
-  KIMI_BINARY="$HOME/.kimi-code/bin/kimi"
-  if [ -x "$KIMI_BINARY" ]; then
-    BINARY="$KIMI_BINARY"
-  else
-    # Last resort: whatever is on PATH
-    BINARY=$(command -v kimi 2>/dev/null || echo "")
-  fi
+# Kimi is a normal npm agent: "agents add kimi" npm-installs
+# @moonshot-ai/kimi-code into the version dir and the binary lands at
+# node_modules/.bin/kimi (a curl-installed kimi is symlinked to the same spot
+# by installVersion). So kimi resolves via the generic node_modules branch
+# below -- never a bespoke ~/.kimi-code/bin path that does not exist for npm
+# installs and fell back to "command -v kimi", which resolves to THIS
+# dispatcher (shims dir is ahead on PATH) and re-execs forever. Only
+# KIMI_CODE_HOME (config isolation) stays special-cased, separately below.
 # Droid (Factory AI) special case: the official installer drops a standalone
 # native binary at ~/.local/bin/droid — there is no npm package and nothing
 # lands in node_modules/.bin. Resolve the fixed install path directly. The
@@ -568,12 +587,18 @@ export function createShim(agent) {
  * `cliCommand@version` for a versioned alias. node + the dist entrypoint are
  * resolved at generation time so the launcher does not depend on `agents`
  * already being on PATH.
+ *
+ * `extraMarkerLines` lets callers stamp additional schema markers into the
+ * header — versioned aliases embed their own alias-schema marker so
+ * readVersionedAliasSchemaVersion can stat the `.cmd` (the only Windows
+ * artifact) the same way it reads the bash script on POSIX.
  */
-function writeWindowsCmdShim(cmdPath, spec) {
+function writeWindowsCmdShim(cmdPath, spec, extraMarkerLines = []) {
     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` +
+        extraMarkerLines.map((line) => `rem ${line}\r\n`).join('') +
         `node "${indexJs}" __shim ${spec} %*\r\n`;
     fs.writeFileSync(cmdPath, content);
 }
@@ -620,8 +645,27 @@ export function removeShim(agent) {
  *        hardcoded node_modules/.bin, which never exists for these three and
  *        made every versioned alias (the path `agents teams` pins to) fail
  *        with "<agent>@<version> not installed". Also emit GROK_HOME.
+ *   v9 — kimi was wrong in v8: it npm-installs @moonshot-ai/kimi-code into
+ *        node_modules/.bin/kimi (grok/droid ship native binaries elsewhere,
+ *        kimi does not). The ~/.kimi-code/bin path never existed for an npm
+ *        install and the `command -v kimi` fallback resolved to this alias's
+ *        sibling dispatcher shim, re-exec-looping forever. Resolve kimi via the
+ *        generic node_modules/.bin branch.
+ *  v10 — guard grok's `command -v grok` fallback against resolving to our own
+ *        shims dir (same infinite re-exec loop), mirroring droid.
+ *  v11 — export DISABLE_AUTOUPDATER=1 for claude aliases so a pinned per-version
+ *        install can't self-mutate via Claude Code's background auto-updater.
+ *        Explicit user value wins.
+ *  v12 — Windows: stop writing the extensionless bash alias next to the `.cmd`
+ *        (and delete a lingering one). The version suffix contains dots, so
+ *        cmd.exe and PowerShell treat `claude@2.1.201` as a complete filename
+ *        with extension `.201`, exact-match the bash script AHEAD of PATHEXT
+ *        probing, and ShellExecute it to the `.sh` editor association — the
+ *        editor opens the script and the agent never launches. The `.cmd` is
+ *        now the only Windows artifact and carries this alias marker so
+ *        staleness checks read it directly.
  */
-export const VERSIONED_ALIAS_SCHEMA_VERSION = 8;
+export const VERSIONED_ALIAS_SCHEMA_VERSION = 12;
 /** Internal marker string used to embed the schema version in versioned alias scripts. */
 const VERSIONED_ALIAS_VERSION_MARKER = 'agents-versioned-alias-version:';
 // The version string is interpolated into a generated bash script and into
@@ -649,6 +693,10 @@ export function generateVersionedAliasScript(agent, version) {
 # Claude stores OAuth credentials in the macOS keychain. Scope them to this
 # version's config directory so direct aliases also switch the live account.
 export CLAUDE_CONFIG_DIR="$HOME/.agents/.history/versions/${agent}/${version}/home/${configDirName}"
+# Managed installs are pinned in a per-version dir; Claude Code's background
+# auto-updater would rewrite the pinned binary in place. Disable it so a pin
+# stays a pin. An explicit user value always wins.
+export DISABLE_AUTOUPDATER="\${DISABLE_AUTOUPDATER:-1}"
 `
         : agent === 'codex'
             ? `
@@ -680,12 +728,16 @@ export KIMI_CODE_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/
                         : '';
     const launchArgs = agent === 'codex' ? ' -c check_for_update_on_startup=false' : '';
     // Resolve the binary the same way the main shim does (see generateShimScript).
-    // Grok, Kimi, and Droid do NOT ship into node_modules/.bin — Grok downloads a
-    // native binary to ~/.grok/downloads, Kimi to ~/.kimi-code/bin, and Droid
-    // (Factory AI) installs a standalone binary to ~/.local/bin. Hardcoding the
-    // node_modules path made every versioned alias for these three fail with
-    // "<agent>@<version> not installed", which is exactly the path `agents teams`
-    // takes once it pins a teammate's version.
+    // Grok and Droid do NOT ship into node_modules/.bin — Grok downloads a native
+    // binary to ~/.grok/downloads and Droid (Factory AI) installs a standalone
+    // binary to ~/.local/bin. Hardcoding the node_modules path made every
+    // versioned alias for those two fail with "<agent>@<version> not installed",
+    // which is exactly the path `agents teams` takes once it pins a teammate's
+    // version. Kimi is NOT one of them: `agents add kimi` npm-installs
+    // @moonshot-ai/kimi-code so its binary is at node_modules/.bin/kimi (the
+    // generic branch below). The old ~/.kimi-code/bin path never exists for an
+    // npm install and fell back to `command -v kimi`, which resolves to this
+    // alias's sibling dispatcher shim and re-execs forever.
     // This template is unix-only — on Windows the .cmd companion delegates to
     // "agents __shim" which resolves via getBinaryPath() instead.
     const versionDir = `$HOME/.agents/.history/versions/${agent}/${version}`;
@@ -697,17 +749,17 @@ if [ -d "$GROK_DOWNLOADS" ]; then
   BINARY=$(ls "$GROK_DOWNLOADS"/grok-* 2>/dev/null | grep -i "${version}" | head -1)
   [ -n "$BINARY" ] || BINARY=$(ls "$GROK_DOWNLOADS"/grok-* 2>/dev/null | head -1)
 fi
-[ -n "$BINARY" ] && [ -x "$BINARY" ] || BINARY=$(command -v grok 2>/dev/null || echo "")`
-        : agent === 'kimi'
-            ? `# Kimi ships its binary in ~/.kimi-code/bin, not node_modules.
-KIMI_BINARY="$HOME/.kimi-code/bin/kimi"
-if [ -x "$KIMI_BINARY" ]; then
-  BINARY="$KIMI_BINARY"
-else
-  BINARY=$(command -v kimi 2>/dev/null || echo "")
+# Refuse a PATH match under our own shims dir — it resolves to this alias's
+# sibling dispatcher shim (shims dir is ahead of ~/.local/bin on PATH) and
+# re-execs forever. Fall through to the clean "not installed" error instead.
+if [ -z "$BINARY" ] || [ ! -x "$BINARY" ]; then
+  BINARY=$(command -v grok 2>/dev/null || echo "")
+  case "$BINARY" in
+    "$HOME/.agents/.cache/shims/"*) BINARY="" ;;
+  esac
 fi`
-            : agent === 'droid'
-                ? `# Droid (Factory AI) installs a standalone native binary at ~/.local/bin/droid;
+        : agent === 'droid'
+            ? `# Droid (Factory AI) installs a standalone native binary at ~/.local/bin/droid;
 # there is no npm package and nothing lands in node_modules/.bin. The PATH
 # fallback refuses anything under our shims dir to avoid an infinite re-exec.
 DROID_BINARY="$HOME/.local/bin/droid"
@@ -719,7 +771,7 @@ else
     "$HOME/.agents/.cache/shims/"*) BINARY="" ;;
   esac
 fi`
-                : `BINARY="${versionDir}/node_modules/.bin/${agentConfig.cliCommand}"`;
+            : `BINARY="${versionDir}/node_modules/.bin/${agentConfig.cliCommand}"`;
     return `#!/bin/bash
 # Auto-generated by agents-cli - do not edit
 # ${VERSIONED_ALIAS_VERSION_MARKER} ${VERSIONED_ALIAS_SCHEMA_VERSION}
@@ -741,7 +793,7 @@ exec "$BINARY"${launchArgs} "$@"
  * alias doesn't exist or is a pre-v2 alias (no marker — treated as stale).
  */
 export function readVersionedAliasSchemaVersion(agent, version) {
-    const aliasPath = getVersionedAliasPath(agent, version);
+    const aliasPath = versionedAliasOnDiskPath(agent, version);
     if (!fs.existsSync(aliasPath))
         return null;
     try {
@@ -768,11 +820,19 @@ export function isVersionedAliasCurrent(agent, version) {
  * was upgraded.
  */
 export function ensureVersionedAliasCurrent(agent, version) {
-    const aliasPath = getVersionedAliasPath(agent, version);
-    if (!fs.existsSync(aliasPath)) {
+    if (!fs.existsSync(versionedAliasOnDiskPath(agent, version))) {
         createVersionedAlias(agent, version);
         return 'created';
     }
+    // A lingering extensionless bash alias on Windows shadows the `.cmd` in both
+    // cmd.exe and PowerShell (the dotted version reads as a file extension, and
+    // an exact filename match beats PATHEXT probing), ShellExecuting the bash
+    // script to the `.sh` editor association instead of launching the agent.
+    // Regenerate regardless of the `.cmd`'s stamp so the shadow gets deleted.
+    if (shimTargetsFor(process.platform).cmd && fs.existsSync(getVersionedAliasPath(agent, version))) {
+        createVersionedAlias(agent, version);
+        return 'updated';
+    }
     // Upgrade-only (newest-wins), same rationale as ensureShimCurrent: never
     // downgrade an alias stamped by a newer install sharing the shims dir.
     const onDisk = readVersionedAliasSchemaVersion(agent, version);
@@ -783,14 +843,38 @@ export function ensureVersionedAliasCurrent(agent, version) {
     return 'current';
 }
 /**
- * Get the filesystem path for a versioned alias script.
+ * Get the filesystem path for a versioned alias script — the logical
+ * (extensionless) launch name. On Windows this is not a real file (see
+ * versionedAliasOnDiskFile); stat/read checks must use the on-disk path.
  */
 export function getVersionedAliasPath(agent, version) {
     return path.join(getShimsDir(), `${AGENTS[agent].cliCommand}@${version}`);
 }
+/**
+ * The file createVersionedAlias actually materializes for a platform:
+ * `<cmd>@<version>.cmd` on Windows, the bare bash script on POSIX. Pure —
+ * testable on any host. Mirrors onDiskShimFile for the main shim.
+ */
+export function versionedAliasOnDiskFile(cliCommand, version, platform) {
+    const name = `${cliCommand}@${version}`;
+    return shimTargetsFor(platform).cmd ? `${name}.cmd` : name;
+}
+/** The on-disk versioned-alias path for the current platform. */
+function versionedAliasOnDiskPath(agent, version) {
+    return path.join(getShimsDir(), versionedAliasOnDiskFile(AGENTS[agent].cliCommand, version, process.platform));
+}
 /**
  * Create a versioned alias for a specific agent version.
  * e.g., claude@2.0.65
+ *
+ * Same platform split as createShim (shimTargetsFor): POSIX writes the
+ * extensionless bash script; Windows writes ONLY the `.cmd`. Unlike the main
+ * shim — where the bash file was merely dead weight — a bash alias next to the
+ * versioned `.cmd` is actively harmful: the dotted version suffix makes
+ * cmd.exe/PowerShell treat `claude@2.1.201` as a complete filename (extension
+ * `.201`), so the exact match wins over PATHEXT probing and the shell
+ * ShellExecutes the bash script to the `.sh` editor association — the editor
+ * opens, the agent never launches. Any legacy bash alias is deleted here.
  */
 export function createVersionedAlias(agent, version) {
     assertSafeVersion(version);
@@ -798,40 +882,42 @@ export function createVersionedAlias(agent, version) {
     const shimsDir = getShimsDir();
     const agentConfig = AGENTS[agent];
     const aliasPath = path.join(shimsDir, `${agentConfig.cliCommand}@${version}`);
-    const script = generateVersionedAliasScript(agent, version);
-    fs.writeFileSync(aliasPath, script, { mode: 0o755 });
-    if (IS_WINDOWS) {
-        writeWindowsCmdShim(aliasPath + '.cmd', `${agentConfig.cliCommand}@${version}`);
+    const targets = shimTargetsFor(process.platform);
+    if (targets.bash) {
+        fs.writeFileSync(aliasPath, generateVersionedAliasScript(agent, version), { mode: 0o755 });
+    }
+    else {
+        try {
+            fs.unlinkSync(aliasPath);
+        }
+        catch { }
+    }
+    if (targets.cmd) {
+        writeWindowsCmdShim(aliasPath + '.cmd', `${agentConfig.cliCommand}@${version}`, [`${VERSIONED_ALIAS_VERSION_MARKER} ${VERSIONED_ALIAS_SCHEMA_VERSION}`]);
     }
     return aliasPath;
 }
 /**
- * Remove a versioned alias for a specific agent version.
+ * Remove a versioned alias for a specific agent version. Removes whichever
+ * companions exist — the extensionless script (POSIX, or a legacy Windows
+ * install that wrote it) AND the `.cmd` (Windows) — mirroring removeShim.
  */
 export function removeVersionedAlias(agent, version) {
-    const shimsDir = getShimsDir();
-    const agentConfig = AGENTS[agent];
-    const aliasPath = path.join(shimsDir, `${agentConfig.cliCommand}@${version}`);
-    if (fs.existsSync(aliasPath)) {
-        fs.unlinkSync(aliasPath);
-        if (IS_WINDOWS) {
-            try {
-                fs.unlinkSync(aliasPath + '.cmd');
-            }
-            catch { }
+    const aliasPath = getVersionedAliasPath(agent, version);
+    let removed = false;
+    for (const p of [aliasPath, aliasPath + '.cmd']) {
+        if (fs.existsSync(p)) {
+            fs.unlinkSync(p);
+            removed = true;
         }
-        return true;
     }
-    return false;
+    return removed;
 }
 /**
- * Check if a versioned alias exists.
+ * Check if a versioned alias exists (the on-disk artifact for this platform).
  */
 export function versionedAliasExists(agent, version) {
-    const shimsDir = getShimsDir();
-    const agentConfig = AGENTS[agent];
-    const aliasPath = path.join(shimsDir, `${agentConfig.cliCommand}@${version}`);
-    return fs.existsSync(aliasPath);
+    return fs.existsSync(versionedAliasOnDiskPath(agent, version));
 }
 /**
  * Get the path to the agent's config directory in HOME.

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

@@ -17,7 +17,16 @@ export declare const SSH_TARGET_RE: RegExp;
 export declare function assertValidSshTarget(host: string): void;
 /** POSIX single-quote a string for safe interpolation into a remote shell command. */
 export declare function shellQuote(s: string): string;
-/** Hardened ssh options applied to every connection. */
+/**
+ * Hardened ssh options applied to every connection — the single baseline every
+ * `ssh` in the codebase composes from (directly here, or as `[...SSH_OPTS, …]`
+ * in the few callers that need extra flags like `-L`/`-N`/`ProxyCommand`).
+ *
+ * `ServerAliveInterval`/`ServerAliveCountMax` add in-connection keepalive: a
+ * silently-dropped link (laptop sleeps, Wi-Fi flips) is detected and the ssh
+ * process exits within ~45s instead of hanging forever — so a followed run or a
+ * long-lived `-N` tunnel can't leave a zombie ssh + socket pinned on the laptop.
+ */
 export declare const SSH_OPTS: readonly string[];
 export declare function controlOpts(): string[];
 export interface SshExecOptions {
@@ -27,7 +36,7 @@ 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`). */
+    /** Reuse a persistent control socket across calls (default true; see `controlOpts`). */
     multiplex?: boolean;
 }
 export interface SshExecResult {
@@ -44,6 +53,20 @@ export interface SshExecResult {
  * it); callers that build it from user input must `shellQuote` the pieces.
  */
 export declare function sshExec(target: string, remoteCmd: string, opts?: SshExecOptions): SshExecResult;
+export interface SshExecRawResult {
+    code: number | null;
+    stdout: Buffer;
+    stderr: Buffer;
+    timedOut: boolean;
+}
+/**
+ * Like {@link sshExec} but returns raw stdout/stderr Buffers — no UTF-8 decode.
+ *
+ * Use when byte-exactness matters, e.g. offset-tracked log tailing: a multibyte
+ * character split across a read boundary must stay raw bytes, not collapse to a
+ * U+FFFD replacement char (which would desync a byte offset from the wire).
+ */
+export declare function sshExecRaw(target: string, remoteCmd: string, opts?: SshExecOptions): SshExecRawResult;
 /** True if `target` is reachable over ssh (a passwordless `true` succeeds quickly). */
 export declare function sshReachable(target: string, timeoutMs?: number): boolean;
 export interface SshStreamOptions {
@@ -54,7 +77,7 @@ export interface SshStreamOptions {
      * leave it off and forward a non-interactive invocation instead.
      */
     tty?: boolean;
-    /** Reuse a persistent control socket across calls (see `controlOpts`). */
+    /** Reuse a persistent control socket across calls (default true; see `controlOpts`). */
     multiplex?: boolean;
 }
 /**

package/dist/lib/ssh-exec.js

@@ -29,11 +29,22 @@ export function shellQuote(s) {
         return s;
     return "'" + s.replace(/'/g, "'\\''") + "'";
 }
-/** Hardened ssh options applied to every connection. */
+/**
+ * Hardened ssh options applied to every connection — the single baseline every
+ * `ssh` in the codebase composes from (directly here, or as `[...SSH_OPTS, …]`
+ * in the few callers that need extra flags like `-L`/`-N`/`ProxyCommand`).
+ *
+ * `ServerAliveInterval`/`ServerAliveCountMax` add in-connection keepalive: a
+ * silently-dropped link (laptop sleeps, Wi-Fi flips) is detected and the ssh
+ * process exits within ~45s instead of hanging forever — so a followed run or a
+ * long-lived `-N` tunnel can't leave a zombie ssh + socket pinned on the laptop.
+ */
 export const SSH_OPTS = [
     '-o', 'StrictHostKeyChecking=accept-new',
     '-o', 'BatchMode=yes',
     '-o', 'ConnectTimeout=10',
+    '-o', 'ServerAliveInterval=15',
+    '-o', 'ServerAliveCountMax=3',
 ];
 /**
  * OpenSSH connection-multiplexing options. The first connection to a host opens
@@ -44,6 +55,12 @@ export const SSH_OPTS = [
  * 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.
  *
+ * This is **on by default** for every `sshExec`/`sshStream` call: the poll loops
+ * (`followHostTask`), readiness probes, and per-host fan-outs are exactly the
+ * high-frequency callers that benefit most from socket reuse, and they should
+ * never have to remember to opt in. A caller passes `multiplex: false` only for
+ * a genuine one-shot where a lingering 60s master is pure overhead.
+ *
  * 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.
@@ -79,13 +96,14 @@ export function controlOpts() {
  */
 export function sshExec(target, remoteCmd, opts = {}) {
     assertValidSshTarget(target);
-    const mux = opts.multiplex ? controlOpts() : [];
+    const mux = opts.multiplex === false ? [] : controlOpts();
     const args = [...SSH_OPTS, ...mux, ...(opts.extraSshArgs ?? []), target, remoteCmd];
     const res = spawnSync('ssh', args, {
         input: opts.input,
         encoding: 'utf-8',
         timeout: opts.timeoutMs,
         stdio: ['pipe', 'pipe', 'pipe'],
+        windowsHide: true,
     });
     const timedOut = !!(res.error && res.error.code === 'ETIMEDOUT');
     return {
@@ -95,6 +113,32 @@ export function sshExec(target, remoteCmd, opts = {}) {
         timedOut,
     };
 }
+/**
+ * Like {@link sshExec} but returns raw stdout/stderr Buffers — no UTF-8 decode.
+ *
+ * Use when byte-exactness matters, e.g. offset-tracked log tailing: a multibyte
+ * character split across a read boundary must stay raw bytes, not collapse to a
+ * U+FFFD replacement char (which would desync a byte offset from the wire).
+ */
+export function sshExecRaw(target, remoteCmd, opts = {}) {
+    assertValidSshTarget(target);
+    const mux = opts.multiplex === false ? [] : controlOpts();
+    const args = [...SSH_OPTS, ...mux, ...(opts.extraSshArgs ?? []), target, remoteCmd];
+    const res = spawnSync('ssh', args, {
+        input: opts.input,
+        // No `encoding` → spawnSync returns Buffers.
+        timeout: opts.timeoutMs,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        windowsHide: true,
+    });
+    const timedOut = !!(res.error && res.error.code === 'ETIMEDOUT');
+    return {
+        code: typeof res.status === 'number' ? res.status : null,
+        stdout: res.stdout ?? Buffer.alloc(0),
+        stderr: res.stderr ?? Buffer.alloc(0),
+        timedOut,
+    };
+}
 /** True if `target` is reachable over ssh (a passwordless `true` succeeds quickly). */
 export function sshReachable(target, timeoutMs = 10000) {
     return sshExec(target, 'true', { timeoutMs, multiplex: true }).code === 0;
@@ -108,7 +152,7 @@ export function sshReachable(target, timeoutMs = 10000) {
  */
 export function sshStream(target, remoteCmd, opts = {}) {
     assertValidSshTarget(target);
-    const mux = opts.multiplex ? controlOpts() : [];
+    const mux = opts.multiplex === false ? [] : controlOpts();
     const tty = opts.tty ? ['-tt'] : [];
     const args = [...SSH_OPTS, ...mux, ...tty, target, remoteCmd];
     const res = spawnSync('ssh', args, { stdio: 'inherit' });

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

@@ -28,7 +28,11 @@ export interface StartTunnelOptions {
      */
     detached?: boolean;
 }
-/** Build the ssh argv (after the `ssh` program name) for an `-L` tunnel. Pure. */
+/** Build the ssh argv (after the `ssh` program name) for an `-L` tunnel. Pure.
+ *
+ * Composes the shared hardened baseline (`SSH_OPTS`) rather than re-listing it,
+ * so the tunnel inherits the same options — crucially the keepalive, which lets
+ * a dropped `-N` tunnel exit instead of lingering as a zombie on the laptop. */
 export declare function buildTunnelArgs(user: string, host: string, localPort: number, remotePort: number): string[];
 /**
  * Spawn `ssh -L localPort:127.0.0.1:remotePort -N user@host`.
@@ -74,12 +78,13 @@ export declare function resolveRemoteDevice(name: string): Promise<{
     host: string;
 }>;
 /**
- * PowerShell that streams base64 from stdin, decodes it incrementally to
- * %LOCALAPPDATA%\agents\computer-helper-win.exe, and stops any running instance
- * first so the file isn't locked. The CryptoStream/FromBase64Transform decode
- * is streaming — the ~156MB exe never lands in memory whole on the remote.
+ * PowerShell that resolves the destination under %LOCALAPPDATA%\agents and
+ * stops any running instance first so the file is not locked. The caller copies
+ * the exe with scp and then verifies the byte count separately.
  */
 export declare function buildPushScript(): string;
+/** PowerShell that verifies scp wrote the expected number of bytes. */
+export declare function buildVerifyPushScript(remotePath: string, expectedBytes: number): string;
 /**
  * PowerShell that registers the daemon as a LOGON scheduled task. Interactive
  * logon type + Highest run level so the daemon runs in the real desktop session
@@ -90,6 +95,20 @@ 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;
+/** Convert a Windows path returned by PowerShell into the scp/SFTP path form. */
+export declare function scpRemotePath(remotePath: string): string;
+/**
+ * Build the scp argv used for the helper exe transfer. Exported so tests can
+ * assert the real binary copy path keeps BatchMode and does not route bytes
+ * through a PowerShell decoder.
+ */
+export declare function buildScpArgs(target: string, remotePath: string, filePath: string): string[];
+/**
+ * `setup --host`: push the exe, then register + start the LOGON task. Remote
+ * PowerShell hops go through `sshExec` (BatchMode key auth — the same hardening
+ * the browser driver and `agents ssh` use), and the large exe rides a binary
+ * scp transfer. Throws with the remote stderr on any failure.
+ */
 export declare function setupRemoteHelper(name: string): Promise<{
     target: string;
     taskName: string;