@phnx-labs/agents-cli 1.20.33 → 1.20.35

package/dist/lib/plugins.js

@@ -18,7 +18,7 @@ import { listInstalledVersions, getVersionHomePath } from './versions.js';
 import { AGENTS, agentConfigDirName } from './agents.js';
 import { capableAgents, isCapable } from './capabilities.js';
 import { shouldInstallCommandAsSkill, installCommandSkillToVersion } from './command-skills.js';
-import { copyPluginToMarketplace, syncMarketplaceManifest, registerMarketplace, unregisterMarketplace, addPluginToSettings, removePluginFromSettings, removePluginFromMarketplace, marketplaceIsEmpty, removeEmptyMarketplaceDir, isInstalledInMarketplace, marketplaceRoot, discoverMarketplaces, marketplaceNameFor, MARKETPLACE_NAME, PROJECT_MARKETPLACE_NAME, SYSTEM_MARKETPLACE_NAME, } from './plugin-marketplace.js';
+import { copyPluginToMarketplace, syncMarketplaceManifest, registerMarketplace, unregisterMarketplace, addPluginToSettings, removePluginFromSettings, removePluginFromMarketplace, registerDroidInstalledPlugin, unregisterDroidInstalledPlugin, isDroidPluginInstalled, registerCopilotInstalledPlugin, unregisterCopilotInstalledPlugin, marketplaceIsEmpty, removeEmptyMarketplaceDir, isInstalledInMarketplace, marketplaceRoot, discoverMarketplaces, marketplaceNameFor, MARKETPLACE_NAME, PROJECT_MARKETPLACE_NAME, SYSTEM_MARKETPLACE_NAME, } from './plugin-marketplace.js';
 const PLUGIN_MANIFEST_DIR = '.claude-plugin';
 const PLUGIN_MANIFEST_FILE = 'plugin.json';
 const USER_CONFIG_FILE = '.user-config.json';
