@phnx-labs/agents-cli 1.20.0 → 1.20.3

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

@@ -1,14 +1,23 @@
 /**
  * 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.
  */
 /** Supported secret resolution backends. */
 export type SecretProvider = 'keychain' | 'env' | 'file' | 'exec';
@@ -44,33 +53,50 @@ export declare function secretsKeychainItem(bundle: string, key: string): string
  * tests) is destructive and would require an interactive Keychain unlock.
  */
 export interface KeychainBackend {
-    has(item: string, sync: boolean): boolean;
-    get(item: string, sync: boolean): string;
-    set(item: string, value: string, sync: boolean): void;
-    delete(item: string, sync: boolean): boolean;
+    has(item: string): boolean;
+    get(item: string): string;
+    set(item: string, value: string): void;
+    delete(item: string): boolean;
     list(prefix: string): string[];
 }
 /** Install a custom keychain backend (test only). Returns the previous backend so callers can restore. */
 export declare function setKeychainBackendForTest(b: KeychainBackend | null): KeychainBackend | null;
-/** Check if a keychain/keyring item exists. */
-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;
+/** Check if a keychain/keyring item exists. Never prompts for biometry. */
+export declare function hasKeychainToken(item: string): boolean;
 /**
- * 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).
+ * Retrieve a secret value from the keychain/keyring. Throws if not found.
  *
- * On macOS this uses the signed helper's `get-batch` command so one LAContext
- * can satisfy all protected item reads for the bundle.
+ * 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 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. */
-export declare function deleteKeychainToken(item: string, sync?: boolean): boolean;
+export declare function getKeychainToken(item: string): string;
+/**
+ * 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
+ * lookups — no biometric prompt path on those platforms.
+ */
+export declare function getKeychainTokens(items: string[]): Map<string, string>;
+/** Store or update a secret value in the keychain/keyring. Device-local; biometry-gated on macOS. */
+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;
 /** Enumerate keychain/keyring item names starting with the given prefix. */
 export declare function listKeychainItems(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
+ * (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 declare function migrateKeychainItem(item: string): boolean;
 /** Options controlling how secret refs are resolved. */
 export interface ResolveOptions {
     /** Translate a short keychain ID to a fully namespaced item name. */
@@ -79,8 +105,6 @@ export interface ResolveOptions {
     allowExec?: boolean;
     /** Restrict env: refs to this allowlist. When undefined, any env var may be read. */
     envAllowlist?: string[];
-    /** Read keychain refs from the iCloud-synced keychain backend. */
-    iCloudSync?: boolean;
 }
 /** Resolve a secret ref to its plaintext value using the appropriate provider. */
 export declare function resolveRef(ref: SecretRef, opts?: ResolveOptions): string;

package/dist/lib/secrets/index.js

@@ -1,21 +1,30 @@
 /**
  * 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.`;
@@ -47,9 +56,6 @@ function assertSupportedPlatform() {
 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`;
@@ -61,22 +67,6 @@ export function secretsKeychainItem(bundle, key) {
 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
-// (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;
-}
 let backend = null;
 /** Install a custom keychain backend (test only). Returns the previous backend so callers can restore. */
 export function setKeychainBackendForTest(b) {
@@ -84,104 +74,96 @@ 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: `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;
-    // 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: 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();
-    }
-    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'], {
+        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 (secResult.status === 0) {
-            const token = secResult.stdout?.toString().trim();
+        if (sec.status === 0) {
+            const token = sec.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, {
+    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;
 }
 /**
- * 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).
+ * 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 macOS this uses the signed helper's `get-batch` command so one LAContext
- * can satisfy all protected item reads for the bundle.
+ * On Linux or when a test backend is installed, falls back to individual
+ * lookups — no biometric prompt path on those platforms.
  */
-export function getKeychainTokensBatch(items, sync = false, reason = 'read agents-cli secrets') {
+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));
-            }
-            catch {
-                // Missing or unreadable — skip; the caller reports which key is missing.
+                result.set(item, backend.get(item));
             }
+            catch { /* missing — skip */ }
         }
         return result;
     }
@@ -189,51 +171,58 @@ export function getKeychainTokensBatch(items, sync = false, reason = 'read agent
     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.
+                result.set(item, linuxBackend.get(item));
             }
+            catch { /* missing — skip */ }
         }
         return result;
     }
-    const proc = spawnSync(bin, ['get-batch', os.userInfo().username, '--reason', reason, ...items], {
+    const bin = getKeychainHelperPath();
+    const child = spawnSync(bin, ['get-batch', os.userInfo().username, ...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'));
+    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() ?? '';
+    // Output is a sequence of records, one per service in input order:
+    //   "V <service>\n<value>\n"   (present)
+    //   "M <service>\n"            (missing)
+    // 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');
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (line === '' && i === lines.length - 1)
+            break;
+        if (line.startsWith('V ')) {
+            const service = line.slice(2);
+            const value = lines[i + 1] ?? '';
+            result.set(service, value);
+            i += 2;
+        }
+        else if (line.startsWith('M ')) {
+            i += 1;
+        }
+        else if (line === '') {
+            i += 1;
+        }
+        else {
+            throw new Error(`Malformed get-batch output line: ${JSON.stringify(line)}`);
+        }
     }
     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();
@@ -244,18 +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 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, {
+    const bin = getKeychainHelperPath();
+    const result = spawnSync(bin, ['set', item, os.userInfo().username], {
         input: value,
         stdio: ['pipe', 'pipe', 'pipe'],
     });
@@ -264,29 +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: 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 linuxBackend.delete(item);
+    const bin = getKeychainHelperPath();
     return spawnSync(bin, ['delete', item, os.userInfo().username], {
         stdio: ['ignore', 'pipe', 'pipe'],
     }).status === 0;
@@ -298,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'],
     });
@@ -310,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));
@@ -321,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;