@phnx-labs/agents-cli 1.19.2 → 1.20.3

package/dist/lib/secrets/index.js

@@ -1,22 +1,33 @@
 /**
  * Cross-platform secure credential storage.
  *
- * 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.
+ * macOS: every keychain operation goes through the signed `Agents CLI.app`
+ * helper. The helper attaches a biometry-or-passcode access control to every
+ * item it writes, so the OS itself gates decryption with Touch ID. A single
+ * LAContext lives for the helper's process lifetime, so a batch read pops
+ * Touch ID once and reuses the assertion for every item in the same batch.
+ * No /usr/bin/security fast path: that path bypasses the helper's ACL,
+ * exposes items to the legacy password sheet, and would defeat the model.
  *
- * The .app embeds a provisioning profile that grants the application-identifier
- * + keychain-access-groups entitlement macOS requires for kSecAttrSynchronizable
- * writes (iCloud Keychain). For device-local writes the helper is invoked with
- * the `nosync` arg.
+ * Linux: libsecret (GNOME Keyring) via the `secret-tool` CLI. No biometry —
+ * items are unlocked when the keyring is open.
+ *
+ * Windows: not supported.
+ *
+ * Items are device-local: the biometry access control requires the OS to
+ * treat them as bound to this device, so cross-machine propagation goes
+ * through the explicit export/import flow in src/lib/secrets/sync.ts
+ * rather than the system's cloud-keychain path.
  */
-import { fileURLToPath } from 'url';
 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 { getKeychainHelperPath } from './install-helper.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,39 +48,24 @@ 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() {
     return process.platform === 'linux';
 }
-function isMacOS() {
-    return process.platform === 'darwin';
-}
 /** Build the keychain item name for a profile provider token. */
 export function profileKeychainItem(provider) {
     return `${SERVICE_PREFIX}.${provider}.token`;
 }
 /** 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 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
-// (ad-hoc or Developer ID) cannot do this; only an .app with an embedded
-// profile can. So compile-on-first-use is not possible — the binary must
-// 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, '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.');
-    }
-    return binPath;
+function keychainItemRequiresUserPresence(item) {
+    return item.startsWith(SECRETS_ITEM_PREFIX) || item.startsWith(BUNDLES_ITEM_PREFIX);
 }
 let backend = null;
 /** Install a custom keychain backend (test only). Returns the previous backend so callers can restore. */
@@ -78,85 +74,94 @@ export function setKeychainBackendForTest(b) {
     backend = b;
     return prev;
 }
-// Backend routing: non-sync items go through /usr/bin/security with an empty
-// trusted-app ACL; existing items written by older versions retain their ACL.
-// Sync items must go through the signed .app — only the .app
-// holds the keychain-access-groups entitlement macOS requires for
-// kSecAttrSynchronizable. Enumeration also goes through the .app because the
-// security CLI doesn't expose listing by service prefix.
-/** Check if a keychain/keyring item exists. */
-export function hasKeychainToken(item, sync = false) {
+/**
+ * Items whose name does NOT start with `agents-cli.` belong to another
+ * application (e.g. Anthropic's `Claude Code-credentials-*`). Their ACL
+ * trusts THEIR writer, not our signed helper, so routing them through our
+ * helper produces a legacy password sheet. `/usr/bin/security` reads them
+ * silently because it's in the default trusted-app list on most user-owned
+ * keychain items. And we MUST NOT JIT-migrate them — the owning app
+ * expects to re-write the item with its own ACL design.
+ */
+function isOurItem(item) {
+    return item.startsWith('agents-cli.');
+}
+/** Check if a keychain/keyring item exists. Never prompts for biometry. */
+export function hasKeychainToken(item) {
     if (backend)
-        return backend.has(item, sync);
+        return backend.has(item);
     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'], {
-        stdio: ['ignore', 'pipe', 'pipe'],
-    }).status === 0)
-        return true;
-    // Fallback: binary searches both synced and non-synced via kSecAttrSynchronizableAny
-    const bin = ensureKeychainHelper();
+        return linuxBackend.has(item);
+    if (!isOurItem(item)) {
+        return spawnSync('/usr/bin/security', ['find-generic-password', '-a', os.userInfo().username, '-s', item], {
+            stdio: ['ignore', 'ignore', 'ignore'],
+        }).status === 0;
+    }
+    const bin = getKeychainHelperPath();
     return spawnSync(bin, ['has', item, os.userInfo().username], {
         stdio: ['ignore', 'pipe', 'pipe'],
     }).status === 0;
 }
