@phnx-labs/agents-cli 1.20.35 → 1.20.36

package/dist/lib/session/remote-list.js

@@ -0,0 +1,213 @@
+/**
+ * Cross-machine fan-out for the default `agents sessions` listing.
+ *
+ * `discoverSessions()` only scans the local disk. To browse the whole fleet in
+ * one list — without syncing anything — we run `agents sessions <same query>
+ * --json` on each peer over SSH and merge the parsed `SessionMeta[]`, tagging
+ * every row with the machine it came from so the picker/table can label and
+ * group by computer.
+ *
+ * This is the browse-listing sibling of `remote-active.ts` (which fans out
+ * `--active`): same transport, same device set, same recursion guard. The peer
+ * runs with `AGENTS_SESSIONS_LOCAL=1` so it answers only for itself and the
+ * sweep never recurses. A dead or slow host is skipped with a stderr note,
+ * never fatal — one asleep laptop must not blank the list.
+ */
+import { spawn } from 'child_process';
+import chalk from 'chalk';
+import { SSH_OPTS, controlOpts, assertValidSshTarget, shellQuote } from '../ssh-exec.js';
+import { sshTargetFor } from '../devices/connect.js';
+import { loadDevices } from '../devices/registry.js';
+import { remoteShellFor, buildWindowsAgentsCommand } from '../hosts/remote-cmd.js';
+import { resolveRemoteOsSync } from '../hosts/remote-os.js';
+import { machineId, normalizeHost } from './sync/config.js';
+import { NO_FANOUT_ENV } from './remote-active.js';
+import { terminalWidth } from './width.js';
+/** Per-host SSH budget. Slightly above SSH_OPTS' ConnectTimeout=10 so a
+ * reachable-but-slow remote still answers before we give up. */
+const REMOTE_TIMEOUT_MS = 12_000;
+/**
+ * The command run on each peer: answer for itself, as JSON, without recursing.
+ * `forwardedArgs` carry the caller's own query/filters (already including the
+ * leading `sessions` and a `--json`) so each peer returns a comparable slice.
+ * A Windows peer gets a PowerShell invocation (ssh lands in cmd.exe/PowerShell
+ * there, where `bash -lc` is not a command); every other OS keeps `bash -lc`.
+ */
+export function remoteListCommand(forwardedArgs, os) {
+    if (remoteShellFor(os) === 'powershell') {
+        return buildWindowsAgentsCommand({
+            args: forwardedArgs,
+            env: { [NO_FANOUT_ENV]: '1' },
+        });
+    }
+    const inner = [`${NO_FANOUT_ENV}=1`, 'agents', ...forwardedArgs].map((t, i) => i === 0 ? t : shellQuote(t)).join(' ');
+    return `bash -lc ${shellQuote(inner)}`;
+}
+/**
+ * Parse a peer's `sessions --json` stdout into `SessionMeta[]`, tagging each
+ * with `machine`. Defensive against version skew / partial output: non-JSON or
+ * a non-array yields `[]`, and non-object entries are dropped rather than
+ * throwing. The `machine` we dialed always wins over any value the peer set on
+ * its own rows, so grouping keys off the computer we asked. Exported for unit
+ * testing without a live tailnet.
+ */
+export function parseRemoteList(stdout, machine) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(parsed))
+        return [];
+    const out = [];
+    for (const x of parsed) {
+        if (x && typeof x === 'object' && !Array.isArray(x)) {
+            // `_remote` marks these as living on the peer's disk (not a local mirror),
+            // so the picker routes read/resume back over SSH instead of the local FS.
+            out.push({ ...x, machine, _remote: true });
+        }
+    }
+    return out;
+}
+/** Run one remote `agents sessions … --json` and capture stdout. Resolves
+ * `{ code: null }` on spawn error or timeout (host treated as dead). */
+function sshCapture(target, remoteCmd, timeoutMs) {
+    assertValidSshTarget(target);
+    return new Promise((resolve) => {
+        const args = [...SSH_OPTS, ...controlOpts(), target, remoteCmd];
+        const child = spawn('ssh', args, { stdio: ['ignore', 'pipe', 'ignore'] });
+        let stdout = '';
+        let settled = false;
+        const done = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({ code, stdout });
+        };
+        const timer = setTimeout(() => { child.kill('SIGKILL'); done(null); }, timeoutMs);
+        child.stdout.on('data', (d) => { stdout += d.toString(); });
+        child.on('error', () => done(null));
+        child.on('close', (code) => done(code));
+    });
+}
+async function fetchByTarget(target, machine, display, forwardedArgs, os) {
+    const { code, stdout } = await sshCapture(target, remoteListCommand(forwardedArgs, os), REMOTE_TIMEOUT_MS);
+    if (code !== 0) {
+        process.stderr.write(chalk.gray(`  ${display}: unreachable or no agents CLI — skipped\n`));
+        return [];
+    }
+    return parseRemoteList(stdout, machine);
+}
+/**
+ * Gather listing sessions from other machines. With an explicit `hosts` list
+ * (from `--host`), fan out to exactly those. Otherwise sweep the registered,
+ * online devices from `ag devices`, excluding this machine and any without an
+ * address. `forwardedArgs` are the caller's own sessions args (query + filters,
+ * already `--json`) so every peer returns the same slice this machine asked for.
+ */
+export async function gatherRemoteList(forwardedArgs, hosts) {
+    const self = machineId();
+    const targets = [];
+    if (hosts && hosts.length > 0) {
+        for (const h of hosts) {
+            try {
+                assertValidSshTarget(h);
+            }
+            catch {
+                process.stderr.write(chalk.gray(`  ${h}: not a valid ssh target — skipped\n`));
+                continue;
+            }
+            const bareHost = h.split('@').pop() || h;
+            targets.push({ target: h, machine: normalizeHost(bareHost), name: h, os: resolveRemoteOsSync(h) });
+        }
+    }
+    else {
+        let reg;
+        try {
+            reg = await loadDevices();
+        }
+        catch {
+            return { sessions: [], deviceCount: 0 };
+        }
+        for (const d of Object.values(reg)) {
+            if (d.tailscale?.online !== true)
+                continue;
+            if (normalizeHost(d.name) === self)
+                continue;
+            // Only machines that can actually run the CLI. iOS/tablet nodes register as
+            // `unknown` platform and can never answer, so skip them rather than burn a
+            // full ConnectTimeout on each.
+            if (d.platform !== 'windows' && d.platform !== 'linux' && d.platform !== 'macos')
+                continue;
+            try {
+                targets.push({ target: sshTargetFor(d), machine: normalizeHost(d.name), name: d.name, os: d.platform });
+            }
+            catch {
+                // No address on the profile — nothing to dial; skip silently.
+            }
+        }
+    }
+    const results = await Promise.all(targets.map((t) => fetchByTarget(t.target, t.machine, t.name, forwardedArgs, t.os)));
+    return { sessions: results.flat(), deviceCount: targets.length };
+}
+/** Resolve a peer's SSH target (and OS) from the device registry by its
+ * normalized machine id — the same id the fan-out tags rows with. Returns
+ * undefined when no registered device with an address matches. */
+export async function resolvePeerTarget(machine) {
+    let reg;
+    try {
+        reg = await loadDevices();
+    }
+    catch {
+        return undefined;
+    }
+    for (const d of Object.values(reg)) {
+        if (normalizeHost(d.name) !== machine)
+            continue;
+        try {
+            return { target: sshTargetFor(d), os: d.platform };
+        }
+        catch {
+            return undefined; // matched the machine, but it has no address to dial
+        }
+    }
+    return undefined;
+}
+/**
+ * Run `agents <args>` ON a peer over SSH, attached to this terminal (inherited
+ * stdio). `args` is the full arg vector after the binary — callers pass e.g.
+ * `['sessions', id, '--markdown']` or `['sessions', 'resume', id]`. Used when a
+ * picked session lives on another machine: its transcript and agent binary are
+ * there, so both reading (no TTY) and resuming (TTY) must execute on the peer —
+ * not via a local `--host` hop, which would discover locally and dead-end for a
+ * session that exists only on the peer. Resolves 'no-target' when the machine
+ * isn't a dialable registered device; the caller surfaces a clear message.
+ */
+export async function runOnPeer(args, machine, opts = {}) {
+    const peer = await resolvePeerTarget(machine);
+    if (!peer)
+        return 'no-target';
+    assertValidSshTarget(peer.target); // registry-sourced, but validate like the fan-out does
+    const cols = terminalWidth();
+    const remoteCmd = remoteShellFor(peer.os) === 'powershell'
+        ? buildWindowsAgentsCommand({ args, env: cols > 0 ? { COLUMNS: String(cols) } : undefined })
+        : `bash -lc ${shellQuote((cols > 0 ? [`COLUMNS=${cols}`] : []).concat(['agents', ...args].map(shellQuote)).join(' '))}`;
+    const sshArgs = [...SSH_OPTS, ...controlOpts()];
+    if (opts.tty)
+        sshArgs.push('-tt'); // force a PTY so the resumed agent is interactive
+    sshArgs.push(peer.target, remoteCmd);
+    return new Promise((resolve) => {
+        const child = spawn('ssh', sshArgs, { stdio: 'inherit' });
+        // ssh prints its own connection errors to the inherited stderr; a spawn
+        // failure (e.g. ssh not on PATH) has no such output, so name it. Either way
+        // we resolve once it settles so the picker flow completes.
+        child.on('error', (err) => {
+            process.stderr.write(chalk.red(`Failed to reach ${machine}: ${err?.message ?? 'ssh failed to launch'}\n`));
+            resolve('ok');
+        });
+        child.on('close', () => resolve('ok'));
+    });
+}

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

