@phnx-labs/agents-cli 1.20.32 → 1.20.34

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, 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,
@@ -379,25 +380,64 @@ export function listBundles() {
     // prompt instead of N. Bundle metadata items carry user-presence ACLs (same
     // as secret values), so a naive loop over readBundle() spawns a fresh
     // LAContext per item — meaning N biometric prompts for `secrets list`.
-    let keychainServices = [];
-    try {
-        keychainServices = listKeychainItems(BUNDLE_META_PREFIX);
-    }
-    catch {
-        keychainServices = [];
-    }
-    const keychainNames = keychainServices
-        .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)
-                out.push(bundle);
+    //
+    // SKIP this entirely when the keychain backend is routing to the encrypted
+    // file store (Linux headless / locked-collection fallback): there,
+    // listKeychainItems() returns the SAME items the file enumeration below
+    // reads, so running both would list every file-backed bundle twice — once
+    // mislabeled `keychain`, once correctly `[file]`. Under the fallback the
+    // file store is the single source of truth, so the block below covers all.
+    if (!keychainUsesFileFallback()) {
+        let keychainServices = [];
+        try {
+            keychainServices = listKeychainItems(BUNDLE_META_PREFIX);
+        }
+        catch {
+            keychainServices = [];
+        }
+        const keychainNames = keychainServices
+            .map((s) => s.slice(BUNDLE_META_PREFIX.length))
+            .filter((n) => BUNDLE_NAME_PATTERN.test(n));
+        if (keychainNames.length > 0) {
+            // 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;
 /**
@@ -86,8 +107,30 @@ export declare function getKeychainTokens(items: string[]): Map<string, string>;
 export declare function setKeychainToken(item: string, value: string): void;
 /** Delete a keychain/keyring item. Returns true if it existed. Never prompts for biometry. */
 export declare function deleteKeychainToken(item: string): boolean;
+/**
+ * True when the active keychain backend transparently routes reads/writes to
+ * the encrypted-file store instead of the OS credential store. This only
+ * happens on Linux under the headless / locked-collection fallback
+ * (src/lib/secrets/linux.ts); macOS and the test backend always return false.
+ *
+ * Callers that ALSO enumerate the file store directly (e.g. `listBundles`)
+ * use this to avoid double-counting: under the fallback `listKeychainItems`
+ * and the direct file enumeration return the same items.
+ */
+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

package/dist/lib/secrets/index.js

@@ -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
@@ -23,7 +26,8 @@ import { execFileSync, spawnSync } from 'child_process';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { linuxBackend } from './linux.js';
+import { linuxBackend, usesFileFallback as linuxUsesFileFallback } from './linux.js';
+import { windowsBackend, usesFileFallback as windowsUsesFileFallback } from './windows.js';
 import { getKeychainHelperPath } from './install-helper.js';
 const SERVICE_PREFIX = 'agents-cli';
 const SECRETS_ITEM_PREFIX = `${SERVICE_PREFIX}.secrets.`;
@@ -47,15 +51,36 @@ export function serializeRef(ref) {
     return `${ref.provider}:${ref.value}`;
 }
 function assertSupportedPlatform() {
-    if (process.platform !== 'darwin' && process.platform !== 'linux') {
-        throw new Error('agents secrets requires macOS Keychain or Linux libsecret.\n' +
-            'Windows is not supported — use environment variables or a .env file instead.\n' +
-            'WSL2 is supported (libsecret via gnome-keyring).');
+    if (process.platform !== 'darwin' && process.platform !== 'linux' && process.platform !== 'win32') {
+        throw new Error('agents secrets requires macOS Keychain, Linux libsecret, or Windows Credential Manager.\n' +
+            'Use environment variables or a .env file on unsupported platforms.');
     }
 }
 function isLinux() {
     return process.platform === 'linux';
 }
+function isWindows() {
+    return process.platform === 'win32';
+}
+/**
+ * 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 function assertValueStorable(value, platform = process.platform) {
+    if (!value || !value.trim())
+        throw new Error('Secret value is empty.');
+    if (platform === 'darwin' && /[\r\n]/.test(value)) {
+        throw new Error('Secret value contains newlines, which are not supported.');
+    }
+}
 /** Build the keychain item name for a profile provider token. */
 export function profileKeychainItem(provider) {
     return `${SERVICE_PREFIX}.${provider}.token`;
@@ -74,6 +99,13 @@ export function setKeychainBackendForTest(b) {
     backend = b;
     return prev;
 }
+/** 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 function isKeychainBackendOverridden() {
+    return backend !== null;
+}
 /**
  * Items whose name does NOT start with `agents-cli.` belong to another
  * application (e.g. Anthropic's `Claude Code-credentials-*`). Their ACL
@@ -93,6 +125,8 @@ export function hasKeychainToken(item) {
     assertSupportedPlatform();
     if (isLinux())
         return linuxBackend.has(item);
+    if (isWindows())
+        return windowsBackend.has(item);
     if (!isOurItem(item)) {
         return spawnSync('/usr/bin/security', ['find-generic-password', '-a', os.userInfo().username, '-s', item], {
             stdio: ['ignore', 'ignore', 'ignore'],
@@ -116,6 +150,8 @@ export function getKeychainToken(item) {
     assertSupportedPlatform();
     if (isLinux())
         return linuxBackend.get(item);
+    if (isWindows())
+        return windowsBackend.get(item);
     if (!isOurItem(item)) {
         const sec = spawnSync('/usr/bin/security', ['find-generic-password', '-a', os.userInfo().username, '-s', item, '-w'], {
             stdio: ['ignore', 'pipe', 'pipe'],
@@ -177,6 +213,15 @@ export function getKeychainTokens(items) {
         }
         return result;
     }
+    if (isWindows()) {
+        for (const item of items) {
+            try {
+                result.set(item, windowsBackend.get(item));
+            }
+            catch { /* missing — skip */ }
+        }
+        return result;
+    }
     const bin = getKeychainHelperPath();
     const child = spawnSync(bin, ['get-batch', os.userInfo().username, ...items], {
         stdio: ['ignore', 'pipe', 'pipe'],
@@ -226,16 +271,17 @@ export function setKeychainToken(item, value) {
         return;
     }
     assertSupportedPlatform();
-    if (!value || !value.trim())
-        throw new Error('Secret value is empty.');
-    if (/[\r\n]/.test(value))
-        throw new Error('Secret value contains newlines, which are not supported.');
+    assertValueStorable(value);
     if (/[\x00=\r\n]/.test(item))
         throw new Error('Secret item name contains invalid characters.');
     if (isLinux()) {
         linuxBackend.set(item, value);
         return;
     }
+    if (isWindows()) {
+        windowsBackend.set(item, value);
+        return;
+    }
     // Bare (non-`agents-cli.`) items are written WITHOUT the biometry ACL so
     // they round-trip with the no-prompt read path in getKeychainToken (which
     // also uses /usr/bin/security for non-our items). This is what lets a
@@ -273,11 +319,32 @@ export function deleteKeychainToken(item) {
     assertSupportedPlatform();
     if (isLinux())
         return linuxBackend.delete(item);
+    if (isWindows())
+        return windowsBackend.delete(item);
     const bin = getKeychainHelperPath();
     return spawnSync(bin, ['delete', item, os.userInfo().username], {
         stdio: ['ignore', 'pipe', 'pipe'],
     }).status === 0;
 }
+/**
+ * True when the active keychain backend transparently routes reads/writes to
+ * the encrypted-file store instead of the OS credential store. This only
+ * happens on Linux under the headless / locked-collection fallback
+ * (src/lib/secrets/linux.ts); macOS and the test backend always return false.
+ *
+ * Callers that ALSO enumerate the file store directly (e.g. `listBundles`)
+ * use this to avoid double-counting: under the fallback `listKeychainItems`
+ * and the direct file enumeration return the same items.
+ */
+export function keychainUsesFileFallback() {
+    if (backend)
+        return false;
+    if (isLinux())
+        return linuxUsesFileFallback();
+    if (isWindows())
+        return windowsUsesFileFallback();
+    return false;
+}
 /** Enumerate keychain/keyring item names starting with the given prefix. */
 export function listKeychainItems(prefix) {
     if (backend)
@@ -285,6 +352,8 @@ export function listKeychainItems(prefix) {
     assertSupportedPlatform();
     if (isLinux())
         return linuxBackend.list(prefix);
+    if (isWindows())
+        return windowsBackend.list(prefix);
     const bin = getKeychainHelperPath();
     const result = spawnSync(bin, ['list', prefix], {
         stdio: ['ignore', 'pipe', 'pipe'],
@@ -296,6 +365,33 @@ export function listKeychainItems(prefix) {
     const out = result.stdout?.toString() || '';
     return out.split('\n').map((s) => s.trim()).filter(Boolean);
 }
+/**
+ * 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 function listLegacyKeychainItems(prefix) {
+    if (backend)
+        return [];
+    assertSupportedPlatform();
+    if (isLinux())
+        return [];
+    const bin = getKeychainHelperPath();
+    const result = spawnSync(bin, ['list-legacy', prefix], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (result.status !== 0) {
+        const msg = result.stderr?.toString().trim();
+        throw new Error(msg || `Failed to enumerate legacy keychain items with prefix '${prefix}'.`);
+    }
+    const out = result.stdout?.toString() || '';
+    return out.split('\n').map((s) => s.trim()).filter(Boolean);
+}
 /**
  * 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
@@ -310,6 +406,8 @@ export function migrateKeychainItem(item) {
     assertSupportedPlatform();
     if (isLinux())
         return linuxBackend.has(item);
+    if (isWindows())
+        return windowsBackend.has(item);
     const bin = getKeychainHelperPath();
     const result = spawnSync(bin, ['migrate-acl', item, os.userInfo().username], {
         stdio: ['ignore', 'pipe', 'pipe'],

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

@@ -18,6 +18,20 @@
  */
 import type { KeychainBackend } from './index.js';
 export { encryptForFallback, decryptForFallback, fileBackend, type EncFile, } from './filestore.js';
+/**
+ * True when secret operations currently route to the encrypted-file store
+ * instead of the Secret Service (the headless / locked-collection fallback).
+ *
+ * Runs the same `preflight()` decision every read and write uses, so it can't
+ * drift from where bytes actually land. `preflight()` throws only in the
+ * interactive / no-secret-tool / no-passphrase case — where nothing is stored
+ * — so treat that as "not on the file path".
+ *
+ * `listBundles()` needs this: under the fallback the keychain enumeration
+ * (`linuxBackend.list`) and the file enumeration read the SAME store, so
+ * without this signal every file-backed bundle would be listed twice.
+ */
+export declare function usesFileFallback(): boolean;
 /** secret-tool lookup attributes:
  *   service=agents-cli account=<user> item=<itemName> */
 export declare function hasSecretToolToken(item: string): boolean;

package/dist/lib/secrets/linux.js

@@ -86,6 +86,27 @@ function preflight() {
     }
     return 'secret-tool';
 }
+/**
+ * True when secret operations currently route to the encrypted-file store
+ * instead of the Secret Service (the headless / locked-collection fallback).
+ *
+ * Runs the same `preflight()` decision every read and write uses, so it can't
+ * drift from where bytes actually land. `preflight()` throws only in the
+ * interactive / no-secret-tool / no-passphrase case — where nothing is stored
+ * — so treat that as "not on the file path".
+ *
+ * `listBundles()` needs this: under the fallback the keychain enumeration
+ * (`linuxBackend.list`) and the file enumeration read the SAME store, so
+ * without this signal every file-backed bundle would be listed twice.
+ */
+export function usesFileFallback() {
+    try {
+        return preflight() === 'file';
+    }
+    catch {
+        return false;
+    }
+}
 // ---------- secret-tool ops with fallback ----------
 /** secret-tool lookup attributes:
  *   service=agents-cli account=<user> item=<itemName> */