@phnx-labs/agents-cli 1.19.1 → 1.20.0

package/dist/lib/secrets/bundles.js

@@ -15,7 +15,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import * as yaml from 'yaml';
-import { deleteKeychainToken, getKeychainToken, hasKeychainToken, listKeychainItems, parseBundleValue, resolveRef, secretsKeychainItem, setKeychainToken, } from './index.js';
+import { deleteKeychainToken, getKeychainToken, getKeychainTokensBatch, hasKeychainToken, listKeychainItems, parseBundleValue, resolveRef, secretsKeychainItem, setKeychainToken, } from './index.js';
 import { emit } from '../events.js';
 /** Allowed values for a secret's `type` metadata field. */
 export const SECRET_TYPES = [
@@ -34,6 +34,7 @@ const LAST_USED_THROTTLE_MS = 60_000;
 const BUNDLE_NAME_PATTERN = /^[a-z0-9][a-z0-9\-_.]{0,48}$/i;
 const ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const BUNDLE_META_PREFIX = 'agents-cli.bundles.';
+const SECRETS_ITEM_PREFIX = 'agents-cli.secrets.';
 export const RESERVED_ENV_NAMES = new Set([
     'PATH', 'HOME', 'USER', 'USERNAME', 'SHELL', 'PWD', 'OLDPWD',
     'TERM', 'LANG', 'LC_ALL', 'DISPLAY', 'EDITOR', 'VISUAL',
@@ -145,7 +146,7 @@ export function readBundle(name) {
     }
     return bundle;
 }
-export function writeBundle(bundle) {
+export function writeBundle(bundle, opts = {}) {
     validateBundleName(bundle.name);
     for (const key of Object.keys(bundle.vars)) {
         validateEnvKey(key);
@@ -187,7 +188,9 @@ export function writeBundle(bundle) {
     };
     const json = JSON.stringify(payload);
     setKeychainToken(bundleMetaItem(bundle.name), json, Boolean(bundle.icloud_sync));
-    emit('secrets.set', { bundle: bundle.name });
+    if (opts.emitEvent !== false) {
+        emit('secrets.set', { bundle: bundle.name });
+    }
 }
 export function deleteBundle(name) {
     validateBundleName(name);
@@ -208,14 +211,58 @@ export function listBundles() {
     const names = services
         .map((s) => s.slice(BUNDLE_META_PREFIX.length))
         .filter((n) => BUNDLE_NAME_PATTERN.test(n));
+    if (names.length === 0)
+        return [];
+    // Batch all metadata reads behind ONE Touch ID 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`. Sharing a single context across all
+    // SecItemCopyMatching calls collapses the prompt to one. Mirrors the pattern
+    // already used by resolveBundleEnv for runtime secret injection.
+    const itemsToFetch = names.map(bundleMetaItem);
+    const fetched = getKeychainTokensBatch(itemsToFetch, false, 'list secrets bundles');
     const out = [];
     for (const name of names) {
+        const json = fetched.get(bundleMetaItem(name));
+        if (json === undefined)
+            continue;
+        let parsed;
         try {
-            out.push(readBundle(name));
+            parsed = JSON.parse(json);
         }
         catch {
             // Skip malformed bundles; surfaced via `agents secrets view <name>`.
+            continue;
+        }
+        if (!parsed || typeof parsed !== 'object')
+            continue;
+        const bundle = {
+            name,
+            description: parsed.description,
+            allow_exec: Boolean(parsed.allow_exec),
+            icloud_sync: Boolean(parsed.icloud_sync),
+            vars: parsed.vars && typeof parsed.vars === 'object' ? parsed.vars : {},
+        };
+        if (typeof parsed.created_at === 'string')
+            bundle.created_at = parsed.created_at;
+        if (typeof parsed.updated_at === 'string')
+            bundle.updated_at = parsed.updated_at;
+        if (typeof parsed.last_used === 'string')
+            bundle.last_used = parsed.last_used;
+        if (parsed.meta && typeof parsed.meta === 'object')
+            bundle.meta = parsed.meta;
+        // Skip bundles with invalid env keys rather than throwing — same lenient
+        // posture readBundle had via the outer catch.
+        let valid = true;
+        for (const key of Object.keys(bundle.vars)) {
+            if (!ENV_KEY_PATTERN.test(key)) {
+                valid = false;
+                break;
+            }
         }
+        if (!valid)
+            continue;
+        out.push(bundle);
     }
     return out.sort((a, b) => a.name.localeCompare(b.name));
 }
@@ -247,41 +294,217 @@ function stampLastUsed(bundle) {
     }
     try {
         bundle.last_used = new Date(nowMs).toISOString();
-        writeBundle(bundle);
+        writeBundle(bundle, { emitEvent: false });
     }
     catch {
         // Swallow — telemetry must never block secret resolution.
     }
 }
-// Walk the bundle and produce a flat env map. Keychain refs are translated via
-// the bundle-scoped naming scheme so two bundles with the same short ID never
-// collide. Throws on the first missing secret so `agents run` fails loudly
-// rather than silently injecting empty strings.
-export function resolveBundleEnv(bundle) {
+export function resolveBundleEnv(bundle, opts = {}) {
     stampLastUsed(bundle);
-    const env = {};
+    const parsedByKey = new Map();
+    const keychainItemsToFetch = [];
+    const keychainKeys = [];
+    const kindCounts = {};
     for (const [key, raw] of Object.entries(bundle.vars)) {
         const parsed = parseBundleValue(raw);
-        if ('literal' in parsed) {
-            env[key] = parsed.literal;
-            continue;
+        parsedByKey.set(key, parsed);
+        const kind = 'literal' in parsed ? 'literal' : parsed.ref.provider;
+        kindCounts[kind] = (kindCounts[kind] ?? 0) + 1;
+        if ('ref' in parsed && parsed.ref.provider === 'keychain') {
+            const item = secretsKeychainItem(bundle.name, parsed.ref.value);
+            keychainItemsToFetch.push(item);
+            keychainKeys.push(key);
         }
-        try {
-            env[key] = resolveRef(parsed.ref, {
-                allowExec: bundle.allow_exec,
-                iCloudSync: bundle.icloud_sync,
-                keychainItemFor: (shortId) => secretsKeychainItem(bundle.name, shortId),
-            });
+    }
+    const keys = Object.keys(bundle.vars).sort();
+    keychainKeys.sort();
+    const emitReadAudit = (status, err) => {
+        emit('secrets.get', {
+            bundle: bundle.name,
+            caller: opts.caller,
+            status,
+            keyCount: keys.length,
+            keys,
+            keychainKeys,
+            kindCounts,
+            error: err instanceof Error ? err.message : (err ? String(err) : undefined),
+        });
+    };
+    // Build the localizedReason shown under the Touch ID prompt. Lowercase verb
+    // phrase per Apple HIG — the system prepends "<App> is required to ".
+    const reason = opts.caller
+        ? `read ${bundle.name} secrets (for ${opts.caller})`
+        : `read ${bundle.name} secrets`;
+    try {
+        // Single helper invocation, one biometric prompt.
+        const fetched = keychainItemsToFetch.length > 0
+            ? getKeychainTokensBatch(keychainItemsToFetch, bundle.icloud_sync, reason)
+            : new Map();
+        // Second pass: assemble env. Keychain values come from the batch; everything
+        // else is resolved inline (literals and env/file/exec refs don't prompt).
+        const env = {};
+        for (const [key] of Object.entries(bundle.vars)) {
+            const parsed = parsedByKey.get(key);
+            if ('literal' in parsed) {
+                env[key] = parsed.literal;
+                continue;
+            }
+            if (parsed.ref.provider === 'keychain') {
+                const item = secretsKeychainItem(bundle.name, parsed.ref.value);
+                const value = fetched.get(item);
+                if (value === undefined) {
+                    throw new Error(`Bundle '${bundle.name}' key '${key}': keychain item '${item}' not found. ` +
+                        `Run: agents secrets add ${bundle.name} ${key}`);
+                }
+                env[key] = value;
+                continue;
+            }
+            try {
+                env[key] = resolveRef(parsed.ref, {
+                    allowExec: bundle.allow_exec,
+                    iCloudSync: bundle.icloud_sync,
+                    keychainItemFor: (shortId) => secretsKeychainItem(bundle.name, shortId),
+                });
+            }
+            catch (err) {
+                throw new Error(`Bundle '${bundle.name}' key '${key}': ${err.message}`);
+            }
+        }
+        emitReadAudit('success');
+        return env;
+    }
+    catch (err) {
+        emitReadAudit('error', err);
+        throw err;
+    }
+}
+/**
+ * Read a bundle's metadata AND resolve its env in a single Touch ID prompt.
+ *
+ * `readBundle` + `resolveBundleEnv` issued two separate `LAContext` calls
+ * (metadata read via `get-auth`, then secret values via `get-batch`) which
+ * surfaced as two consecutive Touch ID prompts. macOS does not honor
+ * "Always Allow" for items protected with `kSecAttrAccessControl`+biometry,
+ * so caching at the OS level was never an option. This collapses both reads
+ * into one `get-batch` call: we enumerate the bundle's secret items first
+ * (silent — `list` returns attrs only and does not trigger biometry) and
+ * include the metadata item in the same batch. One prompt, correctly scoped
+ * to the bundle name and caller.
+ */
+export function readAndResolveBundleEnv(name, opts = {}) {
+    validateBundleName(name);
+    const metaItem = bundleMetaItem(name);
+    const bundleSecretPrefix = `${SECRETS_ITEM_PREFIX}${name}.`;
+    let secretItems;
+    try {
+        secretItems = listKeychainItems(bundleSecretPrefix);
+    }
+    catch {
+        secretItems = [];
+    }
+    const reason = opts.caller
+        ? `read ${name} secrets (for ${opts.caller})`
+        : `read ${name} secrets`;
+    // icloud_sync flag is unknown until we parse metadata, but the helper's
+    // get-batch uses kSecAttrSynchronizableAny so it finds both synced and
+    // device-local items in one shot.
+    const fetched = getKeychainTokensBatch([metaItem, ...secretItems], false, reason);
+    const json = fetched.get(metaItem);
+    if (json === undefined) {
+        throw new Error(`Secrets bundle '${name}' not found.`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        throw new Error(`Bundle '${name}' is malformed.`);
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        throw new Error(`Bundle '${name}' is malformed.`);
+    }
+    const bundle = {
+        name,
+        description: parsed.description,
+        allow_exec: Boolean(parsed.allow_exec),
+        icloud_sync: Boolean(parsed.icloud_sync),
+        vars: parsed.vars && typeof parsed.vars === 'object' ? parsed.vars : {},
+    };
+    if (typeof parsed.created_at === 'string')
+        bundle.created_at = parsed.created_at;
+    if (typeof parsed.updated_at === 'string')
+        bundle.updated_at = parsed.updated_at;
+    if (typeof parsed.last_used === 'string')
+        bundle.last_used = parsed.last_used;
+    if (parsed.meta && typeof parsed.meta === 'object')
+        bundle.meta = parsed.meta;
+    for (const key of Object.keys(bundle.vars)) {
+        validateEnvKey(key);
+    }
+    stampLastUsed(bundle);
+    const parsedByKey = new Map();
+    const keychainKeys = [];
+    const kindCounts = {};
+    for (const [key, raw] of Object.entries(bundle.vars)) {
+        const p = parseBundleValue(raw);
+        parsedByKey.set(key, p);
+        const kind = 'literal' in p ? 'literal' : p.ref.provider;
+        kindCounts[kind] = (kindCounts[kind] ?? 0) + 1;
+        if ('ref' in p && p.ref.provider === 'keychain') {
+            keychainKeys.push(key);
         }
-        catch (err) {
-            const msg = err.message;
-            if (parsed.ref.provider === 'keychain' && /not found/.test(msg)) {
-                throw new Error(`${msg} Run: agents secrets add ${bundle.name} ${key}`);
+    }
+    const keys = Object.keys(bundle.vars).sort();
+    keychainKeys.sort();
+    const emitReadAudit = (status, err) => {
+        emit('secrets.get', {
+            bundle: bundle.name,
+            caller: opts.caller,
+            status,
+            keyCount: keys.length,
+            keys,
+            keychainKeys,
+            kindCounts,
+            error: err instanceof Error ? err.message : (err ? String(err) : undefined),
+        });
+    };
+    try {
+        const env = {};
+        for (const [key] of Object.entries(bundle.vars)) {
+            const p = parsedByKey.get(key);
+            if ('literal' in p) {
+                env[key] = p.literal;
+                continue;
+            }
+            if (p.ref.provider === 'keychain') {
+                const item = secretsKeychainItem(bundle.name, p.ref.value);
+                const value = fetched.get(item);
+                if (value === undefined) {
+                    throw new Error(`Bundle '${bundle.name}' key '${key}': keychain item '${item}' not found. ` +
+                        `Run: agents secrets add ${bundle.name} ${key}`);
+                }
+                env[key] = value;
+                continue;
+            }
+            try {
+                env[key] = resolveRef(p.ref, {
+                    allowExec: bundle.allow_exec,
+                    iCloudSync: bundle.icloud_sync,
+                    keychainItemFor: (shortId) => secretsKeychainItem(bundle.name, shortId),
+                });
+            }
+            catch (err) {
+                throw new Error(`Bundle '${bundle.name}' key '${key}': ${err.message}`);
             }
-            throw new Error(`Bundle '${bundle.name}' key '${key}': ${msg}`);
         }
+        emitReadAudit('success');
+        return { bundle, env };
+    }
+    catch (err) {
+        emitReadAudit('error', err);
+        throw err;
     }
-    return env;
 }
 // Build a keychain ref expression from a bundle+key pair, for storage in the bundle metadata.
 export function keychainRef(key) {

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

@@ -1,7 +1,7 @@
 /**
  * Cross-platform secure credential storage.
  *
- * macOS: Uses Keychain via signed Swift helper (AgentsKeychain.app) or `security` CLI.
+ * macOS: Uses Keychain via signed Swift helper (Agents CLI.app) or `security` CLI.
  * Linux: Uses libsecret (GNOME Keyring) via `secret-tool` CLI.
  * Windows: Not yet supported.
  *
@@ -56,6 +56,15 @@ export declare function setKeychainBackendForTest(b: KeychainBackend | null): Ke
 export declare function hasKeychainToken(item: string, sync?: boolean): boolean;
 /** Retrieve a secret value from the keychain/keyring. Throws if not found. */
 export declare function getKeychainToken(item: string, sync?: boolean): string;
+/**
+ * Read multiple keychain items, returning a Map keyed by item name. Missing or
+ * unreadable items are simply absent from the map (the caller decides whether a
+ * given key was required).
+ *
+ * On macOS this uses the signed helper's `get-batch` command so one LAContext
+ * can satisfy all protected item reads for the bundle.
+ */
+export declare function getKeychainTokensBatch(items: string[], sync?: boolean, reason?: string): Map<string, string>;
 /** Store or update a secret value in the keychain/keyring. iCloud-synced when sync=true (macOS only). */
 export declare function setKeychainToken(item: string, value: string, sync?: boolean): void;
 /** Delete a keychain/keyring item. Returns true if it existed. */

package/dist/lib/secrets/index.js

@@ -1,7 +1,7 @@
 /**
  * Cross-platform secure credential storage.
  *
- * macOS: Uses Keychain via signed Swift helper (AgentsKeychain.app) or `security` CLI.
+ * macOS: Uses Keychain via signed Swift helper (Agents CLI.app) or `security` CLI.
  * Linux: Uses libsecret (GNOME Keyring) via `secret-tool` CLI.
  * Windows: Not yet supported.
  *
@@ -17,6 +17,8 @@ import * as os from 'os';
 import * as path from 'path';
 import { linuxBackend } from './linux.js';
 const SERVICE_PREFIX = 'agents-cli';
+const SECRETS_ITEM_PREFIX = `${SERVICE_PREFIX}.secrets.`;
+const BUNDLES_ITEM_PREFIX = `${SERVICE_PREFIX}.bundles.`;
 const REF_PATTERN = /^(keychain|env|file|exec):(.+)$/s;
 /** Parse a bundle value into either a literal string or a typed secret ref. */
 export function parseBundleValue(raw) {
@@ -37,8 +39,9 @@ export function serializeRef(ref) {
 }
 function assertSupportedPlatform() {
     if (process.platform !== 'darwin' && process.platform !== 'linux') {
-        throw new Error('Secure credential storage requires macOS or Linux. ' +
-            'On Windows, use environment variables or .env files instead.');
+        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).');
     }
 }
 function isLinux() {
@@ -53,9 +56,12 @@ export function profileKeychainItem(provider) {
 }
 /** Build the keychain item name for a secrets-bundle key. */
 export function secretsKeychainItem(bundle, key) {
-    return `${SERVICE_PREFIX}.secrets.${bundle}.${key}`;
+    return `${SECRETS_ITEM_PREFIX}${bundle}.${key}`;
 }
-// Resolve the bundled, signed-and-notarized AgentsKeychain.app shipped
+function keychainItemRequiresUserPresence(item) {
+    return item.startsWith(SECRETS_ITEM_PREFIX) || item.startsWith(BUNDLES_ITEM_PREFIX);
+}
+// Resolve the bundled, signed-and-notarized Agents CLI.app shipped
 // alongside the compiled JS. The .app embeds a provisioning profile that
 // grants the application-identifier + keychain-access-groups entitlements
 // macOS requires for kSecAttrSynchronizable writes. Bare CLI binaries
@@ -64,7 +70,7 @@ export function secretsKeychainItem(bundle, key) {
 // be prebuilt by `scripts/build-keychain-helper.sh` and shipped.
 function ensureKeychainHelper() {
     const here = path.dirname(fileURLToPath(import.meta.url));
-    const binPath = path.join(here, 'AgentsKeychain.app', 'Contents', 'MacOS', 'AgentsKeychain');
+    const binPath = path.join(here, 'Agents CLI.app', 'Contents', 'MacOS', 'Agents CLI');
     if (!fs.existsSync(binPath)) {
         throw new Error(`Keychain helper missing at ${binPath}. ` +
             'This npm package was built without the signed helper bundle. Reinstall agents-cli.');
@@ -91,8 +97,12 @@ export function hasKeychainToken(item, sync = false) {
     assertSupportedPlatform();
     if (isLinux())
         return linuxBackend.has(item, sync);
-    // macOS: Try security first (no prompts for local items), fall back to binary for synced items.
-    if (spawnSync('security', ['find-generic-password', '-a', os.userInfo().username, '-s', item, '-w'], {
+    // macOS: `security find-generic-password` *without* `-w` only reads item
+    // metadata, never the value, so it doesn't consult the item's ACL — no
+    // prompt. The previous code passed `-w`, which forced decryption and
+    // triggered the "security wants to access keychain" sheet on every item
+    // the helper had written. Existence checks never need the value.
+    if (spawnSync('security', ['find-generic-password', '-a', os.userInfo().username, '-s', item], {
         stdio: ['ignore', 'pipe', 'pipe'],
     }).status === 0)
         return true;
@@ -109,18 +119,38 @@ export function getKeychainToken(item, sync = false) {
     assertSupportedPlatform();
     if (isLinux())
         return linuxBackend.get(item, sync);
-    // macOS: Try security first (no prompts for local items)
-    const secResult = spawnSync('security', ['find-generic-password', '-a', os.userInfo().username, '-s', item, '-w'], {
-        stdio: ['ignore', 'pipe', 'pipe'],
-    });
-    if (secResult.status === 0) {
-        const token = secResult.stdout?.toString().trim();
-        if (token)
-            return token;
+    // macOS: read through the signed helper FIRST. The helper holds the
+    // keychain-access-group entitlement (so it reads iCloud-synced items) and
+    // supplies an LAContext for items protected by kSecAttrAccessControl.
+    //
+    // Bare `security` is only a fallback for when the helper bundle is absent
+    // (e.g. a dev build without the .app). It must NOT be tried first: macOS
+    // shows the "security wants to access … enter keychain password" sheet on any
+    // item whose ACL doesn't list `security`, which is every item we write. That
+    // security-first ordering is exactly what made bundle reads prompt on every
+    // `secrets exec`.
+    let bin;
+    try {
+        bin = ensureKeychainHelper();
     }
-    // Fallback: binary searches both synced and non-synced via kSecAttrSynchronizableAny
-    const bin = ensureKeychainHelper();
-    const result = spawnSync(bin, ['get', item, os.userInfo().username], {
+    catch {
+        // Helper bundle missing — degrade to security. Reads items security created
+        // without a prompt; restrictive items may still prompt (dev-build only).
+        const secResult = spawnSync('security', ['find-generic-password', '-a', os.userInfo().username, '-s', item, '-w'], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        if (secResult.status === 0) {
+            const token = secResult.stdout?.toString().trim();
+            if (token)
+                return token;
+        }
+        throw new Error(`Keychain item '${item}' not found.`);
+    }
+    // Helper searches both synced and non-synced via kSecAttrSynchronizableAny.
+    const args = keychainItemRequiresUserPresence(item)
+        ? ['get-auth', item, os.userInfo().username, '--reason', 'read agents-cli secrets']
+        : ['get', item, os.userInfo().username];
+    const result = spawnSync(bin, args, {
         stdio: ['ignore', 'pipe', 'pipe'],
     });
     if (result.status === 1)
@@ -134,6 +164,72 @@ export function getKeychainToken(item, sync = false) {
         throw new Error(`Keychain item '${item}' exists but is empty.`);
     return token;
 }
+/**
+ * Read multiple keychain items, returning a Map keyed by item name. Missing or
+ * unreadable items are simply absent from the map (the caller decides whether a
+ * given key was required).
+ *
+ * On macOS this uses the signed helper's `get-batch` command so one LAContext
+ * can satisfy all protected item reads for the bundle.
+ */
+export function getKeychainTokensBatch(items, sync = false, reason = 'read agents-cli secrets') {
+    const result = new Map();
+    if (backend) {
+        for (const item of items) {
+            try {
+                result.set(item, backend.get(item, sync));
+            }
+            catch {
+                // Missing or unreadable — skip; the caller reports which key is missing.
+            }
+        }
+        return result;
+    }
+    assertSupportedPlatform();
+    if (isLinux()) {
+        for (const item of items) {
+            try {
+                result.set(item, linuxBackend.get(item, sync));
+            }
+            catch {
+                // Missing or unreadable — skip; the caller reports which key is missing.
+            }
+        }
+        return result;
+    }
+    let bin;
+    try {
+        bin = ensureKeychainHelper();
+    }
+    catch {
+        for (const item of items) {
+            try {
+                result.set(item, getKeychainToken(item, sync));
+            }
+            catch {
+                // Missing or unreadable — skip; the caller reports which key is missing.
+            }
+        }
+        return result;
+    }
+    const proc = spawnSync(bin, ['get-batch', os.userInfo().username, '--reason', reason, ...items], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (proc.status !== 0)
+        return result;
+    const out = proc.stdout?.toString() || '';
+    for (const line of out.split('\n')) {
+        if (!line)
+            continue;
+        const tab = line.indexOf('\t');
+        if (tab <= 0)
+            continue;
+        const item = line.slice(0, tab);
+        const encoded = line.slice(tab + 1);
+        result.set(item, Buffer.from(encoded, 'base64').toString('utf8'));
+    }
+    return result;
+}
 /** Store or update a secret value in the keychain/keyring. iCloud-synced when sync=true (macOS only). */
 export function setKeychainToken(item, value, sync = false) {
     if (backend) {
@@ -151,28 +247,21 @@ export function setKeychainToken(item, value, sync = false) {
         linuxBackend.set(item, value, sync);
         return;
     }
-    // macOS path
-    if (sync) {
-        const bin = ensureKeychainHelper();
-        const result = spawnSync(bin, ['set', item, os.userInfo().username], {
-            input: value,
-            stdio: ['pipe', 'pipe', 'pipe'],
-        });
-        if (result.status !== 0) {
-            const msg = result.stderr?.toString().trim();
-            throw new Error(msg || `Failed to write keychain item '${item}'.`);
-        }
-        return;
-    }
-    // `security -i` keeps the value out of argv (and `ps`).
-    const user = os.userInfo().username;
-    const cmd = `add-generic-password -a ${quoteForSecurityCli(user)} -s ${quoteForSecurityCli(item)} -w ${quoteForSecurityCli(value)} -T ${quoteForSecurityCli('')} -U\n`;
-    const result = spawnSync('security', ['-i'], {
-        input: cmd,
+    // macOS path. Both sync and non-sync writes go through the .app helper so
+    // the item picks up kSecAttrAccessControl user-presence protection. The
+    // helper takes an optional `nosync` arg for device-local writes; sync writes
+    // get kSecAttrSynchronizable=true by default.
+    const bin = ensureKeychainHelper();
+    const args = ['set', item, os.userInfo().username];
+    if (!sync)
+        args.push('nosync');
+    const result = spawnSync(bin, args, {
+        input: value,
         stdio: ['pipe', 'pipe', 'pipe'],
     });
     if (result.status !== 0) {
-        throw new Error(`Failed to write keychain item '${item}' (exit ${result.status}).`);
+        const msg = result.stderr?.toString().trim();
+        throw new Error(msg || `Failed to write keychain item '${item}'.`);
     }
 }
 /** Delete a keychain/keyring item. Returns true if it existed. */
@@ -182,20 +271,26 @@ export function deleteKeychainToken(item, sync = false) {
     assertSupportedPlatform();
     if (isLinux())
         return linuxBackend.delete(item, sync);
-    // macOS: Try security first (no prompts for local items), fall back to binary for synced items.
-    if (!sync && spawnSync('security', ['delete-generic-password', '-a', os.userInfo().username, '-s', item], {
-        stdio: ['ignore', 'pipe', 'pipe'],
-    }).status === 0)
-        return true;
-    // Fallback: binary deletes synced items via kSecAttrSynchronizableAny
-    const bin = ensureKeychainHelper();
+    // macOS: delete through the signed helper FIRST. `security delete-generic-password`
+    // prompts for keychain-password authorization on any item whose ACL doesn't list
+    // `security` — which is every item the helper writes. Same reasoning as
+    // getKeychainToken's helper-first ordering above. The helper also handles the
+    // synced keychain via kSecAttrSynchronizableAny in one call.
+    let bin;
+    try {
+        bin = ensureKeychainHelper();
+    }
+    catch {
+        // Helper bundle missing (dev build). Fall back to security; it can only
+        // touch non-synced items and may prompt for items it didn't write.
+        return spawnSync('security', ['delete-generic-password', '-a', os.userInfo().username, '-s', item], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+        }).status === 0;
+    }
     return spawnSync(bin, ['delete', item, os.userInfo().username], {
         stdio: ['ignore', 'pipe', 'pipe'],
     }).status === 0;
 }
-function quoteForSecurityCli(s) {
-    return '"' + s.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
-}
 /** Enumerate keychain/keyring item names starting with the given prefix. */
 export function listKeychainItems(prefix) {
     if (backend)

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

@@ -20,6 +20,14 @@ export interface ActiveSession {
     cloudProvider?: string;
     cloudTaskId?: string;
     cloudStatus?: string;
+    /**
+     * IDE window that owns this terminal. Source of truth is the per-window
+     * slice key in `live-terminals.json` (computeWindowId in the swarmify
+     * extension): `${vscode.env.sessionId}-${extension-host pid}`. Lets the
+     * renderer cluster terminals that belong to the same IDE window even when
+     * two windows have the same cwd open. Only populated for `terminal` context.
+     */
+    windowId?: string;
 }
 export interface ActiveQueryOptions {
     /** Skip the `ps` scan for ad-hoc headless agents. */

package/dist/lib/session/active.js

@@ -73,11 +73,11 @@ function readLiveTerminals() {
     if (!parsed || typeof parsed !== 'object')
         return [];
     const merged = new Map();
-    for (const slice of Object.values(parsed)) {
+    for (const [windowId, slice] of Object.entries(parsed)) {
         for (const e of (slice?.entries ?? [])) {
             if (!e?.sessionId || !isPidAlive(e.pid))
                 continue;
-            merged.set(e.sessionId, e);
+            merged.set(e.sessionId, { ...e, windowId });
         }
     }
     return Array.from(merged.values());
@@ -259,6 +259,7 @@ export async function listTerminalsActive() {
             sessionFile,
             startedAtMs: t.startedAtMs,
             status: classifyActivity(sessionFile),
+            windowId: t.windowId,
         };
     });
 }