@@ -22,8 +22,14 @@ export declare function buildForwardedArgs(argv: string[], hosts?: Set<string>):
  * Build the single remote command string for `ssh <host> <cmd>`. Forwarded args
  * are quoted for the inner login shell, then the whole `agents …` invocation is
  * quoted again so it survives `bash -lc <...>`.
+ *
+ * `os` selects the remote shell: a Windows host gets a PowerShell invocation
+ * (ssh lands in cmd.exe/PowerShell there, where `bash -lc` does not exist);
+ * anything else — including unknown/absent — keeps the POSIX form unchanged.
+ * The forwarded terminal width rides across as an env var either way so the
+ * remote renders its table to the local screen.
  */
-export declare function buildRemoteCommand(forwardedArgs: string[], columns?: number): string;
+export declare function buildRemoteCommand(forwardedArgs: string[], columns?: number, os?: string): string;
 /** The four outcomes of one `ssh <host> agents sessions …` invocation. */
 export type SshOutcome = 'ok' | 'unreachable' | 'query-failed' | 'spawn-error';
 /**

package/dist/lib/session/remote.js

@@ -28,6 +28,8 @@ import { createHash } from 'crypto';
 import chalk from 'chalk';
 import { getCacheDir } from '../state.js';
 import { SSH_OPTS, controlOpts } from '../ssh-exec.js';
+import { remoteShellFor, buildWindowsAgentsCommand } from '../hosts/remote-cmd.js';
+import { resolveRemoteOsSync } from '../hosts/remote-os.js';
 import { formatRelativeTime } from './relative-time.js';
 import { terminalWidth } from './width.js';
 /**
@@ -88,8 +90,18 @@ export function buildForwardedArgs(argv, hosts = new Set()) {
  * Build the single remote command string for `ssh <host> <cmd>`. Forwarded args
  * are quoted for the inner login shell, then the whole `agents …` invocation is
  * quoted again so it survives `bash -lc <...>`.
+ *
+ * `os` selects the remote shell: a Windows host gets a PowerShell invocation
+ * (ssh lands in cmd.exe/PowerShell there, where `bash -lc` does not exist);
+ * anything else — including unknown/absent — keeps the POSIX form unchanged.
+ * The forwarded terminal width rides across as an env var either way so the
+ * remote renders its table to the local screen.
  */
