@phnx-labs/agents-cli 1.20.32 → 1.20.34

package/dist/lib/hosts/passthrough.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Generic `--host` passthrough — the single choke point that runs an allowlisted
+ * `agents <command>` on a remote host instead of locally, so read-only and
+ * config commands (`view`, `usage`, `cost`, `doctor`, `inspect`, `list`, `sync`)
+ * and the team lifecycle (`teams …`) all gain remote support with no per-command
+ * code. Called once from `index.ts` before commander parses; returns `true` when
+ * it handled the invocation (the local command must then NOT run).
+ *
+ * Transport is SSH (via `ssh-exec.ts`), never a daemon: SSH is the one hardened
+ * choke point already used everywhere, and it gives auth + encryption + host-key
+ * trust for free. Read-only commands stream synchronously (`sshStream`); the one
+ * long-running case — `teams start --watch` — dispatches detached so the remote
+ * supervisor outlives a dropped connection.
+ *
+ * `run` and `sessions` are deliberately absent from the table below: they own
+ * richer `--host` handling in their own command actions (detached run dispatch;
+ * multi-host session fan-out) and must fall through to it.
+ */
+/** Pull the value of `--host`/`-H`/`--remote-cwd` (any form) out of an argv. */
+export declare function flagValue(args: string[], long: string, short?: string): string | undefined;
+/**
+ * Route `agents <command> … --host <name>` to a remote if the command is
+ * host-routable and a `--host` was given. Returns `false` (run locally) when
+ * there is no `--host`, the command isn't in the table, or the target is this
+ * very machine.
+ *
+ * @param command the resolved subcommand name (`process.argv`'s first non-flag).
+ * @param allArgs `process.argv.slice(2)` — the command name followed by its args.
+ */
+export declare function maybeRunOnHost(command: string, allArgs: string[]): Promise<boolean>;

package/dist/lib/hosts/passthrough.js

