@phnx-labs/agents-cli 1.20.33 → 1.20.34

package/dist/lib/drift-sync.js

@@ -0,0 +1,179 @@
+/**
+ * Interactive drift-sync flow — the single "we detected drift, want to fix it?"
+ * action, shared by `agents status`, `agents doctor`, and the menu-bar "NEEDS
+ * SYNC" row.
+ *
+ * It composes existing pieces, re-implementing nothing:
+ *   - computeSyncStatus()          — the unified detection engine (sync-status.ts)
+ *   - pullRepo()                   — fast-forward the `.system` repo (git.ts)
+ *   - promptAgentVersionSelection() — the "which agent types / versions?" picker
+ *   - heal({ mode: 'full' })       — the reconcile engine `doctor --fix` uses
+ *
+ * Combined flow (one confirmation): if `.system` is behind AND resources drifted,
+ * a single "Sync all detected" both pulls `.system` and reconciles the chosen
+ * version homes. The security posture is preserved — the `.system` pull only ever
+ * happens on an explicit user choice here, never silently (see auto-pull-worker.ts
+ * for why system auto-pull is off by default).
+ */
+import chalk from 'chalk';
+import { select, confirm } from '@inquirer/prompts';
+import { AGENTS } from './agents.js';
+import { pullRepo } from './git.js';
+import { heal } from './heal.js';
+import { promptAgentVersionSelection } from './versions.js';
+import { isInteractiveTerminal, isPromptCancelled } from '../commands/utils.js';
+import { computeSyncStatus, } from './sync-status.js';
+const agentName = (id) => AGENTS[id]?.name ?? id;
+/** "claude@2.1.170  2 drifted · 1 missing" for one version. */
+function versionLine(v) {
+    const bits = [];
+    if (v.counts.drifted)
+        bits.push(`${v.counts.drifted} drifted`);
+    if (v.counts.missing)
+        bits.push(`${v.counts.missing} missing`);
+    const label = `${agentName(v.agent)}@${v.version}`;
+    return `  ${label.padEnd(28)} ${chalk.yellow(bits.join(' · '))}`;
+}
+/** Render the drift summary (system freshness + each version owed a sync). */
+function renderSummary(status, needing) {
+    console.log(chalk.bold('\nSync status'));
+    if (status.system.behind > 0) {
+        console.log(`  ${'.system repo'.padEnd(28)} ${chalk.yellow(`${status.system.behind} commit${status.system.behind === 1 ? '' : 's'} behind`)} ${chalk.gray('— pull recommended')}`);
+    }
+    for (const v of needing)
+        console.log(versionLine(v));
+    if (status.totals.orphan > 0) {
+        console.log(chalk.gray(`  (${status.totals.orphan} orphan${status.totals.orphan === 1 ? '' : 's'} — run \`agents prune cleanup\`)`));
+    }
+}
+/** Fast-forward the `.system` repo. Returns whether it actually moved. */
+async function pullSystem(status) {
+    if (status.system.behind <= 0)
+        return false;
+    const res = await pullRepo(status.system.dir);
+    if (res.success) {
+        console.log(chalk.green(`Pulled .system (+${status.system.behind}).`));
+        return true;
+    }
+    console.log(chalk.red(`Could not pull .system: ${res.error ?? 'unknown error'}`));
+    return false;
+}
+/** Reconcile a set of versions grouped by agent via the shared heal engine. */
+async function healVersions(versionsByAgent, cwd) {
+    const out = [];
+    for (const [agent, versions] of versionsByAgent) {
+        if (versions.length === 0)
+            continue;
+        const res = await heal({ mode: 'full', cwd, agent, versions });
+        out.push(...res.versions);
+    }
+    return out;
+}
+/** Report which agents received what after a heal. */
+function reportHealed(healed) {
+    const touched = healed.filter((v) => v.healed.length > 0);
+    if (touched.length === 0) {
+        console.log(chalk.gray('Nothing to reconcile — homes already matched sources.'));
+        return;
+    }
+    const total = touched.reduce((n, v) => n + v.healed.length, 0);
+    const agents = [...new Set(touched.map((v) => agentName(v.agent)))].join(', ');
+    console.log(chalk.green(`Synced ${total} resource${total === 1 ? '' : 's'} to ${agents}.`));
+}
+function groupNeeding(needing) {
+    const m = new Map();
+    for (const v of needing) {
+        const list = m.get(v.agent) ?? [];
+        list.push(v.version);
+        m.set(v.agent, list);
+    }
+    return m;
+}
+/**
+ * The unified "drift detected — sync now?" flow. Returns a structured result so
+ * callers (menu-bar, doctor) can report without re-scanning.
+ */
+export async function promptDriftSync(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const status = opts.status ?? (await computeSyncStatus({ cwd }));
+    const needing = status.agents.filter((a) => a.needsSync);
+    const systemBehind = status.system.behind;
+    const base = {
+        systemBehindBefore: systemBehind,
+        systemPulled: false,
+        healed: [],
+        cancelled: false,
+        nothingToDo: false,
+    };
+    if (systemBehind <= 0 && needing.length === 0) {
+        console.log(chalk.green('Everything is in sync.'));
+        return { ...base, nothingToDo: true };
+    }
+    if (!opts.quiet)
+        renderSummary(status, needing);
+    // Non-interactive OR explicit --yes: reconcile everything detected.
+    if (opts.yes || !isInteractiveTerminal()) {
+        if (!opts.yes) {
+            // Non-TTY without --yes: report, don't act, don't throw.
+            console.log(chalk.gray('\nRun `agents status --yes` to sync, or `agents status` in a terminal to choose.'));
+            return base;
+        }
+        const systemPulled = await pullSystem(status);
+        const healed = await healVersions(groupNeeding(needing), cwd);
+        reportHealed(healed);
+        return { ...base, systemPulled, healed };
+    }
+    // Interactive gate.
+    let choice;
+    try {
+        choice = await select({
+            message: 'Sync now?',
+            choices: [
+                { name: 'Sync all detected', value: 'all' },
+                { name: 'Choose agents & resources', value: 'choose' },
+                { name: 'No', value: 'no' },
+            ],
+            default: 'all',
+        });
+    }
+    catch (err) {
+        if (isPromptCancelled(err))
+            return { ...base, cancelled: true };
+        throw err;
+    }
+    if (choice === 'no')
+        return { ...base, cancelled: true };
+    if (choice === 'all') {
+        const systemPulled = await pullSystem(status);
+        const healed = await healVersions(groupNeeding(needing), cwd);
+        reportHealed(healed);
+        return { ...base, systemPulled, healed };
+    }
+    // choice === 'choose': optional .system pull, then per-agent/version selection.
+    let systemPulled = false;
+    if (systemBehind > 0) {
+        try {
+            const pull = await confirm({ message: `Pull .system (${systemBehind} behind) first?`, default: true });
+            if (pull)
+                systemPulled = await pullSystem(status);
+        }
+        catch (err) {
+            if (!isPromptCancelled(err))
+                throw err;
+            return { ...base, systemPulled, cancelled: true };
+        }
+    }
+    const needingAgents = [...new Set(needing.map((a) => a.agent))];
+    let selection;
+    try {
+        selection = await promptAgentVersionSelection(needingAgents);
+    }
+    catch (err) {
+        if (isPromptCancelled(err))
+            return { ...base, systemPulled, cancelled: true };
+        throw err;
+    }
+    const healed = await healVersions(selection.versionSelections, cwd);
+    reportHealed(healed);
+    return { ...base, systemPulled, healed };
+}