-/** Retrieve a secret value from the keychain/keyring. Throws if not found. */
-export function getKeychainToken(item, sync = false) {
+/**
+ * Retrieve a secret value from the keychain/keyring. Throws if not found.
+ *
+ * On macOS this triggers Touch ID (or reuses an assertion held by an earlier
+ * call in the same process). For bundles, prefer getKeychainTokens() so a
+ * single biometric prompt covers every key in the batch.
+ */
+export function getKeychainToken(item) {
     if (backend)
-        return backend.get(item, sync);
+        return backend.get(item);
     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;
+        return linuxBackend.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'],
+        });
+        if (sec.status === 0) {
+            const token = sec.stdout?.toString().trim();
+            if (token)
+                return token;
+        }
+        throw new Error(`Keychain item '${item}' not found.`);
     }
-    // Fallback: binary searches both synced and non-synced via kSecAttrSynchronizableAny.
-    // `get` is the unauthenticated path — no LocalAuthentication prompt. Used by
-    // profiles.ts (OAuth refresh) where biometric on every API call is too noisy.
-    const bin = ensureKeychainHelper();
+    const bin = getKeychainHelperPath();
     const result = spawnSync(bin, ['get', item, os.userInfo().username], {
         stdio: ['ignore', 'pipe', 'pipe'],
     });
     if (result.status === 1)
         throw new Error(`Keychain item '${item}' not found.`);
+    if (result.status === 4)
+        throw new Error(`Touch ID cancelled while reading '${item}'.`);
     if (result.status !== 0) {
         const msg = result.stderr?.toString().trim();
         throw new Error(msg || `Failed to read keychain item '${item}'.`);
     }
-    const token = result.stdout?.toString().trim();
+    const token = result.stdout?.toString();
     if (!token)
         throw new Error(`Keychain item '${item}' exists but is empty.`);
     return token;
 }
 /**
- * Batch-read multiple keychain items behind a single LocalAuthentication
- * prompt. macOS shows ONE Touch ID prompt and every requested item is
- * unlocked in the same process. Returns a Map keyed by item name. Missing
- * items are absent from the map (caller decides whether that's an error).
- *
- * `reason` is shown to the user under the Touch ID prompt — e.g.
- * "read 'hetzner.com' secrets for agent 'claude'". Apple's HIG recommends
- * a lowercase verb phrase that completes the sentence "X is required to ___".
+ * Batch-read multiple keychain items behind a single Touch ID prompt. The
+ * macOS helper holds one LAContext for its whole process: the first protected
+ * item triggers Touch ID, every later item in the same invocation reuses the
+ * assertion. Missing items are absent from the returned map (caller decides
+ * whether that's an error).
  *
  * On Linux or when a test backend is installed, falls back to individual
- * `get` calls — no biometric prompt path on those platforms.
+ * lookups — no biometric prompt path on those platforms.
  */