@@ -0,0 +1,141 @@
+/**
+ * Generic `--host` passthrough — the single choke point that runs an allowlisted
+ * `agents <command>` on a remote host instead of locally, so read-only and
+ * config commands (`view`, `usage`, `cost`, `doctor`, `inspect`, `list`, `sync`)
+ * and the team lifecycle (`teams …`) all gain remote support with no per-command
+ * code. Called once from `index.ts` before commander parses; returns `true` when
+ * it handled the invocation (the local command must then NOT run).
+ *
+ * Transport is SSH (via `ssh-exec.ts`), never a daemon: SSH is the one hardened
+ * choke point already used everywhere, and it gives auth + encryption + host-key
+ * trust for free. Read-only commands stream synchronously (`sshStream`); the one
+ * long-running case — `teams start --watch` — dispatches detached so the remote
+ * supervisor outlives a dropped connection.
+ *
+ * `run` and `sessions` are deliberately absent from the table below: they own
+ * richer `--host` handling in their own command actions (detached run dispatch;
+ * multi-host session fan-out) and must fall through to it.
+ */
+import chalk from 'chalk';
+import { assertValidSshTarget, sshStream } from '../ssh-exec.js';
+import { resolveHost, resolveHostByCap } from './registry.js';
+import { sshTargetFor } from './types.js';
+import { dispatchAgentsCommand } from './dispatch.js';
+import { stripRoutingFlags, buildRemoteAgentsInvocation, HOST_ROUTING_SPECS, } from './remote-cmd.js';
+import { machineId } from '../session/sync/config.js';
+const REMOTE_PASSTHROUGH = {
+    view: {},
+    usage: {},
+    cost: {},
+    doctor: {},
+    inspect: {},
+    list: {},
+    sync: { nonInteractive: ['--yes'] },
+    teams: {},
+};
+/** `--no-tty` is stripped like the routing flags but carries no value. */
+const STRIP_SPECS = [...HOST_ROUTING_SPECS, { long: 'no-tty', takesValue: false }];
+/** Pull the value of `--host`/`-H`/`--remote-cwd` (any form) out of an argv. */
+export function flagValue(args, long, short) {
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === `--${long}` || (short && a === `-${short}`))
+            return args[i + 1];
+        if (a.startsWith(`--${long}=`))
+            return a.slice(long.length + 3);
+        if (short && a.startsWith(`-${short}=`))
+            return a.slice(short.length + 2);
+        if (short && new RegExp(`^-${short}(.+)`).test(a))
+            return a.slice(2);
+    }
+    return undefined;
+}
+/** Synthesize a `Host` for a raw `user@host` / bare-alias target (not enrolled). */
+function syntheticHost(target) {
+    const at = target.indexOf('@');
+    if (at !== -1) {
+        return { name: target, provider: 'local', source: 'inline', user: target.slice(0, at), address: target.slice(at + 1) };
+    }
+    // Bare name: ssh resolves it from ~/.ssh/config, or connects to it as a hostname.
+    return { name: target, provider: 'local', source: 'ssh-config' };
+}
+/** Resolve a `--host` value to a Host: enrolled name → capability tag → raw target. */
+async function resolveTargetHost(name, any) {
+    const enrolled = await resolveHost(name);
+    if (enrolled)
+        return enrolled;
+    try {
+        return await resolveHostByCap(name, any);
+    }
+    catch (e) {
+        // "Multiple hosts tagged …" is actionable — surface it. "No host tagged" falls
+        // through to treating the value as a literal ssh target.
+        if (e instanceof Error && e.message.startsWith('Multiple hosts'))
+            throw e;
+    }
+    assertValidSshTarget(name); // rejects injection / flag-smuggling before it reaches ssh
+    return syntheticHost(name);
+}
+/**
+ * Route `agents <command> … --host <name>` to a remote if the command is
+ * host-routable and a `--host` was given. Returns `false` (run locally) when
+ * there is no `--host`, the command isn't in the table, or the target is this
+ * very machine.
+ *
+ * @param command the resolved subcommand name (`process.argv`'s first non-flag).
+ * @param allArgs `process.argv.slice(2)` — the command name followed by its args.
+ */
+export async function maybeRunOnHost(command, allArgs) {
+    const spec = REMOTE_PASSTHROUGH[command];
+    if (!spec)
+        return false;
+    const hostName = flagValue(allArgs, 'host', 'H');
+    if (!hostName)
+        return false;
+    // Running against your own machine is just a local run — skip the SSH round-trip.
+    // `machineId()` is the same self-identifier the device registry and session
+    // sync use (lowercased short hostname); compare case-insensitively.
+    if (hostName.toLowerCase() === machineId())
+        return false;
+    const remoteCwd = flagValue(allArgs, 'remote-cwd');
+    const any = allArgs.includes('--any');
+    let host;
+    try {
+        host = await resolveTargetHost(hostName, any);
+    }
+    catch (e) {
+        console.error(chalk.red(e instanceof Error ? e.message : String(e)));
+        process.exitCode = 1;
+        return true;
+    }
+    const target = sshTargetFor(host);
+    // Interactive only when our own stdout is a terminal and the caller didn't opt
+    // out — otherwise force the command's non-interactive path so no half-drawn
+    // picker is piped into a file or another program.
+    const interactive = !!process.stdout.isTTY && !allArgs.includes('--no-tty');
+    let forwarded = stripRoutingFlags(allArgs, STRIP_SPECS);
+    if (!interactive && spec.nonInteractive)
+        forwarded = [...forwarded, ...spec.nonInteractive];
+    // The one long-running case: keep the remote team supervisor alive past a
+    // disconnect by dispatching it detached (nohup), still streaming live.
+    const isWatchedTeamStart = command === 'teams' && forwarded[1] === 'start' && forwarded.includes('--watch');
+    if (isWatchedTeamStart) {
+        try {
+            const { exitCode } = await dispatchAgentsCommand(host, { forwardedArgs: forwarded, remoteCwd });
+            process.exitCode = exitCode && exitCode > 0 ? exitCode : 0;
+        }
+        catch (e) {
+            console.error(chalk.red(e instanceof Error ? e.message : String(e)));
+            process.exitCode = 1;
+        }
+        return true;
+    }
+    const remoteCmd = buildRemoteAgentsInvocation(forwarded, remoteCwd);
+    const code = sshStream(target, remoteCmd, { tty: interactive, multiplex: true });
+    if (code === 255) {
+        console.error(chalk.red(`${host.name}: unreachable over SSH (asleep, offline, or host key changed?).`) +
+            chalk.gray(' Check: agents hosts check ' + host.name));
+    }
+    process.exitCode = code;
+    return true;
+}

