@phnx-labs/agents-cli 1.14.2 → 1.14.3

package/dist/lib/secrets/bundles.js

@@ -1,21 +1,51 @@
 /**
  * Secret bundles -- named sets of keychain-backed environment variables.
  *
- * Each bundle is a YAML file in ~/.agents/secrets/ declaring key names.
- * Values live in the macOS Keychain and are injected into the agent's
- * environment at spawn time via `agents run --secrets <bundle>`.
+ * Bundle metadata (name, description, vars map) is stored in the macOS
+ * Keychain as a JSON blob under `agents-cli.bundles.<name>`. Bundles created
+ * with `--icloud-sync` write the metadata to the iCloud-synced keychain so
+ * the full bundle definition (not just secret values) propagates across
+ * the user's Macs. Nothing about secrets ever lives in plaintext on disk.
+ *
+ * Secret values keep their old layout: one keychain item per key under
+ * `agents-cli.secrets.<bundle>.<key>`, sync-state matching the bundle's
+ * `icloud_sync` flag.
  */
 import * as fs from 'fs';
+import * as os from 'os';
 import * as path from 'path';
 import * as yaml from 'yaml';
-import { getSecretsDir, getUserSecretsDir } from '../state.js';
-import { parseBundleValue, resolveRef, secretsKeychainItem, } from './index.js';
-const BUNDLE_NAME_PATTERN = /^[a-z0-9][a-z0-9-_]{0,48}$/i;
+import { deleteKeychainToken, getKeychainToken, hasKeychainToken, listKeychainItems, parseBundleValue, resolveRef, secretsKeychainItem, setKeychainToken, } from './index.js';
+/** Allowed values for a secret's `type` metadata field. */
+export const SECRET_TYPES = [
+    'api-key',
+    'token',
+    'password',
+    'url',
+    'database-url',
+    'ssh-key',
+    'certificate',
+    'webhook',
+    'note',
+];
+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.';
+export const RESERVED_ENV_NAMES = new Set([
+    'PATH', 'HOME', 'USER', 'USERNAME', 'SHELL', 'PWD', 'OLDPWD',
+    'TERM', 'LANG', 'LC_ALL', 'DISPLAY', 'EDITOR', 'VISUAL',
+    'TMPDIR', 'TMP', 'TEMP', 'LOGNAME', 'UID', 'EUID', 'HOSTNAME',
+]);
+export function bundleToEnvPrefix(name) {
+    return name.replace(/[-\.]/g, '_').toUpperCase();
+}
+export function isReservedEnvName(key) {
+    return RESERVED_ENV_NAMES.has(key);
+}
 /** Validate a bundle name against the allowed pattern. Throws on invalid input. */
 export function validateBundleName(name) {
     if (!BUNDLE_NAME_PATTERN.test(name)) {
-        throw new Error(`Invalid bundle name '${name}'. Use letters, digits, dash, underscore (max 48 chars).`);
+        throw new Error(`Invalid bundle name '${name}'. Use letters, digits, dash, underscore, dot (max 48 chars).`);
     }
 }
 export function validateEnvKey(key) {
@@ -23,37 +53,64 @@ export function validateEnvKey(key) {
         throw new Error(`Invalid environment variable name '${key}'. Must match [A-Za-z_][A-Za-z0-9_]*.`);
     }
 }