-export function getKeychainTokensBatch(items, _sync = false, reason) {
+export function getKeychainTokens(items) {
     const result = new Map();
     if (items.length === 0)
         return result;
     if (backend) {
         for (const item of items) {
             try {
-                result.set(item, backend.get(item, _sync));
+                result.set(item, backend.get(item));
             }
             catch { /* missing — skip */ }
         }
@@ -166,34 +171,31 @@ export function getKeychainTokensBatch(items, _sync = false, reason) {
     if (isLinux()) {
         for (const item of items) {
             try {
-                result.set(item, linuxBackend.get(item, _sync));
+                result.set(item, linuxBackend.get(item));
             }
             catch { /* missing — skip */ }
         }
         return result;
     }
-    // macOS: single helper invocation with Touch ID gate.
-    const bin = ensureKeychainHelper();
-    const helperArgs = ['get-batch', os.userInfo().username];
-    if (reason)
-        helperArgs.push('--reason', reason);
-    helperArgs.push(...items);
-    const child = spawnSync(bin, helperArgs, {
+    const bin = getKeychainHelperPath();
+    const child = spawnSync(bin, ['get-batch', os.userInfo().username, ...items], {
         stdio: ['ignore', 'pipe', 'pipe'],
     });
+    if (child.status === 4) {
+        throw new Error(`Touch ID cancelled while reading ${items.length} keychain item(s).`);
+    }
     if (child.status !== 0) {
         const msg = child.stderr?.toString().trim();
         throw new Error(msg || `Failed to batch-read ${items.length} keychain items.`);
     }
     const out = child.stdout?.toString() ?? '';
-    // Parser. Output is a sequence of records:
+    // Output is a sequence of records, one per service in input order:
     //   "V <service>\n<value>\n"   (present)
     //   "M <service>\n"            (missing)
-    // Service names cannot contain '\n' (validated at write time); values are
-    // also newline-free (rejected by setKeychainToken). So splitting on '\n'
+    // Service names are validated newline/'='-free by setKeychainToken below
+    // and values are rejected if they contain newlines — so splitting on '\n'
     // and walking line-by-line is unambiguous.
     const lines = out.split('\n');
-    // Last entry from split is the empty string after a trailing newline.
     let i = 0;
     while (i < lines.length) {
         const line = lines[i];
@@ -217,10 +219,10 @@ export function getKeychainTokensBatch(items, _sync = false, reason) {
     }
     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) {
+/** Store or update a secret value in the keychain/keyring. Device-local; biometry-gated on macOS. */
+export function setKeychainToken(item, value) {
     if (backend) {
-        backend.set(item, value, sync);
+        backend.set(item, value);
         return;
     }
     assertSupportedPlatform();
@@ -231,20 +233,11 @@ export function setKeychainToken(item, value, sync = false) {
     if (/[\x00=\r\n]/.test(item))
         throw new Error('Secret item name contains invalid characters.');
     if (isLinux()) {
-        linuxBackend.set(item, value, sync);
+        linuxBackend.set(item, value);
         return;
     }
-    // macOS path. Both sync and non-sync writes go through the .app helper so
-    // the item picks up our SecAccess ACL (helper as trusted reader). That ACL
-    // is what stops macOS from showing the legacy "enter password" sheet on
-    // subsequent reads. 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, {
+    const bin = getKeychainHelperPath();
+    const result = spawnSync(bin, ['set', item, os.userInfo().username], {
         input: value,
         stdio: ['pipe', 'pipe', 'pipe'],
     });
@@ -253,20 +246,14 @@ export function setKeychainToken(item, value, sync = false) {
         throw new Error(msg || `Failed to write keychain item '${item}'.`);
     }
 }
-/** Delete a keychain/keyring item. Returns true if it existed. */
-export function deleteKeychainToken(item, sync = false) {
+/** Delete a keychain/keyring item. Returns true if it existed. Never prompts for biometry. */
+export function deleteKeychainToken(item) {
     if (backend)
-        return backend.delete(item, sync);
+        return backend.delete(item);
     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();
+        return linuxBackend.delete(item);
+    const bin = getKeychainHelperPath();
     return spawnSync(bin, ['delete', item, os.userInfo().username], {
         stdio: ['ignore', 'pipe', 'pipe'],
     }).status === 0;
@@ -278,8 +265,7 @@ export function listKeychainItems(prefix) {
     assertSupportedPlatform();
     if (isLinux())
         return linuxBackend.list(prefix);
-    // macOS path
-    const bin = ensureKeychainHelper();
+    const bin = getKeychainHelperPath();
     const result = spawnSync(bin, ['list', prefix], {
         stdio: ['ignore', 'pipe', 'pipe'],
     });
@@ -290,6 +276,31 @@ export function listKeychainItems(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
+ * (which may pop the password sheet once), then deletes and re-adds it with
+ * the biometry access control. Returns true if the item was rewritten, false
+ * if no item by that name exists. macOS only — Linux backends have no ACL
+ * concept, so the call is a no-op there.
+ */
+export function migrateKeychainItem(item) {
+    if (backend)
+        return backend.has(item);
+    assertSupportedPlatform();
+    if (isLinux())
+        return linuxBackend.has(item);
+    const bin = getKeychainHelperPath();
+    const result = spawnSync(bin, ['migrate-acl', item, os.userInfo().username], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (result.status === 0)
+        return true;
+    if (result.status === 1)
+        return false;
+    const msg = result.stderr?.toString().trim();
+    throw new Error(msg || `Failed to migrate keychain item '${item}'.`);
+}
 function expandHome(p) {
     if (p.startsWith('~/') || p === '~') {
         return path.join(os.homedir(), p.slice(1));
@@ -301,7 +312,7 @@ export function resolveRef(ref, opts = {}) {
     switch (ref.provider) {
         case 'keychain': {
             const item = opts.keychainItemFor ? opts.keychainItemFor(ref.value) : ref.value;
-            return getKeychainToken(item, opts.iCloudSync);
+            return getKeychainToken(item);
         }
         case 'env': {
             const name = ref.value;

package/dist/lib/secrets/install-helper.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Stable install location for the signed macOS Keychain helper.
+ *
+ * Why a stable path: every npm publish re-signs `Agents CLI.app` with a fresh
+ * timestamp, producing a new code signature. macOS Keychain trusted-app ACLs
+ * are pinned to the exact signature, so the ACL invalidates on every release
+ * when the helper lives inside the npm package directory. Copying the .app
+ * once to `~/Library/Application Support/agents-cli/` gives it a path that
+ * survives `npm i -g`, `scripts/install.sh`, version bumps, etc.
+ *
+ * This module is the SINGLE SOURCE OF TRUTH for the helper path. Other
+ * modules in `src/lib/secrets/` must import `getKeychainHelperPath()` rather
+ * than recomputing it.
+ */
+/**
+ * Idempotent install. Copies the bundled `.app` to the stable user path. Skips
+ * if the destination already exists and `codesign --verify` passes, unless
+ * `forceReinstall=true`.
+ *
+ * Notarization is checked via `spctl --assess` after install — a failure is
+ * logged as a warning but does NOT throw. Notarization checks require network
+ * access (Gatekeeper ticket lookup) and are not load-bearing for the helper's
+ * keychain ACL semantics.
+ */
+export declare function ensureKeychainHelperInstalled(opts?: {
+    forceReinstall?: boolean;
+}): void;
+/**
+ * Return the absolute path to the helper executable. If the installed bundle
+ * is missing, performs a lazy install first.
+ *
+ * Throws on non-darwin.
+ */
+export declare function getKeychainHelperPath(): string;
+/** Diagnostic snapshot used by `agents helper status`. */
+export interface KeychainHelperStatus {
+    source: string | null;
+    destination: string;
+    installed: boolean;
+    codesignOk: boolean;
+    codesignOutput: string;
+    spctlOk: boolean;
+    spctlOutput: string;
+}
+export declare function getKeychainHelperStatus(): KeychainHelperStatus;

package/dist/lib/secrets/install-helper.js

@@ -0,0 +1,165 @@
+/**
+ * Stable install location for the signed macOS Keychain helper.
+ *
+ * Why a stable path: every npm publish re-signs `Agents CLI.app` with a fresh
+ * timestamp, producing a new code signature. macOS Keychain trusted-app ACLs
+ * are pinned to the exact signature, so the ACL invalidates on every release
+ * when the helper lives inside the npm package directory. Copying the .app
+ * once to `~/Library/Application Support/agents-cli/` gives it a path that
+ * survives `npm i -g`, `scripts/install.sh`, version bumps, etc.
+ *
+ * This module is the SINGLE SOURCE OF TRUTH for the helper path. Other
+ * modules in `src/lib/secrets/` must import `getKeychainHelperPath()` rather
+ * than recomputing it.
+ */
+import { fileURLToPath } from 'url';
+import { spawnSync } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+const APP_BUNDLE_NAME = 'Agents CLI.app';
+const INSTALL_DIR_NAME = 'agents-cli';
+/** Absolute path to the installed `.app` bundle directory (not the executable). */
+function installedAppPath() {
+    return path.join(os.homedir(), 'Library', 'Application Support', INSTALL_DIR_NAME, APP_BUNDLE_NAME);
+}
+/** Absolute path to the executable inside the installed `.app` bundle. */
+function installedExecutablePath() {
+    return path.join(installedAppPath(), 'Contents', 'MacOS', 'Agents CLI');
+}
+/**
+ * Locate the source `.app` bundle shipped alongside the compiled JS.
+ *
+ * Resolution order:
+ *   1. dist/lib/secrets/Agents CLI.app — sibling of this compiled file (npm install layout)
+ *   2. <repo>/bin/Agents CLI.app       — raw working tree (`bun run dev`, tsx from src/)
+ *
+ * Throws if neither exists.
+ */
+function sourceAppPath() {
+    const candidates = [];
+    try {
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        candidates.push(path.join(here, APP_BUNDLE_NAME));
+        // tsx/src case: src/lib/secrets/install-helper.ts -> ../../../bin/Agents CLI.app
+        candidates.push(path.resolve(here, '..', '..', '..', 'bin', APP_BUNDLE_NAME));
+    }
+    catch { /* import.meta.url unavailable */ }
+    for (const c of candidates) {
+        if (fs.existsSync(c))
+            return c;
+    }
+    throw new Error(`Source ${APP_BUNDLE_NAME} not found. Looked in:\n  ${candidates.join('\n  ')}\n` +
+        'The npm package may have been built without the signed helper bundle. Reinstall agents-cli.');
+}
+function assertDarwin() {
+    if (process.platform !== 'darwin') {
+        throw new Error('Keychain helper is macOS only.');
+    }
+}
+function codesignVerify(appPath) {
+    const r = spawnSync('codesign', ['--verify', '--deep', '--strict', appPath], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        encoding: 'utf-8',
+    });
+    return { ok: r.status === 0, output: (r.stderr || r.stdout || '').toString().trim() };
+}
+function spctlAssess(appPath) {
+    const r = spawnSync('spctl', ['--assess', '--type', 'execute', '--verbose=2', appPath], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        encoding: 'utf-8',
+    });
+    return { ok: r.status === 0, output: (r.stderr || r.stdout || '').toString().trim() };
+}
+function copyAppBundle(src, dest) {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    if (fs.existsSync(dest))
+        fs.rmSync(dest, { recursive: true, force: true });
+    // `cp -R` preserves the bundle's signature, symlinks, and resource forks.
+    // `fs.cpSync({recursive: true})` works on simple trees but has historically
+    // mishandled extended attributes on `.app` bundles, breaking codesign.
+    const r = spawnSync('cp', ['-R', src, dest], { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf-8' });
+    if (r.status !== 0) {
+        const msg = (r.stderr || r.stdout || '').toString().trim();
+        throw new Error(`Failed to copy ${src} -> ${dest}: ${msg || 'unknown error'}`);
+    }
+}
+/**
+ * Idempotent install. Copies the bundled `.app` to the stable user path. Skips
+ * if the destination already exists and `codesign --verify` passes, unless
+ * `forceReinstall=true`.
+ *
+ * Notarization is checked via `spctl --assess` after install — a failure is
+ * logged as a warning but does NOT throw. Notarization checks require network
+ * access (Gatekeeper ticket lookup) and are not load-bearing for the helper's
+ * keychain ACL semantics.
+ */
+export function ensureKeychainHelperInstalled(opts = {}) {
+    assertDarwin();
+    const dest = installedAppPath();
+    if (!opts.forceReinstall && fs.existsSync(dest)) {
+        const { ok } = codesignVerify(dest);
+        if (ok)
+            return;
+    }
+    const src = sourceAppPath();
+    copyAppBundle(src, dest);
+    const verify = codesignVerify(dest);
+    if (!verify.ok) {
+        throw new Error(`Installed helper failed codesign verification at ${dest}.\n${verify.output}\n` +
+            'The bundle may be corrupted. Try `agents helper install` to reinstall, or reinstall agents-cli.');
+    }
+    const assess = spctlAssess(dest);
+    if (!assess.ok) {
+        // Warn, do not fail. Gatekeeper ticket lookup needs network; offline
+        // installs and CI runners commonly fail this check. The ACL semantics
+        // we care about depend on codesign, not spctl.
+        process.stderr.write(`agents-cli: notarization check (spctl) did not pass for ${dest}: ${assess.output}\n`);
+    }
+}
+/**
+ * Return the absolute path to the helper executable. If the installed bundle
+ * is missing, performs a lazy install first.
+ *
+ * Throws on non-darwin.
+ */
+export function getKeychainHelperPath() {
+    assertDarwin();
+    const exec = installedExecutablePath();
+    if (!fs.existsSync(exec)) {
+        ensureKeychainHelperInstalled();
+    }
+    return exec;
+}
+export function getKeychainHelperStatus() {
+    assertDarwin();
+    const destApp = installedAppPath();
+    let src = null;
+    try {
+        src = sourceAppPath();
+    }
+    catch { /* missing source is reported as null */ }
+    const installed = fs.existsSync(destApp);
+    if (!installed) {
+        return {
+            source: src,
+            destination: destApp,
+            installed: false,
+            codesignOk: false,
+            codesignOutput: 'not installed',
+            spctlOk: false,
+            spctlOutput: 'not installed',
+        };
+    }
+    const cs = codesignVerify(destApp);
+    const sp = spctlAssess(destApp);
+    return {
+        source: src,
+        destination: destApp,
+        installed: true,
+        codesignOk: cs.ok,
+        codesignOutput: cs.output || 'ok',
+        spctlOk: sp.ok,
+        spctlOutput: sp.output || 'ok',
+    };
+}

package/dist/lib/secrets/linux.js

@@ -143,16 +143,16 @@ export function listSecretToolItems(prefix) {
 }
 /** KeychainBackend implementation for Linux using secret-tool */
 export const linuxBackend = {
-    has(item, _sync) {
+    has(item) {
         return hasSecretToolToken(item);
     },
-    get(item, _sync) {
+    get(item) {
         return getSecretToolToken(item);
     },
-    set(item, value, _sync) {
+    set(item, value) {
         setSecretToolToken(item, value);
     },
-    delete(item, _sync) {
+    delete(item) {
         return deleteSecretToolToken(item);
     },
     list(prefix) {