-export function buildRemoteCommand(forwardedArgs, columns) {
+export function buildRemoteCommand(forwardedArgs, columns, os) {
+    if (remoteShellFor(os) === 'powershell') {
+        const env = columns && columns > 0 ? { COLUMNS: String(columns) } : undefined;
+        return buildWindowsAgentsCommand({ args: forwardedArgs, env });
+    }
     const inner = ['agents', ...forwardedArgs].map(shellQuote).join(' ');
     // Forward the caller's terminal width so the remote renders the table to the
     // local screen (over SSH the remote's own COLUMNS is unset/wrong). `VAR=val
@@ -176,12 +188,14 @@ export function runRemoteSessions(hosts, argv = process.argv) {
     for (const host of hosts)
         assertValidSshTarget(host); // fail fast on any bad target
     const forwarded = buildForwardedArgs(argv, new Set(hosts));
-    const remoteCmd = buildRemoteCommand(forwarded, terminalWidth());
+    const cols = terminalWidth();
     const multi = hosts.length > 1;
     let failures = 0;
     for (const host of hosts) {
         if (multi)
             process.stdout.write(chalk.cyan(`\n── ${host} ──\n`));
+        // Per-host: a Windows peer needs a PowerShell command, POSIX peers `bash -lc`.
+        const remoteCmd = buildRemoteCommand(forwarded, cols, resolveRemoteOsSync(host));
         const res = spawnSync('ssh', [...SSH_OPTS, ...controlOpts(), host, remoteCmd], {
             encoding: 'utf8',
             maxBuffer: 64 * 1024 * 1024,

package/dist/lib/session/sync/config.d.ts

@@ -33,18 +33,4 @@ export declare function loadR2Config(): R2Config;
  * does not re-storm every cycle. `now` is injectable for tests.
  */
 export declare function isSyncConfigured(now?: number): boolean;
-/**
- * Normalize a raw hostname into a stable device id: first label only,
- * lowercased, non-alphanumerics collapsed to hyphens. `zion.tail…ts.net` and
- * `ZION` both become `zion`. The single source for this transform — machineId()
- * and cross-machine session grouping must agree or the local machine won't
- * match its own registry key.
- */
-export declare function normalizeHost(raw: string): string;
-/**
- * This machine's stable, human-readable id, used as its R2 prefix and mirror
- * directory name. Tailnet hostnames (zion, yosemite-s0, mac-mini) are already
- * unique and readable; we lowercase and strip any domain suffix. Overridable
- * via AGENTS_SYNC_MACHINE_ID for tests and unusual setups.
- */
-export declare function machineId(): string;
+export { machineId, normalizeHost } from '../../machine-id.js';

package/dist/lib/session/sync/config.js

@@ -3,7 +3,6 @@
  * machine's stable identity. Credentials come from the `r2.backups` secrets
  * bundle (OS keychain on macOS, libsecret on Linux) — never from env or disk.
  */
-import * as os from 'os';
 import { readAndResolveBundleEnv } from '../../secrets/bundles.js';
 /** Secrets bundle holding the R2 credentials. */
 export const SYNC_BUNDLE = 'r2.backups';
@@ -93,22 +92,7 @@ export function isSyncConfigured(now = Date.now()) {
         return false;
     }
 }
-/**
- * Normalize a raw hostname into a stable device id: first label only,
- * lowercased, non-alphanumerics collapsed to hyphens. `zion.tail…ts.net` and
- * `ZION` both become `zion`. The single source for this transform — machineId()
- * and cross-machine session grouping must agree or the local machine won't
- * match its own registry key.
- */
-export function normalizeHost(raw) {
-    return raw.split('.')[0].trim().toLowerCase().replace(/[^a-z0-9_-]/g, '-') || 'unknown';
-}
-/**
- * This machine's stable, human-readable id, used as its R2 prefix and mirror
- * directory name. Tailnet hostnames (zion, yosemite-s0, mac-mini) are already
- * unique and readable; we lowercase and strip any domain suffix. Overridable
- * via AGENTS_SYNC_MACHINE_ID for tests and unusual setups.
- */
-export function machineId() {
-    return normalizeHost(process.env.AGENTS_SYNC_MACHINE_ID || os.hostname());
-}
+// machineId() and normalizeHost() now live in the dependency-free leaf
+// ../../machine-id.ts so low-level modules (state.ts) can use them without an
+// import cycle. Re-exported here for existing importers.
+export { machineId, normalizeHost } from '../../machine-id.js';

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

@@ -78,6 +78,23 @@ export interface SessionMeta {
      * `entrypoint` field ('sdk-cli' for team spawns, 'cli' for real sessions).
      */
     isTeamOrigin?: boolean;
+    /**
+     * The machine (normalized hostname) this session's transcript originated on:
+     * the local machine for live-home sessions, or the origin machine parsed from
+     * the cross-machine mirror path (backups/<agent>/<machine>/…, see
+     * sync/agents.ts). Populated by discoverSessions for the listing/picker;
+     * undefined for sessions obtained outside that path.
+     */
+    machine?: string;
+    /**
+     * True only for rows pulled from another machine over the live cross-machine
+     * fan-out (`remote-list.ts`) — their transcript is on that peer's disk, so
+     * reading/resuming has to hop back over SSH. Distinct from `machine`, which is
+     * also set on locally-readable synced mirrors: a mirror is machine-tagged but
+     * its `filePath` is a local path, so it must NOT be treated as remote. Set by
+     * `parseRemoteList`; transient (never persisted, stripped from --json).
+     */
+    _remote?: boolean;
     /** Terms that matched the current search query */
     _matchedTerms?: string[];
     /** BM25 relevance score from the most recent content-index search */

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 = 21;
+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.
@@ -134,8 +134,19 @@ export declare function removeShim(agent: AgentId): boolean;
  *        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.
- */
-export declare const VERSIONED_ALIAS_SCHEMA_VERSION = 10;
+ *  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
@@ -157,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

@@ -208,7 +208,10 @@ async function promptConflictStrategy(conflictInfos) {
 //        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.
-export const SHIM_SCHEMA_VERSION = 21;
+// 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) {
@@ -236,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
@@ -580,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);
 }
@@ -640,8 +653,19 @@ export function removeShim(agent) {
  *        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 = 10;
+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
@@ -669,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'
             ? `
@@ -765,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 {
@@ -792,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);
@@ -807,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);
@@ -822,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.js

@@ -103,6 +103,7 @@ export function sshExec(target, remoteCmd, opts = {}) {
         encoding: 'utf-8',
         timeout: opts.timeoutMs,
         stdio: ['pipe', 'pipe', 'pipe'],
+        windowsHide: true,
     });
     const timedOut = !!(res.error && res.error.code === 'ETIMEDOUT');
     return {
@@ -128,6 +129,7 @@ export function sshExecRaw(target, remoteCmd, opts = {}) {
         // No `encoding` → spawnSync returns Buffers.
         timeout: opts.timeoutMs,
         stdio: ['pipe', 'pipe', 'pipe'],
+        windowsHide: true,
     });
     const timedOut = !!(res.error && res.error.code === 'ETIMEDOUT');
     return {