@@ -416,7 +416,7 @@ export function marketplaceSpecForName(name, cwd = process.cwd()) {
  * carries, not just the user one.
  */
 function listVersionMarketplaceNames(agent, versionHome) {
-    const dir = path.join(versionHome, `.${agent}`, 'plugins', 'marketplaces');
+    const dir = path.join(versionHome, agentConfigDirName(agent), 'plugins', 'marketplaces');
     if (!fs.existsSync(dir))
         return [];
     try {
@@ -444,6 +444,11 @@ function listVersionMarketplaceNames(agent, versionHome) {
  * MCP servers, bin/, settings.json, and permissions once the plugin lives at the
  * native install path and is marked enabled — see
  * https://code.claude.com/docs/en/plugins.
+ *
+ * Droid (Factory CLI) reuses this same marketplace layout but additionally
+ * requires an installed_plugins.json registry entry and a "local"-source
+ * known_marketplaces.json entry before `droid plugin list` will see the plugin
+ * (steps handled by registerMarketplace's droid branch + step 5c below).
  */
 export function syncPluginToVersion(plugin, agent, versionHome, options = {}) {
     const result = {
@@ -491,9 +496,25 @@ export function syncPluginToVersion(plugin, agent, versionHome, options = {}) {
     // .mcp.json, settings.json, permissions/) are only auto-enabled when the
     // caller explicitly opts in. addPluginToSettings does no gating — that moved
     // here, where plugin capabilities are inspected.
-    if (options.allowExecSurfaces === true || !hasPluginExecSurfaces(inspectPluginCapabilities(plugin.root))) {
+    const enablePlugin = options.allowExecSurfaces === true || !hasPluginExecSurfaces(inspectPluginCapabilities(plugin.root));
+    if (enablePlugin) {
         addPluginToSettings(plugin.name, marketplaceName, agent, versionHome);
     }
+    // 5c. Droid diverges from Claude's marketplace+enabledPlugins model: it only
+    //     "sees" a plugin that also has an entry in installed_plugins.json (with
+    //     the marketplace registered as source "local"). Register the install so
+    //     `droid plugin list` shows it — Active when enabled, Inactive otherwise.
+    if (agent === 'droid') {
+        registerDroidInstalledPlugin(plugin.name, marketplaceName, installDir, plugin.manifest.version, agent, versionHome);
+    }
+    // 5d. Copilot, like Droid, only "sees" a plugin that also has an entry in its
+    //     auto-managed config.json#installedPlugins (registerMarketplace already
+    //     wrote settings.json#extraKnownMarketplaces, and addPluginToSettings the
+    //     enabledPlugins flag). cache_path points at the marketplace copy; the
+    //     `enabled` flag mirrors the exec-surface trust gate above.
+    if (agent === 'copilot') {
+        registerCopilotInstalledPlugin(plugin.name, marketplaceName, installDir, plugin.manifest.version, enablePlugin, agent, versionHome);
+    }
     // 5b. Convert plugin commands/ to skills for agents that dropped command support
     //     (Codex >= 0.117.0). Skill name is prefixed with plugin name to avoid
     //     collision with standalone command skills.
@@ -718,7 +739,15 @@ function migrateLegacyFlatLayout(plugin, agent, versionHome) {
 export function isPluginSynced(plugin, agent, versionHome) {
     if (!isCapable(agent, 'plugins'))
         return false;
-    return isInstalledInMarketplace(plugin.name, marketplaceSpecForName(plugin.marketplace), agent, versionHome);
+    const spec = marketplaceSpecForName(plugin.marketplace);
+    if (!isInstalledInMarketplace(plugin.name, spec, agent, versionHome))
+        return false;
+    // Droid additionally requires its installed_plugins.json registry entry —
+    // without it the marketplace copy is invisible to `droid plugin list`.
+    if (agent === 'droid') {
+        return isDroidPluginInstalled(plugin.name, marketplaceNameFor(spec), agent, versionHome);
+    }
+    return true;
 }
 // ─── Removal ─────────────────────────────────────────────────────────────────
 /**
@@ -746,6 +775,12 @@ export function removePluginFromVersion(pluginName, pluginRoot, agent, versionHo
             removedAny = true;
         }
         removePluginFromSettings(pluginName, name, agent, versionHome);
+        if (agent === 'droid') {
+            unregisterDroidInstalledPlugin(pluginName, name, agent, versionHome);
+        }
+        if (agent === 'copilot') {
+            unregisterCopilotInstalledPlugin(pluginName, name, agent, versionHome);
+        }
         // Refresh marketplace.json so it reflects what's left under plugins/.
         syncMarketplaceManifest(spec, agent, versionHome);
         // If we just removed the last plugin, drop the marketplace dir and the
@@ -930,6 +965,12 @@ export function cleanOrphanedPluginSkills(agent, versionHome, activePluginNames,
                 fs.mkdirSync(trashDir, { recursive: true, mode: 0o700 });
                 fs.renameSync(path.join(mktPluginsDir, entry.name), trashDest);
                 removePluginFromSettings(entry.name, name, agent, versionHome);
+                if (agent === 'droid') {
+                    unregisterDroidInstalledPlugin(entry.name, name, agent, versionHome);
+                }
+                if (agent === 'copilot') {
+                    unregisterCopilotInstalledPlugin(entry.name, name, agent, versionHome);
+                }
                 removed.push(entry.name);
                 trashedHere = true;
             }

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

package/dist/lib/secrets/agent.js

@@ -36,6 +36,19 @@ import { getCliVersion, getCliVersionFresh } from '../version.js';
 const PROTOCOL_VERSION = 1;
 /** Default lifetime of an unlocked bundle when `--ttl` is not given. */
 export const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000; // 24h
+/**
+ * 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 const META_CACHE_PREFIX = '!meta:';
 /** After the store goes empty (all bundles locked or expired) for this long,
  * the broker exits so no idle process lingers holding a socket. */
 const IDLE_EXIT_MS = 5 * 60 * 1000; // 5m
@@ -233,6 +246,20 @@ export async function uninstallSecretsAgentService() {
  * 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 function realBundleCount(store) {
+    let n = 0;
+    for (const name of store.keys())
+        if (!name.startsWith(META_CACHE_PREFIX))
+            n++;
+    return n;
+}
 export function handleAgentRequest(store, req, now = Date.now()) {
     switch (req.cmd) {
         case 'ping':
@@ -266,6 +293,8 @@ export function handleAgentRequest(store, req, now = Date.now()) {
             for (const [name, e] of store) {
                 if (now >= e.expiresAt)
                     continue;
+                if (name.startsWith(META_CACHE_PREFIX))
+                    continue; // internal list cache, not a user bundle
                 entries.push({ name, expiresAt: e.expiresAt, keyCount: Object.keys(e.env).length });
             }
             return { ok: true, cmd: 'status', entries };
@@ -321,22 +350,28 @@ export async function runSecretsAgent(opts = {}) {
     // an in-place upgrade has landed and self-heal onto it. getCliVersion caches
     // this value for the process lifetime; getCliVersionFresh re-reads on disk.
     const runningVersion = getCliVersion();
+    // "Warmth" for self-heal / idle-exit counts only real unlocked bundles, NOT
+    // the internal `secrets list` metadata cache (#524). Otherwise a 24h-TTL list
+    // cache would keep the store non-empty and (a) block the persistent broker
+    // from self-healing onto a freshly-installed version for up to a day (#435's
+    // gate is size===0), and (b) stop a one-off broker from ever idle-exiting. The
+    // metadata cache is a disposable list snapshot — wiping it on upgrade/idle
+    // costs at most one extra prompt on the next `secrets list`.
     const sweep = () => {
         const now = Date.now();
         for (const [name, e] of store)
             if (now >= e.expiresAt)
                 store.delete(name);
-        // Self-heal onto a newer in-place install — but ONLY while the store is
-        // empty, so we never wipe live unlocks and force a re-prompt (#435). The
-        // `store.size === 0` short-circuit also keeps getCliVersionFresh (a disk
-        // read) off the hot path. A pending upgrade is adopted at the next idle
-        // sweep instead of immediately.
-        if (store.size === 0 &&
-            shouldSelfHealForUpgrade(persistent, store.size, runningVersion, getCliVersionFresh())) {
+        const live = realBundleCount(store);
+        // Self-heal onto a newer in-place install — but ONLY while no real unlocks
+        // are held, so we never wipe live unlocks and force a re-prompt (#435). A
+        // metadata-only store still self-heals (the list cache is disposable).
+        if (live === 0 &&
+            shouldSelfHealForUpgrade(persistent, live, runningVersion, getCliVersionFresh())) {
             shutdown(0); // KeepAlive relaunches on the new code
             return;
         }
-        if (store.size === 0) {
+        if (live === 0) {
             if (!persistent && now - emptySince >= IDLE_EXIT_MS)
                 shutdown(0);
         }
@@ -346,7 +381,7 @@ export async function runSecretsAgent(opts = {}) {
     };
     const handle = (req) => {
         const resp = handleAgentRequest(store, req);
-        if (store.size > 0)
+        if (realBundleCount(store) > 0)
             emptySince = Date.now();
         return resp;
     };
@@ -529,6 +564,44 @@ export function agentGetSync(name) {
         return null;
     }
 }
+// Key inside the cached entry's env that holds the JSON metadata snapshot.
+const META_SNAPSHOT_KEY = '__snapshot__';
+/**
+ * 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 function agentGetMetaSync(nameSetHash) {
+    if (!onDarwin())
+        return null;
+    const hit = agentGetSync(META_CACHE_PREFIX + nameSetHash);
+    const raw = hit?.env?.[META_SNAPSHOT_KEY];
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return 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 function agentAutoLoadMetaSync(nameSetHash, bundles, ttlMs) {
+    if (!onDarwin())
+        return;
+    const key = META_CACHE_PREFIX + nameSetHash;
+    const placeholder = { name: key, vars: {} };
+    agentAutoLoadSync(key, placeholder, { [META_SNAPSHOT_KEY]: JSON.stringify(bundles) }, ttlMs);
+}
 /** 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
@@ -606,10 +679,15 @@ export async function agentLock(name) {
     const r = await request({ cmd: 'lock', name });
     return r?.ok === true && r.cmd === 'lock' ? r.wiped : 0;
 }
-/** 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 async function agentStatus() {
     const r = await request({ cmd: 'status' });
-    return r?.ok === true && r.cmd === 'status' ? r.entries : [];
+    const entries = r?.ok === true && r.cmd === 'status' ? r.entries : [];
+    return entries.filter((e) => !e.name.startsWith(META_CACHE_PREFIX));
 }
 /** Ping result: whether a broker is reachable + speaking our protocol, and the
  * version of the code it's running (for staleness detection). */

package/dist/lib/secrets/bundles.js

@@ -21,11 +21,12 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import * as yaml from 'yaml';
-import { deleteKeychainToken, getKeychainToken, getKeychainTokens, hasKeychainToken, keychainUsesFileFallback, listKeychainItems, parseBundleValue, resolveRef, secretsKeychainItem, setKeychainToken, } from './index.js';
+import { deleteKeychainToken, getKeychainToken, getKeychainTokens, hasKeychainToken, isKeychainBackendOverridden, keychainUsesFileFallback, listKeychainItems, parseBundleValue, resolveRef, secretsKeychainItem, setKeychainToken, } from './index.js';
 import { fileStore } from './filestore.js';
 import { emit } from '../events.js';
 import { readMeta } from '../state.js';
-import { agentGetSync, agentAutoLoadSync, secretsAgentAutoEnabled, DEFAULT_TTL_MS } from './agent.js';
+import { agentGetSync, agentAutoLoadSync, agentGetMetaSync, agentAutoLoadMetaSync, secretsAgentAutoEnabled, DEFAULT_TTL_MS } from './agent.js';
+import { createHash } from 'node:crypto';
 const keychainStore = {
     has: hasKeychainToken,
     get: getKeychainToken,
@@ -398,15 +399,45 @@ export function listBundles() {
             .map((s) => s.slice(BUNDLE_META_PREFIX.length))
             .filter((n) => BUNDLE_NAME_PATTERN.test(n));
         if (keychainNames.length > 0) {
-            const fetched = getKeychainTokens(keychainNames.map(bundleMetaItem));
-            for (const name of keychainNames) {
-                const json = fetched.get(bundleMetaItem(name));
-                if (json === undefined)
-                    continue;
-                const bundle = parseBundleMeta(name, json, 'keychain');
-                if (bundle)
+            // Daily-policy fast-path (macOS). Bundle metadata items are biometry-gated,
+            // so the getKeychainTokens batch below pops Touch ID on every `secrets
+            // list` — the broker/`daily` mechanism only ever covered value reads, not
+            // this listing. Serve a broker-cached metadata snapshot when one is held,
+            // so only the first list per ~24h prompts. The cache key is a hash of the
+            // current keychain name-set (enumerated silently above): add / remove /
+            // rename a bundle and the key changes, so the stale snapshot is never
+            // served — no active invalidation needed. Values are never cached here;
+            // this is metadata only.
+            const useAgent = process.env.AGENTS_SECRETS_NO_AGENT !== '1' &&
+                !isKeychainBackendOverridden() &&
+                secretsAgentAutoEnabled();
+            const nameSetHash = createHash('sha256')
+                .update([...keychainNames].sort().join('\n'))
+                .digest('hex')
+                .slice(0, 32);
+            const cached = useAgent ? agentGetMetaSync(nameSetHash) : null;
+            if (cached) {
+                for (const bundle of cached)
                     out.push(bundle);
             }
+            else {
+                const fetched = getKeychainTokens(keychainNames.map(bundleMetaItem));
+                const keychainBundles = [];
+                for (const name of keychainNames) {
+                    const json = fetched.get(bundleMetaItem(name));
+                    if (json === undefined)
+                        continue;
+                    const bundle = parseBundleMeta(name, json, 'keychain');
+                    if (bundle)
+                        keychainBundles.push(bundle);
+                }
+                for (const bundle of keychainBundles)
+                    out.push(bundle);
+                // Populate the broker for the rest of the daily window (fire-and-forget).
+                if (useAgent && keychainBundles.length > 0) {
+                    agentAutoLoadMetaSync(nameSetHash, keychainBundles, DEFAULT_TTL_MS);
+                }
+            }
         }
     }
     // File-backed bundles live in the encrypted-file store. Enumeration is a

package/dist/lib/secrets/filestore.js

@@ -20,11 +20,12 @@
  * item and its keychain twin carry identical names:
  *   `agents-cli.bundles.<name>` and `agents-cli.secrets.<bundle>.<key>`.
  */
-import { execSync } from 'child_process';
+import { execSync, spawnSync } from 'child_process';
 import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from 'crypto';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
+import { encodePwshBase64 } from '../pwsh.js';
 // ---------- file store location ----------
 let fileDirOverride = null;
 let cachedPassphrase = null;
@@ -36,7 +37,36 @@ function ensureFileDir() {
     fs.mkdirSync(fileDir(), { recursive: true, mode: 0o700 });
 }
 // ---------- passphrase ----------
+/**
+ * Windows has no `/dev/tty` and no POSIX `stty`, so the interactive prompt runs
+ * through PowerShell's `Read-Host -AsSecureString` (which never echoes). The
+ * secure string is marshaled back out and written to stdout, which we capture.
+ * If PowerShell cannot run at all, fail with an actionable error rather than
+ * letting `fs.openSync('/dev/tty')` throw a raw ENOENT. Reached only on the rare
+ * interactive-Windows file-fallback path — the headless service-account case
+ * (no TTY) auto-provisions a machine-local key and never gets here.
+ */
+function readPassphraseFromTtyWindows() {
+    const script = `
+$ErrorActionPreference = 'Stop'
+$sec = Read-Host -AsSecureString -Prompt 'Enter AGENTS_SECRETS_PASSPHRASE'
+$ptr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($sec)
+try { [Console]::Out.Write([Runtime.InteropServices.Marshal]::PtrToStringBSTR($ptr)) }
+finally { [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($ptr) }
+`;
+    // Not -NonInteractive: that flag would suppress the Read-Host prompt itself.
+    const res = spawnSync('powershell.exe', ['-NoProfile', '-EncodedCommand', encodePwshBase64(script)], {
+        stdio: ['inherit', 'pipe', 'inherit'],
+    });
+    if (res.error || res.status !== 0) {
+        throw new Error('Could not prompt for a passphrase on Windows. Set AGENTS_SECRETS_PASSPHRASE ' +
+            'to decrypt the file-backed secret store.');
+    }
+    return (res.stdout?.toString() ?? '').replace(/\r?\n$/, '');
+}
 function readPassphraseFromTty() {
+    if (process.platform === 'win32')
+        return readPassphraseFromTtyWindows();
     const fd = fs.openSync('/dev/tty', 'r+');
     let echoDisabled = false;
     try {

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

@@ -12,7 +12,10 @@
  * Linux: libsecret (GNOME Keyring) via the `secret-tool` CLI. No biometry —
  * items are unlocked when the keyring is open.
  *
- * Windows: not supported.
+ * Windows: Windows Credential Manager (CRED_TYPE_GENERIC,
+ * CRED_PERSIST_LOCAL_MACHINE) via a PowerShell P/Invoke shim, with the same
+ * AES-256-GCM encrypted-file fallback used on Linux when the credential store
+ * is unreachable (no logon session / no powershell.exe). No biometry.
  *
  * Items are device-local: the biometry access control requires the OS to
  * treat them as bound to this device, so cross-machine propagation goes
@@ -42,6 +45,19 @@ export declare function parseBundleValue(raw: BundleValue): {
 };
 /** Serialize a secret ref back to its `provider:value` string form. */
 export declare function serializeRef(ref: SecretRef): string;
+/**
+ * Guard a secret value before it is written to the current platform's primary
+ * backend.
+ *
+ * A value is empty on every platform → always rejected. Embedded newlines are
+ * rejected ONLY on darwin: the macOS batch read path (`get-batch`, see
+ * getKeychainTokens) is newline-delimited, so a value with a newline would
+ * corrupt record framing on read. Linux (secret-tool), Windows (Credential
+ * Manager stores the raw UTF-8 blob and emits base64), and the encrypted-file
+ * fallback all store raw bytes and round-trip multiline values (PEM / SSH keys)
+ * faithfully, so they accept newlines. `platform` is injectable for tests.
+ */
+export declare function assertValueStorable(value: string, platform?: NodeJS.Platform): void;
 /** Build the keychain item name for a profile provider token. */
 export declare function profileKeychainItem(provider: string): string;
 /** Build the keychain item name for a secrets-bundle key. */
@@ -61,6 +77,11 @@ export interface KeychainBackend {
 }
 /** Install a custom keychain backend (test only). Returns the previous backend so callers can restore. */
 export declare function setKeychainBackendForTest(b: KeychainBackend | null): KeychainBackend | null;
+/** True when a test backend is installed (real keychain / biometry bypassed).
+ * Callers that gate on the live secrets-agent broker use this to stay hermetic —
+ * with an in-memory backend there is no real keychain to dedup, so the broker
+ * fast-path must not engage. Always false in production (`backend` is null). */
+export declare function isKeychainBackendOverridden(): boolean;
 /** Check if a keychain/keyring item exists. Never prompts for biometry. */
 export declare function hasKeychainToken(item: string): boolean;
 /**
@@ -99,6 +120,17 @@ export declare function deleteKeychainToken(item: string): boolean;
 export declare function keychainUsesFileFallback(): boolean;
 /** Enumerate keychain/keyring item names starting with the given prefix. */
 export declare function listKeychainItems(prefix: string): string[];
+/**
+ * Enumerate ONLY legacy file-based-keychain item names with the given prefix —
+ * the items that still carry a pre-migration (trusted-app) ACL and pop a
+ * separate auth sheet on read. Items already in the data-protection keychain are
+ * excluded (they need no migration). Silent (attributes only, never decrypts).
+ *
+ * macOS only: on Linux / the test backend there is no separate legacy keychain,
+ * so this returns []. Used by `agents secrets migrate-acl` to rewrite only the
+ * stragglers instead of every item (which would be a Touch ID storm).
+ */
+export declare function listLegacyKeychainItems(prefix: string): string[];
 /**
  * One-time upgrade for a keychain item that was written by a previous helper
  * generation with a trusted-app ACL. The helper reads the legacy item