package/dist/lib/hosts/remote-cmd.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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`.
+ */
+/** A flag to strip from a forwarded argv, with whether it consumes a value. */
+export interface StripSpec {
+    /** Long form without leading dashes, e.g. `host`, `remote-cwd`. */
+    long: string;
+    /** Optional single-letter short form without the dash, e.g. `H`. */
+    short?: string;
+    /** True when the flag takes a following value token (`--host <name>`). */
+    takesValue: boolean;
+}
+/**
+ * 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 declare function stripRoutingFlags(args: string[], specs: StripSpec[]): string[];
+/** The routing flags every `--host`-capable command shares. */
+export declare const HOST_ROUTING_SPECS: StripSpec[];
+/**
+ * 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 declare function buildRemoteAgentsInvocation(forwardedArgs: string[], remoteCwd?: string): string;

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/platform/winpath.d.ts

@@ -4,12 +4,41 @@ export interface WinPathResult {
     alreadyPresent?: boolean;
     error?: string;
 }
+/**
+ * Compute the new User PATH from the RAW (unexpanded) current value. Pure and
+ * OS-independent — the single source of truth for the prepend/dedup logic.
+ *
+ * Idempotent: returns `{ changed: false }` (value unchanged, verbatim) when
+ * `dir` is already the first `;`-split entry. Otherwise removes every existing
+ * occurrence of `dir` and prepends it, dropping empty segments — matching POSIX
+ * `export PATH="${dir}:$PATH"`. `%VAR%` segments are preserved verbatim (never
+ * expanded), which is the #308 regression this fix targets.
+ */
+export declare function computeNewUserPath(currentRaw: string, dir: string): {
+    changed: boolean;
+    value: string;
+};
+/**
+ * Decide whether to write the User PATH back as REG_EXPAND_SZ (ExpandString) vs
+ * REG_SZ (String). Pure — testable on any host.
+ *
+ * True (expandable) when the original value was already ExpandString, when the
+ * raw value contains a `%VAR%` reference, or when `Path` was absent (default to
+ * ExpandString — Windows' native Path type). Only a plain String value with no
+ * `%` stays REG_SZ. `originalKind` is the .NET RegistryValueKind name
+ * (`ExpandString`/`String`/…) or `null`/`Absent` when `Path` had no value.
+ */
+export declare function shouldWriteExpandable(originalKind: string | null, rawValue: string): boolean;
 /**
  * Prepend `dir` to the Windows User PATH. Idempotent: a no-op when `dir` is
  * already first; moves it to the front when it exists but is positioned later
  * (e.g. appended by an older install) so it overrides conflicting entries.
- * `dir` is passed via an env var so it is never interpolated into the script
- * text.
+ *
+ * Reads the RAW registry value (preserving `%VAR%` and the REG_EXPAND_SZ type),
+ * computes the new value in TS via `computeNewUserPath`, and only writes when
+ * the value actually changes — preserving the original value type and
+ * broadcasting WM_SETTINGCHANGE. `dir` and the computed value are passed via env
+ * vars so they are never interpolated into the script text.
  */
 export declare function prependToWindowsUserPath(dir: string): WinPathResult;
 /**

package/dist/lib/platform/winpath.js

@@ -1,9 +1,16 @@
 /**
  * Windows User PATH + execution-policy primitives.
  *
- * The single place that mutates the Windows User PATH via the .NET environment
- * API (which writes the registry AND broadcasts WM_SETTINGCHANGE — the correct
- * analog of editing a shell rc file: no `setx` truncation, no manual step).
+ * The single place that mutates the Windows User PATH. It reads and writes the
+ * RAW registry value via `Microsoft.Win32.Registry` (NOT the .NET
+ * `[Environment]::*Environment*Variable` API, which expands `%VAR%` references
+ * on read and downgrades REG_EXPAND_SZ to REG_SZ on write — issue #308,
+ * dotnet/runtime#89695 / #1442). The prepend/dedup itself is computed in TS
+ * (`computeNewUserPath`, the single source of truth) so it has unit coverage on
+ * every OS; PowerShell is used only for the registry primitives. Because a raw
+ * `SetValue` does NOT broadcast the change (the old `[Environment]` API did), the
+ * write script broadcasts WM_SETTINGCHANGE itself so a new terminal picks up the
+ * PATH without re-login.
  * Consumers: `shims.ts` (shims dir) and `scripts/postinstall.js` (npm global-bin
  * dir, so the `agents` command itself resolves).
  *
@@ -12,34 +19,136 @@
  */
 import { execFileSync } from 'child_process';
 import * as path from 'path';
+/**
+ * Compute the new User PATH from the RAW (unexpanded) current value. Pure and
+ * OS-independent — the single source of truth for the prepend/dedup logic.
+ *
+ * Idempotent: returns `{ changed: false }` (value unchanged, verbatim) when
+ * `dir` is already the first `;`-split entry. Otherwise removes every existing
+ * occurrence of `dir` and prepends it, dropping empty segments — matching POSIX
+ * `export PATH="${dir}:$PATH"`. `%VAR%` segments are preserved verbatim (never
+ * expanded), which is the #308 regression this fix targets.
+ */
+export function computeNewUserPath(currentRaw, dir) {
+    const parts = currentRaw.split(';').filter((p) => p !== '');
+    if (parts.length > 0 && parts[0] === dir) {
+        return { changed: false, value: currentRaw };
+    }
+    const others = parts.filter((p) => p !== dir);
+    return { changed: true, value: [dir, ...others].join(';') };
+}
+/**
+ * Decide whether to write the User PATH back as REG_EXPAND_SZ (ExpandString) vs
+ * REG_SZ (String). Pure — testable on any host.
+ *
+ * True (expandable) when the original value was already ExpandString, when the
+ * raw value contains a `%VAR%` reference, or when `Path` was absent (default to
+ * ExpandString — Windows' native Path type). Only a plain String value with no
+ * `%` stays REG_SZ. `originalKind` is the .NET RegistryValueKind name
+ * (`ExpandString`/`String`/…) or `null`/`Absent` when `Path` had no value.
+ */
+export function shouldWriteExpandable(originalKind, rawValue) {
+    if (originalKind === null || originalKind === 'Absent')
+        return true;
+    if (originalKind === 'ExpandString')
+        return true;
+    return rawValue.includes('%');
+}
+// Sentinel separating the value kind from the (possibly '%'-laden) raw value in
+// the read script's stdout — PATH entries never contain a newline, so an
+// exclusive line marker parses unambiguously.
+const READ_MARKER = '===AGENTS-PATH-VALUE===';
+// Reads the RAW User PATH preserving REG_EXPAND_SZ: DoNotExpandEnvironmentNames
+// keeps `%VAR%` literal, and GetValueKind reports the original type (throws when
+// 'Path' is absent -> caught, reported as Absent).
+const READ_SCRIPT = [
+    "$key = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey('Environment', $false)",
+    'if ($null -eq $key) {',
+    "  Write-Output 'KIND:Absent'",
+    `  Write-Output '${READ_MARKER}'`,
+    "  Write-Output ''",
+    '} else {',
+    "  try { $kind = $key.GetValueKind('Path').ToString() } catch { $kind = 'Absent' }",
+    "  $val = $key.GetValue('Path', '', [Microsoft.Win32.RegistryValueOptions]::DoNotExpandEnvironmentNames)",
+    "  Write-Output ('KIND:' + $kind)",
+    `  Write-Output '${READ_MARKER}'`,
+    '  Write-Output $val',
+    '}',
+].join('\n');
+// Writes the computed value back with the preserved kind and broadcasts
+// WM_SETTINGCHANGE (raw SetValue does not, unlike the old [Environment] API).
+// The value comes in via AGENTS_WINPATH_VALUE so it is never interpolated into
+// the script text (preserves the no-injection property for '%'-laden paths).
+const WRITE_SCRIPT = [
+    "$key = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey('Environment', $true)",
+    "if ($null -eq $key) { $key = [Microsoft.Win32.Registry]::CurrentUser.CreateSubKey('Environment') }",
+    '$val = $env:AGENTS_WINPATH_VALUE',
+    "if ($env:AGENTS_WINPATH_EXPAND -eq '1') {",
+    '  $kind = [Microsoft.Win32.RegistryValueKind]::ExpandString',
+    '} else {',
+    '  $kind = [Microsoft.Win32.RegistryValueKind]::String',
+    '}',
+    "$key.SetValue('Path', $val, $kind)",
+    'Add-Type @"',
+    'using System;',
+    'using System.Runtime.InteropServices;',
+    'public static class AgentsWinPath {',
+    '  [DllImport("user32.dll", SetLastError=true, CharSet=CharSet.Auto)]',
+    '  public static extern IntPtr SendMessageTimeout(IntPtr hWnd, uint Msg, UIntPtr wParam, string lParam, uint fuFlags, uint uTimeout, out UIntPtr lpdwResult);',
+    '}',
+    '"@',
+    '$res = [UIntPtr]::Zero',
+    // HWND_BROADCAST=0xffff, WM_SETTINGCHANGE=0x1a, SMTO_ABORTIFHUNG=2, 5s timeout
+    "[AgentsWinPath]::SendMessageTimeout([IntPtr]0xffff, 0x1a, [UIntPtr]::Zero, 'Environment', 2, 5000, [ref]$res) | Out-Null",
+    "Write-Output 'written'",
+].join('\n');
+function runPowerShell(script, extraEnv) {
+    return execFileSync('powershell', ['-NoProfile', '-NonInteractive', '-Command', script], {
+        encoding: 'utf-8',
+        env: extraEnv ? { ...process.env, ...extraEnv } : process.env,
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+}
+/** Parse the read script's stdout into the original value kind and RAW value. */
+function parseReadOutput(out) {
+    const idx = out.indexOf(READ_MARKER);
+    if (idx === -1)
+        return { kind: null, raw: '' };
+    const head = out.slice(0, idx);
+    const kindMatch = head.match(/KIND:(\S+)/);
+    const kind = kindMatch ? kindMatch[1] : null;
+    // Everything after the marker line, minus the leading/trailing newline PS adds.
+    const raw = out
+        .slice(idx + READ_MARKER.length)
+        .replace(/^\r?\n/, '')
+        .replace(/\r?\n$/, '');
+    return { kind, raw };
+}
 /**
  * Prepend `dir` to the Windows User PATH. Idempotent: a no-op when `dir` is
  * already first; moves it to the front when it exists but is positioned later
  * (e.g. appended by an older install) so it overrides conflicting entries.
- * `dir` is passed via an env var so it is never interpolated into the script
- * text.
+ *
+ * Reads the RAW registry value (preserving `%VAR%` and the REG_EXPAND_SZ type),
+ * computes the new value in TS via `computeNewUserPath`, and only writes when
+ * the value actually changes — preserving the original value type and
+ * broadcasting WM_SETTINGCHANGE. `dir` and the computed value are passed via env
+ * vars so they are never interpolated into the script text.
  */
 export function prependToWindowsUserPath(dir) {
-    const script = [
-        '$d = $env:AGENTS_WINPATH_DIR',
-        "$u = [Environment]::GetEnvironmentVariable('Path','User')",
-        "if ($null -eq $u) { $u = '' }",
-        "$parts = @($u -split ';' | Where-Object { $_ -ne '' })",
-        // Already first — nothing to do
-        "if ($parts.Count -gt 0 -and $parts[0] -eq $d) { 'present' } else {",
-        // Remove any existing occurrence then prepend, matching POSIX `export PATH="${dir}:$PATH"`
-        "  $newParts = @($d) + @($parts | Where-Object { $_ -ne $d })",
-        "  [Environment]::SetEnvironmentVariable('Path', ($newParts -join ';'), 'User')",
-        "  'added'",
-        '}',
-    ].join('\n');
     try {
-        const out = execFileSync('powershell', ['-NoProfile', '-NonInteractive', '-Command', script], {
-            encoding: 'utf-8',
-            env: { ...process.env, AGENTS_WINPATH_DIR: dir },
-            stdio: ['ignore', 'pipe', 'pipe'],
-        }).trim();
-        return { success: true, alreadyPresent: out.includes('present') };
+        const readOut = runPowerShell(READ_SCRIPT);
+        const { kind, raw } = parseReadOutput(readOut);
+        const { changed, value } = computeNewUserPath(raw, dir);
+        if (!changed) {
+            return { success: true, alreadyPresent: true };
+        }
+        const expandable = shouldWriteExpandable(kind, value);
+        runPowerShell(WRITE_SCRIPT, {
+            AGENTS_WINPATH_VALUE: value,
+            AGENTS_WINPATH_EXPAND: expandable ? '1' : '0',
+        });
+        return { success: true, alreadyPresent: false };
     }
     catch (err) {
         return { success: false, error: `Could not update the Windows user PATH: ${err.message}` };

package/dist/lib/pwsh.d.ts

@@ -0,0 +1,11 @@
+/**
+ * PowerShell `-EncodedCommand` helper.
+ *
+ * Base64 of a script's UTF-16LE bytes is a single quote-free token, so it rides
+ * through Node spawn → Windows sshd → cmd.exe with zero escaping hazards
+ * (hand-quoted `powershell -Command "…"` is fragile the moment a path, URL, or
+ * newline is involved). Shared by the browser SSH driver (which builds a
+ * `powershell -EncodedCommand …` string) and the Windows secrets backend (which
+ * spawns powershell.exe with an argv array).
+ */
+export declare function encodePwshBase64(script: string): string;

package/dist/lib/pwsh.js

@@ -0,0 +1,13 @@
+/**
+ * PowerShell `-EncodedCommand` helper.
+ *
+ * Base64 of a script's UTF-16LE bytes is a single quote-free token, so it rides
+ * through Node spawn → Windows sshd → cmd.exe with zero escaping hazards
+ * (hand-quoted `powershell -Command "…"` is fragile the moment a path, URL, or
+ * newline is involved). Shared by the browser SSH driver (which builds a
+ * `powershell -EncodedCommand …` string) and the Windows secrets backend (which
+ * spawns powershell.exe with an argv array).
+ */
+export function encodePwshBase64(script) {
+    return Buffer.from(script, 'utf16le').toString('base64');
+}

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

@@ -25,6 +25,19 @@
 import type { SecretsBundle } from './bundles.js';
 /** Default lifetime of an unlocked bundle when `--ttl` is not given. */
 export declare const DEFAULT_TTL_MS: number;
+/**
+ * Reserved store-key prefix for the `secrets list` metadata snapshot cache.
+ * The broker holds the resolved bundle-metadata array (names/policy/timestamps,
+ * NO resolved secret values beyond the literals already in metadata) keyed by a
+ * hash of the current keychain bundle name-set, so the second and later
+ * `secrets list` within the daily window read metadata without a Touch ID
+ * prompt. Keyed by the name-set hash so adding/removing/renaming a bundle
+ * changes the key and misses the cache automatically — no active invalidation.
+ * The '!' sentinel can never collide with a real bundle name
+ * (BUNDLE_NAME_PATTERN requires an alphanumeric first char) and is safe as
+ * spawnSync argv (unlike a NUL byte); `status` hides these entries.
+ */
+export declare const META_CACHE_PREFIX = "!meta:";
 /**
  * Decide whether a persistent broker should self-heal onto freshly-installed
  * code (exit so launchd relaunches it). Only when the store is EMPTY: exiting
@@ -119,6 +132,14 @@ export type Response = {
  * unit-testable with a controlled `now`, without a socket or a spawned process.
  * Mutates `store` in place; returns the wire response.
  */
+/**
+ * Count of real unlocked bundles in the store, excluding the internal
+ * `secrets list` metadata cache. Used to decide broker "warmth" for self-heal
+ * and idle-exit: a metadata-only store must read as empty so a disposable list
+ * cache never blocks an upgrade restart (#435) or an idle one-off broker from
+ * exiting. Pure + exported for unit testing.
+ */
+export declare function realBundleCount(store: Map<string, StoredBundle>): number;
 export declare function handleAgentRequest(store: Map<string, StoredBundle>, req: Request, now?: number): Response;
 /**
  * Run the broker in the foreground. Spawned detached by ensureAgentRunning via
@@ -140,6 +161,22 @@ export declare function agentGetSync(name: string): {
     bundle: SecretsBundle;
     env: Record<string, string>;
 } | null;
+/**
+ * Read the cached `secrets list` metadata snapshot for the given keychain
+ * name-set hash, or null on miss / no broker / off-darwin. Reuses the value
+ * fast-path socket read (agentGetSync) — no prompt, no wire change. The hash is
+ * the cache key: a changed name-set (bundle added/removed/renamed) yields a
+ * different key and therefore a clean miss, so the stale set is never served.
+ */
+export declare function agentGetMetaSync(nameSetHash: string): SecretsBundle[] | null;
+/**
+ * Fire-and-forget: populate the broker with a freshly-read metadata snapshot so
+ * the next `secrets list` within the daily window renders without a prompt.
+ * Stored as an ordinary entry (placeholder bundle, snapshot in env) under the
+ * reserved META_CACHE_PREFIX key; the snapshot travels over stdin to the
+ * detached worker (never argv/disk), same as value caching. macOS only.
+ */
+export declare function agentAutoLoadMetaSync(nameSetHash: string, bundles: SecretsBundle[], ttlMs: number): void;
 /** True unless `secrets.agent.auto` is explicitly disabled in agents.yaml. The
  * broker is the mechanism that delivers the `daily` default policy (one Touch ID
  * per ~24h), so auto-caching is ON by default; opt out with
@@ -171,7 +208,11 @@ export declare function agentLoad(name: string, bundle: SecretsBundle, env: Reco
 /** Wipe one bundle (or all if name omitted) from the broker. Returns the count
  * wiped, or 0 when no broker is running. */
 export declare function agentLock(name?: string): Promise<number>;
-/** List currently-unlocked bundles, or [] when no broker is running. */
+/** List currently-unlocked bundles, or [] when no broker is running. The
+ * internal `secrets list` metadata-cache entry is filtered out here as well as
+ * server-side: during a rollout a NEW client can talk to an OLD broker that
+ * predates the server-side exclusion, so this keeps the internal entry from
+ * surfacing in `agents secrets status` in that skew window. */
 export declare function agentStatus(): Promise<AgentStatusEntry[]>;
 /**
  * Ensure a broker is running and reachable. Returns true once the socket answers