-function bundlePath(name) {
-    // Check user dir first (for reads), write to user dir
-    const userPath = path.join(getUserSecretsDir(), `${name}.yml`);
-    if (fs.existsSync(userPath))
-        return userPath;
-    const systemPath = path.join(getSecretsDir(), `${name}.yml`);
-    if (fs.existsSync(systemPath))
-        return systemPath;
-    return userPath; // default write location
+/** Assert that `t` is one of the known SECRET_TYPES. Throws with the allowed list otherwise. */
+export function validateSecretType(t) {
+    if (!SECRET_TYPES.includes(t)) {
+        throw new Error(`Invalid type '${t}'. One of: ${SECRET_TYPES.join(', ')}.`);
+    }
+}
+/**
+ * Validate an `expires` value. Accepts strict 'YYYY-MM-DD' only and rejects
+ * any date <= now. We compare against end-of-day UTC for the chosen date so
+ * "today" is treated as past (per spec).
+ */
+export function validateExpiresFutureDated(iso) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(iso)) {
+        throw new Error(`Invalid --expires '${iso}'. Use YYYY-MM-DD.`);
+    }
+    const target = new Date(iso + 'T23:59:59Z');
+    if (Number.isNaN(target.getTime()))
+        throw new Error(`Invalid --expires date '${iso}'.`);
+    if (target.getTime() <= Date.now()) {
+        throw new Error(`--expires must be future-dated. Got '${iso}'.`);
+    }
+}
+function bundleMetaItem(name) {
+    return BUNDLE_META_PREFIX + name;
 }
 export function bundleExists(name) {
-    return fs.existsSync(bundlePath(name));
+    validateBundleName(name);
+    return hasKeychainToken(bundleMetaItem(name));
 }
 export function readBundle(name) {
     validateBundleName(name);
-    const file = bundlePath(name);
-    if (!fs.existsSync(file)) {
+    let json;
+    try {
+        json = getKeychainToken(bundleMetaItem(name));
+    }
+    catch {
         throw new Error(`Secrets bundle '${name}' not found.`);
     }
-    const raw = fs.readFileSync(file, 'utf-8');
-    const parsed = yaml.parse(raw);
+    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: parsed.name || name,
+        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 (parsed.meta && typeof parsed.meta === 'object') {
+        bundle.meta = parsed.meta;
+    }
     for (const key of Object.keys(bundle.vars)) {
         validateEnvKey(key);
     }
@@ -64,48 +121,59 @@ export function writeBundle(bundle) {
     for (const key of Object.keys(bundle.vars)) {
         validateEnvKey(key);
     }
-    const dir = getUserSecretsDir();
-    fs.mkdirSync(dir, { recursive: true });
-    const body = yaml.stringify({
-        name: bundle.name,
+    // Strip empty/all-undefined meta entries so the JSON stays tidy.
+    let meta;
+    if (bundle.meta) {
+        for (const [key, m] of Object.entries(bundle.meta)) {
+            const cleaned = {};
+            if (m.type)
+                cleaned.type = m.type;
+            if (m.expires)
+                cleaned.expires = m.expires;
+            if (m.note)
+                cleaned.note = m.note;
+            if (Object.keys(cleaned).length > 0) {
+                if (!meta)
+                    meta = {};
+                meta[key] = cleaned;
+            }
+        }
+    }
+    const payload = {
         description: bundle.description,
         allow_exec: bundle.allow_exec ? true : undefined,
         icloud_sync: bundle.icloud_sync ? true : undefined,
         vars: bundle.vars,
-    });
-    const file = bundlePath(bundle.name);
-    const tmp = `${file}.tmp-${process.pid}`;
-    fs.writeFileSync(tmp, body, 'utf-8');
-    fs.renameSync(tmp, file);
+        meta,
+    };
+    const json = JSON.stringify(payload);
+    setKeychainToken(bundleMetaItem(bundle.name), json, Boolean(bundle.icloud_sync));
 }
 export function deleteBundle(name) {
     validateBundleName(name);
-    const file = bundlePath(name);
-    if (!fs.existsSync(file))
-        return false;
-    fs.unlinkSync(file);
-    return true;
+    return deleteKeychainToken(bundleMetaItem(name));
 }
 export function listBundles() {
-    const seen = new Set();
-    const bundles = [];
-    for (const dir of [getUserSecretsDir(), getSecretsDir()]) {
-        if (!fs.existsSync(dir))
-            continue;
-        for (const entry of fs.readdirSync(dir).filter((f) => f.endsWith('.yml') || f.endsWith('.yaml'))) {
-            const name = entry.replace(/\.(yml|yaml)$/, '');
-            if (seen.has(name))
-                continue;
-            seen.add(name);
-            try {
-                bundles.push(readBundle(name));
-            }
-            catch {
-                // Skip malformed bundles; surfaced via `agents secrets view <name>`.
-            }
+    let services;
+    try {
+        services = listKeychainItems(BUNDLE_META_PREFIX);
+    }
+    catch {
+        return [];
+    }
+    const names = services
+        .map((s) => s.slice(BUNDLE_META_PREFIX.length))
+        .filter((n) => BUNDLE_NAME_PATTERN.test(n));
+    const out = [];
+    for (const name of names) {
+        try {
+            out.push(readBundle(name));
+        }
+        catch {
+            // Skip malformed bundles; surfaced via `agents secrets view <name>`.
         }
     }
-    return bundles.sort((a, b) => a.name.localeCompare(b.name));
+    return out.sort((a, b) => a.name.localeCompare(b.name));
 }
 export function describeBundle(bundle) {
     const out = [];
@@ -149,10 +217,49 @@ export function resolveBundleEnv(bundle) {
     }
     return env;
 }
-// Build a keychain ref expression from a bundle+key pair, for storage in YAML.
+// Build a keychain ref expression from a bundle+key pair, for storage in the bundle metadata.
 export function keychainRef(key) {
     return `keychain:${key}`;
 }
+/**
+ * Rotate a keychain-backed secret in `bundle`. Errors if `key` is not present
+ * in the bundle (use `add` to introduce a new key). Preserves existing meta
+ * unless `clearMeta` or a `meta` patch is supplied.
+ */
+export function rotateBundleSecret(bundle, key, opts) {
+    validateBundleName(bundle.name);
+    validateEnvKey(key);
+    if (!(key in bundle.vars)) {
+        throw new Error(`Key '${key}' not in bundle '${bundle.name}'. Use 'agents secrets add' to add a new key.`);
+    }
+    const raw = bundle.vars[key];
+    // We only rotate keychain-backed values. Literals/refs aren't "secrets" in
+    // the same sense — pivot the user back to add/remove.
+    if (typeof raw !== 'string' || !raw.startsWith('keychain:')) {
+        throw new Error(`Key '${key}' in bundle '${bundle.name}' is not keychain-backed; cannot rotate.`);
+    }
+    const shortId = raw.slice('keychain:'.length);
+    const item = secretsKeychainItem(bundle.name, shortId);
+    setKeychainToken(item, opts.newValue, bundle.icloud_sync);
+    if (opts.clearMeta) {
+        if (bundle.meta)
+            delete bundle.meta[key];
+    }
+    else if (opts.meta && Object.keys(opts.meta).length > 0) {
+        if (!bundle.meta)
+            bundle.meta = {};
+        const current = bundle.meta[key] ?? {};
+        const patched = { ...current };
+        if (opts.meta.type !== undefined)
+            patched.type = opts.meta.type;
+        if (opts.meta.expires !== undefined)
+            patched.expires = opts.meta.expires;
+        if (opts.meta.note !== undefined)
+            patched.note = opts.meta.note;
+        bundle.meta[key] = patched;
+    }
+    writeBundle(bundle);
+}
 // Iterate all keychain-backed keys in a bundle for cleanup on rm/unset.
 export function keychainItemsForBundle(bundle) {
     const items = [];
@@ -187,3 +294,64 @@ export function parseDotenv(content) {
     }
     return out;
 }
+/**
+ * One-shot migration: move legacy YAML bundles into the keychain. Scans both
+ * `~/.agents/secrets/` and `~/.agents-system/secrets/` — past versions of the
+ * CLI sometimes wrote bundles into the system repo even though that's never
+ * been a legitimate location. After migration the directories are removed so
+ * the system repo never carries a `secrets/` subdir again.
+ *
+ * Idempotent: re-runs after the dirs are gone are no-ops. Called eagerly at
+ * the top of every `agents secrets` subcommand. Skipped on the latency-
+ * sensitive `agents run` path.
+ */
+export function migrateLegacyBundles() {
+    const home = os.homedir();
+    const dirs = [
+        path.join(home, '.agents', 'secrets'),
+        path.join(home, '.agents-system', 'secrets'),
+    ];
+    let migrated = 0;
+    for (const dir of dirs) {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        const ymls = entries.filter((f) => f.endsWith('.yml') || f.endsWith('.yaml'));
+        for (const entry of ymls) {
+            const file = path.join(dir, entry);
+            const name = entry.replace(/\.(yml|yaml)$/, '');
+            try {
+                validateBundleName(name);
+                const raw = fs.readFileSync(file, 'utf-8');
+                const parsed = yaml.parse(raw);
+                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 : {},
+                };
+                writeBundle(bundle);
+                fs.unlinkSync(file);
+                migrated++;
+            }
+            catch {
+                // Leave malformed YAMLs in place so the user can inspect them.
+            }
+        }
+        try {
+            if (fs.readdirSync(dir).length === 0)
+                fs.rmdirSync(dir);
+        }
+        catch { /* not empty or already gone */ }
+    }
+    if (migrated > 0) {
+        console.log(`Migrated ${migrated} legacy bundle${migrated === 1 ? '' : 's'} into keychain.`);
+    }
+}

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

@@ -1,9 +1,11 @@
 /**
  * macOS Keychain integration for secure credential storage.
  *
- * Calls a compiled Swift helper (keychain-helper.swift) to store and retrieve
- * API keys and tokens via the Security framework, with kSecAttrSynchronizable
- * set so iCloud Keychain syncs them across the user's Macs.
+ * All reads/writes go through a signed Swift helper (keychain-helper.swift)
+ * compiled into AgentsKeychain.app. 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.
  */
 /** Supported secret resolution backends. */
 export type SecretProvider = 'keychain' | 'env' | 'file' | 'exec';
@@ -13,14 +15,14 @@ export interface SecretRef {
     value: string;
 }
 /**
- * A bundle YAML value: either a string (literal or provider-prefixed ref) or
+ * A bundle value: either a string (literal or provider-prefixed ref) or
  * an object `{value: string}` used to escape a literal that would otherwise
  * be parsed as a ref (e.g. a URL that happens to start with 'env:').
  */
 export type BundleValue = string | {
     value: string;
 };
-/** Parse a bundle YAML value into either a literal string or a typed secret ref. */
+/** Parse a bundle value into either a literal string or a typed secret ref. */
 export declare function parseBundleValue(raw: BundleValue): {
     literal: string;
 } | {
@@ -32,6 +34,21 @@ export declare function serializeRef(ref: SecretRef): string;
 export declare function profileKeychainItem(provider: string): string;
 /** Build the keychain item name for a secrets-bundle key. */
 export declare function secretsKeychainItem(bundle: string, key: string): string;
+/**
+ * Test seam: lets bundle storage tests swap the keychain backend for an
+ * in-memory map without touching the user's real keychain. Mocking is
+ * justified here because the alternative (touching real keychain in unit
+ * 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;
+    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 item exists (macOS only). */
 export declare function hasKeychainToken(item: string, sync?: boolean): boolean;
 /** Retrieve a secret value from the macOS Keychain. Throws if not found. */
@@ -40,6 +57,8 @@ export declare function getKeychainToken(item: string, sync?: boolean): string;
 export declare function setKeychainToken(item: string, value: string, sync?: boolean): void;
 /** Delete a keychain item. Returns true if it existed. */
 export declare function deleteKeychainToken(item: string, sync?: boolean): boolean;
+/** Enumerate keychain item service names whose name starts with the given prefix. */
+export declare function listKeychainItems(prefix: string): string[];
 /** Options controlling how secret refs are resolved. */
 export interface ResolveOptions {
     /** Translate a short keychain ID to a fully namespaced item name. */

package/dist/lib/secrets/index.js

@@ -1,9 +1,11 @@
 /**
  * macOS Keychain integration for secure credential storage.
  *
- * Calls a compiled Swift helper (keychain-helper.swift) to store and retrieve
- * API keys and tokens via the Security framework, with kSecAttrSynchronizable
- * set so iCloud Keychain syncs them across the user's Macs.
+ * All reads/writes go through a signed Swift helper (keychain-helper.swift)
+ * compiled into AgentsKeychain.app. 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.
  */
 import { fileURLToPath } from 'url';
 import { execFileSync, spawnSync } from 'child_process';
@@ -12,7 +14,7 @@ import * as os from 'os';
 import * as path from 'path';
 const SERVICE_PREFIX = 'agents-cli';
 const REF_PATTERN = /^(keychain|env|file|exec):(.+)$/s;
-/** Parse a bundle YAML value into either a literal string or a typed secret ref. */
+/** Parse a bundle value into either a literal string or a typed secret ref. */
 export function parseBundleValue(raw) {
     if (typeof raw === 'object' && raw !== null && typeof raw.value === 'string') {
         return { literal: raw.value };
@@ -53,58 +55,64 @@ function ensureKeychainHelper() {
     const here = path.dirname(fileURLToPath(import.meta.url));
     const binPath = path.join(here, 'AgentsKeychain.app', 'Contents', 'MacOS', 'AgentsKeychain');
     if (!fs.existsSync(binPath)) {
-        throw new Error(`iCloud Keychain helper missing at ${binPath}. ` +
-            'This npm package was built without the signed helper bundle. ' +
-            'Reinstall agents-cli, or create the bundle without --icloud-sync to use device-local storage.');
+        throw new Error(`Keychain helper missing at ${binPath}. ` +
+            'This npm package was built without the signed helper bundle. Reinstall agents-cli.');
     }
     return binPath;
 }
-// iCloud Keychain sync is opt-in per bundle. When sync=true we route through
-// the Swift helper (kSecAttrSynchronizable=true). When sync is false/undefined
-// we use /usr/bin/security, which is always present on macOS — so a user who
-// never opts in to iCloud sync never needs Xcode Command Line Tools.
+let backend = null;
+/** Install a custom keychain backend (test only). Returns the previous backend so callers can restore. */
+export function setKeychainBackendForTest(b) {
+    const prev = backend;
+    backend = b;
+    return prev;
+}
+// Backend routing: non-sync items go through /usr/bin/security so they share
+// an ACL identity with items created by previous CLI versions (no prompts on
+// existing data). 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 item exists (macOS only). */
 export function hasKeychainToken(item, sync = false) {
+    if (backend)
+        return backend.has(item, sync);
     assertMacOS();
-    if (sync) {
-        const bin = ensureKeychainHelper();
-        return spawnSync(bin, ['has', item, os.userInfo().username], {
-            stdio: ['ignore', 'pipe', 'pipe'],
-        }).status === 0;
-    }
-    return spawnSync('security', ['find-generic-password', '-a', os.userInfo().username, '-s', item, '-w'], {
+    // 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 spawnSync(bin, ['has', item, os.userInfo().username], {
         stdio: ['ignore', 'pipe', 'pipe'],
     }).status === 0;
 }
 /** Retrieve a secret value from the macOS Keychain. Throws if not found. */
 export function getKeychainToken(item, sync = false) {
+    if (backend)
+        return backend.get(item, sync);
     assertMacOS();
-    if (sync) {
-        const bin = ensureKeychainHelper();
-        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 !== 0) {
-            const msg = result.stderr?.toString().trim();
-            throw new Error(msg || `Failed to read keychain item '${item}'.`);
-        }
-        const token = result.stdout?.toString().trim();
-        if (!token)
-            throw new Error(`Keychain item '${item}' exists but is empty.`);
-        return token;
+    // 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;
     }
-    const result = spawnSync('security', ['find-generic-password', '-a', os.userInfo().username, '-s', item, '-w'], {
+    // Fallback: binary searches both synced and non-synced via kSecAttrSynchronizableAny
+    const bin = ensureKeychainHelper();
+    const result = spawnSync(bin, ['get', item, os.userInfo().username], {
         stdio: ['ignore', 'pipe', 'pipe'],
     });
-    if (result.status === 44)
+    if (result.status === 1)
         throw new Error(`Keychain item '${item}' not found.`);
     if (result.status !== 0) {
-        const stderr = result.stderr?.toString() || '';
-        if (/could not be found/i.test(stderr))
-            throw new Error(`Keychain item '${item}' not found.`);
-        throw new Error(`Failed to read keychain item '${item}': ${stderr.trim() || `exit ${result.status}`}`);
+        const msg = result.stderr?.toString().trim();
+        throw new Error(msg || `Failed to read keychain item '${item}'.`);
     }
     const token = result.stdout?.toString().trim();
     if (!token)
@@ -113,6 +121,10 @@ export function getKeychainToken(item, sync = false) {
 }
 /** Store or update a secret value in the macOS Keychain. iCloud-synced when sync=true. */
 export function setKeychainToken(item, value, sync = false) {
+    if (backend) {
+        backend.set(item, value, sync);
+        return;
+    }
     assertMacOS();
     if (!value || !value.trim())
         throw new Error('Secret value is empty.');
@@ -130,7 +142,7 @@ export function setKeychainToken(item, value, sync = false) {
         }
         return;
     }
-    // The `security -i` interactive form keeps the value out of argv (and `ps`).
+    // `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)} -U\n`;
     const result = spawnSync('security', ['-i'], {
@@ -143,6 +155,8 @@ export function setKeychainToken(item, value, sync = false) {
 }
 /** Delete a keychain item. Returns true if it existed. */
 export function deleteKeychainToken(item, sync = false) {
+    if (backend)
+        return backend.delete(item, sync);
     assertMacOS();
     if (sync) {
         const bin = ensureKeychainHelper();
@@ -154,10 +168,25 @@ export function deleteKeychainToken(item, sync = false) {
         stdio: ['ignore', 'pipe', 'pipe'],
     }).status === 0;
 }
-// Quote a value for `security -i`'s shell-like tokenizer so it stays out of argv.
 function quoteForSecurityCli(s) {
     return '"' + s.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
 }
+/** Enumerate keychain item service names whose name starts with the given prefix. */
+export function listKeychainItems(prefix) {
+    if (backend)
+        return backend.list(prefix);
+    assertMacOS();
+    const bin = ensureKeychainHelper();
+    const result = spawnSync(bin, ['list', prefix], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (result.status !== 0) {
+        const msg = result.stderr?.toString().trim();
+        throw new Error(msg || `Failed to enumerate keychain items with prefix '${prefix}'.`);
+    }
+    const out = result.stdout?.toString() || '';
+    return out.split('\n').map((s) => s.trim()).filter(Boolean);
+}
 function expandHome(p) {
     if (p.startsWith('~/') || p === '~') {
         return path.join(os.homedir(), p.slice(1));

package/dist/lib/session/active.js

@@ -2,12 +2,12 @@
  * Active-session detection across every context an agent can run in:
  *
  *   - `terminal` — agents launched from VS Code / Cursor / Codium via the
- *     agents-cli extension. Published to `~/.agents-system/runtime/live-terminals.json`
+ *     agents-cli extension. Published to `~/.agents/runtime/live-terminals.json`
  *     with PID + session UUID per entry.
  *   - `teams`    — agents spawned by `agents teams add`, tracked in
- *     `~/.agents-system/teams/agents/<id>/meta.json` with a PID the manager polls.
+ *     `~/.agents/teams/agents/<id>/meta.json` with a PID the manager polls.
  *   - `cloud`    — dispatched to Rush / Codex Cloud / Factory, tracked in
- *     the SQLite cache at `~/.agents-system/cloud/tasks.db`.
+ *     the SQLite cache at `~/.agents/cloud/tasks.db`.
  *   - `headless` — bare `claude` / `codex` / `gemini` / `cursor-agent` /
  *     `opencode` processes that don't belong to any of the above. Detected
  *     by `ps` minus the PIDs we've already attributed.
@@ -23,10 +23,10 @@ import { execFile } from 'child_process';
 import { promisify } from 'util';
 import { listActiveTasks } from '../cloud/store.js';
 import { AgentManager } from '../teams/agents.js';
-import { getAgentsDir } from '../state.js';
+import { getUserAgentsDir } from '../state.js';
 const execFileAsync = promisify(execFile);
 const HOME = os.homedir();
-const LIVE_TERMINALS_FILE = path.join(getAgentsDir(), 'runtime', 'live-terminals.json');
+const LIVE_TERMINALS_FILE = path.join(getUserAgentsDir(), 'runtime', 'live-terminals.json');
 /**
  * A process is classified `running` if its session file was touched in the
  * last 2 minutes. Every Claude/Codex tool-call appends an event, so a

package/dist/lib/session/db.js

@@ -9,8 +9,8 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import Database from '../sqlite.js';
-import { getAgentsDir } from '../state.js';
-const SESSIONS_DIR = path.join(getAgentsDir(), 'sessions');
+import { getUserAgentsDir } from '../state.js';
+const SESSIONS_DIR = path.join(getUserAgentsDir(), 'sessions');
 const DB_PATH = path.join(SESSIONS_DIR, 'sessions.db');
 /** Current schema version; bumped when migrations are added. */
 const SCHEMA_VERSION = 5;
@@ -18,7 +18,7 @@ const SCHEMA_VERSION = 5;
  * Canonicalize a file path for use as a scan_ledger key. The same physical
  * session file is reachable via multiple aliases — `~/.claude/projects/x.jsonl`
  * (when `~/.claude` is a symlink to a versioned home) and
- * `~/.agents-system/versions/claude/<v>/home/.claude/projects/x.jsonl`. Keying the
+ * `~/.agents/versions/claude/<v>/home/.claude/projects/x.jsonl`. Keying the
  * ledger by the raw path means switching between these aliases (e.g. via
  * `agents use`) misses the cache and forces a full re-parse. Realpath collapses
  * all aliases to one stable key.
@@ -213,7 +213,7 @@ export function getScanStampsForPaths(filePaths) {
         return result;
     const db = getDB();
     // Multiple input paths can resolve to the same canonical key (e.g. the same
-    // session JSONL reachable via `~/.claude/...` and `~/.agents-system/versions/...`).
+    // session JSONL reachable via `~/.claude/...` and `~/.agents/versions/...`).
     // We query DB by canonical key, then fan results back out to every original
     // alias so callers can `.get(filePath)` with the path they passed in.
     const canonicalToOriginals = new Map();