package/dist/lib/exec.d.ts

@@ -189,6 +189,21 @@ export declare function nativeResume(agent: AgentId): boolean;
 export declare function buildExecCommand(options: ExecOptions): string[];
 /** Spawn an agent and return its exit code. Convenience wrapper over spawnAgent. */
 export declare function execAgent(options: ExecOptions): Promise<number>;
+/**
+ * Resolve how to spawn a shim target for a platform. Pure — testable on any host.
+ *
+ * POSIX always execs the binary directly (no shell). On Windows a bare
+ * (non-absolute) name or a `.cmd` companion goes through the shell so cmd.exe
+ * resolves it via PATHEXT — the common, `.cmd`-present path; an absolute `.cmd`
+ * or extensionless path is exec'd through the shell / directly. npm always ships
+ * a `<cmd>.cmd` companion on Windows, so the runnable target `execShimPassthrough`
+ * hands us is the `.cmd` (never a bare `.ps1`).
+ */
+export declare function resolveShimSpawn(platform: NodeJS.Platform, binary: string, extraArgs: string[]): {
+    command: string;
+    args: string[];
+    shell: boolean;
+};
 /**
  * Transparent passthrough exec for generated shims — the node-side delegate that
  * Windows `.cmd` shims call. Resolves the active version (explicit pin, else

package/dist/lib/exec.js

@@ -374,15 +374,6 @@ export const AGENT_COMMANDS = {
             edit: [],
         },
     },
-    roo: {
-        base: ['roo'],
-        promptFlag: 'positional',
-        modeFlags: {
-            plan: ['--mode', 'architect'],
-            edit: ['--mode', 'code'],
-        },
-        modelFlag: '--model',
-    },
     // TODO: --output-format json is documented but currently broken upstream
     // ("flags provided but not defined: -output-format"). Track resolution at
     // https://github.com/google-antigravity/antigravity-cli/issues/7 before
@@ -665,6 +656,25 @@ export async function execAgent(options) {
     const { exitCode } = await spawnAgent(options);
     return exitCode;
 }
+/**
+ * Resolve how to spawn a shim target for a platform. Pure — testable on any host.
+ *
+ * POSIX always execs the binary directly (no shell). On Windows a bare
+ * (non-absolute) name or a `.cmd` companion goes through the shell so cmd.exe
+ * resolves it via PATHEXT — the common, `.cmd`-present path; an absolute `.cmd`
+ * or extensionless path is exec'd through the shell / directly. npm always ships
+ * a `<cmd>.cmd` companion on Windows, so the runnable target `execShimPassthrough`
+ * hands us is the `.cmd` (never a bare `.ps1`).
+ */
+export function resolveShimSpawn(platform, binary, extraArgs) {
+    if (platform === 'win32') {
+        // Use win32 path semantics regardless of the host running this (the platform
+        // is the parameter, not process.platform) so `C:\...` reads as absolute.
+        const useShell = !path.win32.isAbsolute(binary) || binary.endsWith('.cmd');
+        return { command: binary, args: extraArgs, shell: useShell };
+    }
+    return { command: binary, args: extraArgs, shell: false };
+}
 /**
  * Transparent passthrough exec for generated shims — the node-side delegate that
  * Windows `.cmd` shims call. Resolves the active version (explicit pin, else
@@ -691,9 +701,9 @@ export async function execShimPassthrough(agent, rawArgs, cwd, pinnedVersion) {
     // mode/effort are required by ExecOptions but unused by buildExecEnv (which only
     // derives the per-version config-dir env); pass the agent's default to satisfy the type.
     const env = buildExecEnv({ agent, version, cwd, mode: defaultModeFor(agent), effort: 'auto' });
-    const useShell = process.platform === 'win32' && (!path.isAbsolute(binary) || binary.endsWith('.cmd'));
+    const { command, args, shell } = resolveShimSpawn(process.platform, binary, [...launchArgs, ...rawArgs]);
     return new Promise((resolve) => {
-        const child = spawn(binary, [...launchArgs, ...rawArgs], { cwd, stdio: 'inherit', env, shell: useShell });
+        const child = spawn(command, args, { cwd, stdio: 'inherit', env, shell });
         child.on('exit', (code, signal) => resolve(code ?? (signal ? 1 : 0)));
         child.on('error', (err) => {
             process.stderr.write(`agents: failed to launch ${agent}: ${err.message}\n`);

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