clementine-agent 1.1.2 → 1.1.4

package/dist/cli/index.js

@@ -1148,6 +1148,139 @@ async function cmdConfigMigrateToKeychain(opts) {
     console.log(`  ${DIM}choose Always Allow to make the prompt permanent.${RESET}`);
     console.log();
 }
+// ── Config migrate-from-keychain (inverse of migrate-to-keychain) ───
+async function cmdConfigMigrateFromKeychain(opts) {
+    const { planReverseMigration, applyReverseMigration } = await import('../config/migrate-from-keychain.js');
+    const DIM = '\x1b[0;90m';
+    const BOLD = '\x1b[1m';
+    const GREEN = '\x1b[0;32m';
+    const YELLOW = '\x1b[0;33m';
+    const RED = '\x1b[0;31m';
+    const CYAN = '\x1b[0;36m';
+    const RESET = '\x1b[0m';
+    const only = opts.key
+        ? opts.key.flatMap(k => k.split(',').map(s => s.trim()).filter(Boolean))
+        : undefined;
+    const plan = planReverseMigration(BASE_DIR, only ? { only } : {});
+    console.log();
+    console.log(`  ${BOLD}.env path:${RESET}  ${plan.envPath}`);
+    console.log();
+    const groups = {};
+    for (const c of plan.candidates)
+        (groups[c.status] ??= []).push(c);
+    const renderGroup = (label, color, items, showRef = false) => {
+        if (!items || items.length === 0)
+            return;
+        console.log(`  ${color}${label}${RESET} ${DIM}(${items.length})${RESET}`);
+        for (const c of items) {
+            const refTag = showRef && c.ref ? ` ${DIM}${c.ref}${RESET}` : '';
+            console.log(`    ${c.key}${refTag}`);
+        }
+        console.log();
+    };
+    renderGroup('Will migrate from keychain → .env', CYAN, groups.migrated);
+    renderGroup('Sensitive — left in keychain (correct)', DIM, groups['sensitive-skipped']);
+    renderGroup('Unresolvable refs (keychain entry missing)', RED, groups.unresolvable, true);
+    if (plan.toMigrate.length === 0) {
+        console.log(`  ${GREEN}Nothing to migrate.${RESET}`);
+        if (plan.unresolvable.length > 0) {
+            console.log(`  ${YELLOW}${plan.unresolvable.length} unresolvable ref(s) above — fix or delete by hand.${RESET}`);
+        }
+        console.log();
+        return;
+    }
+    if (opts.dryRun) {
+        console.log(`  ${YELLOW}Dry run — no changes written.${RESET}`);
+        console.log();
+        return;
+    }
+    console.log(`  ${BOLD}Applying...${RESET}`);
+    let result;
+    try {
+        result = applyReverseMigration(BASE_DIR, only ? { only } : {});
+    }
+    catch (err) {
+        console.error(`  ${RED}Failed:${RESET} ${err.message}`);
+        process.exit(1);
+    }
+    if (result.failed.length > 0) {
+        console.log(`  ${RED}Some keychain reads failed — .env was NOT modified:${RESET}`);
+        for (const f of result.failed)
+            console.log(`    ${RED}✗${RESET} ${f.key}: ${f.error}`);
+        console.log();
+        process.exit(1);
+    }
+    for (const key of result.migrated) {
+        console.log(`    ${GREEN}✓${RESET} ${key} ${DIM}→ .env (keychain entry deleted)${RESET}`);
+    }
+    console.log();
+    console.log(`  ${GREEN}Migrated ${result.migrated.length} key${result.migrated.length === 1 ? '' : 's'} out of keychain.${RESET}`);
+    console.log();
+}
+// ── Config keychain-fix-acl ─────────────────────────────────────────
+async function cmdConfigKeychainFixAcl(opts) {
+    const { listClementineKeychainEntries, fixAllClementineEntries } = await import('../config/keychain-fix-acl.js');
+    const DIM = '\x1b[0;90m';
+    const BOLD = '\x1b[1m';
+    const GREEN = '\x1b[0;32m';
+    const YELLOW = '\x1b[0;33m';
+    const RED = '\x1b[0;31m';
+    const RESET = '\x1b[0m';
+    const entries = listClementineKeychainEntries();
+    const ours = entries.filter(e => e.isClementine);
+    const foreign = entries.filter(e => !e.isClementine);
+    console.log();
+    console.log(`  ${BOLD}Found ${entries.length} entr${entries.length === 1 ? 'y' : 'ies'} under clementine* services.${RESET}`);
+    console.log(`  ${DIM}Will fix ${ours.length}; will skip ${foreign.length} (look like other apps).${RESET}`);
+    console.log();
+    for (const e of entries) {
+        const tag = e.isClementine ? `${GREEN}fix${RESET}` : `${DIM}skip${RESET}`;
+        console.log(`    [${tag}] ${e.service}/${e.account}`);
+    }
+    console.log();
+    if (ours.length === 0) {
+        console.log(`  ${GREEN}Nothing Clementine-shaped to fix.${RESET}`);
+        console.log();
+        return;
+    }
+    if (opts.list) {
+        console.log(`  ${DIM}--list mode — no changes made. Drop the flag to apply.${RESET}`);
+        console.log();
+        return;
+    }
+    console.log(`  ${BOLD}Fixing ACLs...${RESET}`);
+    console.log(`  ${DIM}macOS may ask for your login keychain password (the system prompt — it DOES appear).${RESET}`);
+    console.log(`  ${DIM}One prompt per entry; type Mac password + Enter for each.${RESET}`);
+    console.log();
+    const results = fixAllClementineEntries();
+    let okCount = 0;
+    let failCount = 0;
+    let skipCount = 0;
+    for (const r of results) {
+        if (r.status === 'fixed') {
+            console.log(`    ${GREEN}✓${RESET} ${r.service}/${r.account}`);
+            okCount++;
+        }
+        else if (r.status === 'skipped-foreign') {
+            skipCount++;
+        }
+        else {
+            console.log(`    ${RED}✗${RESET} ${r.service}/${r.account} ${DIM}— ${r.error}${RESET}`);
+            failCount++;
+        }
+    }
+    console.log();
+    if (failCount === 0) {
+        console.log(`  ${GREEN}All ${okCount} Clementine entries fixed.${RESET} ${DIM}Future reads via the security CLI succeed silently.${RESET}`);
+        if (skipCount > 0)
+            console.log(`  ${DIM}(${skipCount} foreign entr${skipCount === 1 ? 'y' : 'ies'} left untouched.)${RESET}`);
+    }
+    else {
+        console.log(`  ${YELLOW}${okCount} fixed, ${failCount} failed${skipCount > 0 ? `, ${skipCount} foreign-skipped` : ''}.${RESET}`);
+        console.log(`  ${DIM}Failed entries can be fixed manually in Keychain Access.app.${RESET}`);
+    }
+    console.log();
+}
 // ── Advisor commands ────────────────────────────────────────────────
 const ADVISOR_MODES = ['off', 'shadow', 'primary'];
 function readAdvisorMode() {
@@ -1802,6 +1935,21 @@ configCmd
     .action(async (opts) => {
     await cmdConfigMigrateToKeychain(opts);
 });
+configCmd
+    .command('migrate-from-keychain')
+    .description('Pull non-credential values OUT of keychain back to plaintext .env (only API keys belong in keychain)')
+    .option('--dry-run', 'Show what would migrate without writing anything')
+    .option('-k, --key <name...>', 'Limit to specific key(s); repeat or comma-separate for multiple')
+    .action(async (opts) => {
+    await cmdConfigMigrateFromKeychain(opts);
+});
+configCmd
+    .command('keychain-fix-acl')
+    .description('One-shot fix for clementine-agent keychain entries that prompt on every read (one master prompt then no more)')
+    .option('--list', 'List entries without changing anything')
+    .action(async (opts) => {
+    await cmdConfigKeychainFixAcl(opts);
+});
 configCmd
     .command('edit')
     .description('Open .env in your editor')

package/dist/config/effective-config.js

@@ -64,6 +64,8 @@ const refCache = new Map();
 function shellEscape(s) {
     return `'${s.replace(/'/g, "'\\''")}'`;
 }
+/** Hard cap per shell call — see config.ts for rationale. */
+const KEYCHAIN_TIMEOUT_MS = Math.max(500, parseInt(process.env.CLEMENTINE_KEYCHAIN_TIMEOUT_MS ?? '3000', 10) || 3000);
 function resolveRef(stub) {
     if (refCache.has(stub)) {
         const v = refCache.get(stub);
@@ -71,7 +73,7 @@ function resolveRef(stub) {
     }
     const account = stub.slice(KEYCHAIN_REF_PREFIX.length);
     try {
-        const result = execSync(`security find-generic-password -s clementine-agent -a ${shellEscape(account)} -w`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+        const result = execSync(`security find-generic-password -s clementine-agent -a ${shellEscape(account)} -w`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], timeout: KEYCHAIN_TIMEOUT_MS }).trim();
         refCache.set(stub, result || null);
         return result || undefined;
     }

package/dist/config/keychain-fix-acl.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Bulk-fix the ACL on existing clementine-agent keychain entries.
+ *
+ * Why this exists: keychain entries created before commit 88cfd99 used
+ * `add-generic-password -T ''` which means NO apps are pre-approved to
+ * read. Every Clementine read triggered a per-app dialog that often
+ * didn't appear (hidden behind windows, dismissed silently, queued).
+ *
+ * The new keychain.set uses `-T /usr/bin/security` so future entries
+ * don't have this problem. For existing entries this module runs
+ *
+ *   security set-generic-password-partition-list \
+ *     -s clementine-agent -a <account> -S apple-tool:,apple:
+ *
+ * which adds Apple-signed tools (including /usr/bin/security itself)
+ * to the partition allowlist. Result: future reads via security
+ * succeed silently, no per-app dialog.
+ *
+ * The user is prompted for their LOGIN keychain password once per call
+ * (the macOS system prompt — the one that DOES reliably appear). After
+ * approving, all entries become readable without further prompts.
+ */
+/**
+ * Both keychain service names the codebase has used over time:
+ * - "clementine-agent" — used by src/secrets/keychain.ts (env_set / migrate-to-keychain)
+ * - "clementine"       — getSecret's default fallback when no explicit service
+ *                        passed (src/config.ts: ASSISTANT_NAME.toLowerCase()).
+ *                        Holds older per-agent and handoff entries.
+ */
+declare const SERVICES: readonly ["clementine-agent", "clementine"];
+type Service = typeof SERVICES[number];
+export interface KeychainEntry {
+    service: Service;
+    account: string;
+    /** True when isClementineAccount returned true; only these get fixed. */
+    isClementine: boolean;
+}
+export interface AclFixResult {
+    service: Service;
+    account: string;
+    status: 'fixed' | 'failed' | 'skipped-foreign';
+    error?: string;
+}
+/**
+ * Enumerate every keychain entry under any service in SERVICES. Uses the
+ * dump-keychain grep approach since `security` doesn't expose a clean
+ * list-by-service. Read-only, no prompts.
+ *
+ * For the legacy "clementine" service we set `isClementine: false` on any
+ * entry that doesn't match our naming patterns — those get reported but
+ * never touched (could be other apps that coincidentally chose that name).
+ */
+export declare function listClementineKeychainEntries(): KeychainEntry[];
+export declare function fixAcl(service: Service, account: string): AclFixResult;
+/**
+ * Plan + apply: enumerate entries, fix each Clementine-shaped one in turn.
+ * Foreign entries (other apps under the legacy "clementine" service) get
+ * reported with status='skipped-foreign' and never touched.
+ */
+export declare function fixAllClementineEntries(): AclFixResult[];
+export {};
+//# sourceMappingURL=keychain-fix-acl.d.ts.map

package/dist/config/keychain-fix-acl.js

@@ -0,0 +1,201 @@
+/**
+ * Bulk-fix the ACL on existing clementine-agent keychain entries.
+ *
+ * Why this exists: keychain entries created before commit 88cfd99 used
+ * `add-generic-password -T ''` which means NO apps are pre-approved to
+ * read. Every Clementine read triggered a per-app dialog that often
+ * didn't appear (hidden behind windows, dismissed silently, queued).
+ *
+ * The new keychain.set uses `-T /usr/bin/security` so future entries
+ * don't have this problem. For existing entries this module runs
+ *
+ *   security set-generic-password-partition-list \
+ *     -s clementine-agent -a <account> -S apple-tool:,apple:
+ *
+ * which adds Apple-signed tools (including /usr/bin/security itself)
+ * to the partition allowlist. Result: future reads via security
+ * succeed silently, no per-app dialog.
+ *
+ * The user is prompted for their LOGIN keychain password once per call
+ * (the macOS system prompt — the one that DOES reliably appear). After
+ * approving, all entries become readable without further prompts.
+ */
+import { execSync, spawnSync } from 'node:child_process';
+/**
+ * Both keychain service names the codebase has used over time:
+ * - "clementine-agent" — used by src/secrets/keychain.ts (env_set / migrate-to-keychain)
+ * - "clementine"       — getSecret's default fallback when no explicit service
+ *                        passed (src/config.ts: ASSISTANT_NAME.toLowerCase()).
+ *                        Holds older per-agent and handoff entries.
+ */
+const SERVICES = ['clementine-agent', 'clementine'];
+/**
+ * Under the legacy "clementine" service, some non-Clementine apps
+ * coincidentally store entries (e.g., macOS "Local Crypto Key Data"
+ * with a UUID prefix). We refuse to touch those — only entries that
+ * match our naming conventions get the ACL update.
+ */
+function isClementineAccount(service, account) {
+    if (service === 'clementine-agent')
+        return true; // we own this whole service
+    // For the legacy "clementine" service, conservatively only touch entries
+    // that look like things we set: per-agent secrets (AGENT_*),
+    // handoff-decryption-key-*, oauth-tokens, env-var names (UPPER_SNAKE),
+    // anything starting with "clementine-".
+    if (account.startsWith('AGENT_'))
+        return true;
+    if (account.startsWith('handoff-'))
+        return true;
+    if (account === 'oauth-tokens')
+        return true;
+    if (account.startsWith('clementine-'))
+        return true;
+    if (/^[A-Z][A-Z0-9_]*$/.test(account))
+        return true;
+    return false;
+}
+/**
+ * Enumerate every keychain entry under any service in SERVICES. Uses the
+ * dump-keychain grep approach since `security` doesn't expose a clean
+ * list-by-service. Read-only, no prompts.
+ *
+ * For the legacy "clementine" service we set `isClementine: false` on any
+ * entry that doesn't match our naming patterns — those get reported but
+ * never touched (could be other apps that coincidentally chose that name).
+ */
+export function listClementineKeychainEntries() {
+    let raw;
+    try {
+        raw = execSync('/usr/bin/security dump-keychain 2>/dev/null', {
+            encoding: 'utf-8',
+            timeout: 10_000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            maxBuffer: 32 * 1024 * 1024,
+        });
+    }
+    catch {
+        return [];
+    }
+    // dump-keychain emits one record per item. Within a record, fields appear
+    // in arbitrary order — `acct` often comes BEFORE `svce`. So we can't track
+    // "last-seen svce" line-by-line; we have to split into per-record blocks
+    // and extract both fields from each block.
+    //
+    // Each record starts with `keychain: "/path/to/keychain"` followed by the
+    // `version`, `class`, `attributes:` lines and the field blobs. The next
+    // record begins at the next `^keychain: ` line.
+    const entries = [];
+    const seen = new Set();
+    // Split by record boundary. Use a positive lookahead so the delimiter stays
+    // at the start of each chunk.
+    const blocks = raw.split(/\n(?=keychain: ")/);
+    for (const block of blocks) {
+        const svceMatch = block.match(/"svce"<blob>="([^"]+)"/);
+        const acctMatch = block.match(/"acct"<blob>="([^"]+)"/);
+        if (!svceMatch || !acctMatch)
+            continue;
+        const svc = svceMatch[1];
+        const account = acctMatch[1];
+        if (!SERVICES.includes(svc))
+            continue;
+        const service = svc;
+        const dedupeKey = `${service}\x00${account}`;
+        if (seen.has(dedupeKey))
+            continue;
+        seen.add(dedupeKey);
+        entries.push({
+            service,
+            account,
+            isClementine: isClementineAccount(service, account),
+        });
+    }
+    // Stable sort: service first, then account
+    entries.sort((a, b) => a.service === b.service ? a.account.localeCompare(b.account) : a.service.localeCompare(b.service));
+    return entries;
+}
+/**
+ * Add `apple-tool:,apple:` to the partition list of a given account.
+ *
+ * `security set-generic-password-partition-list` prompts on the controlling
+ * terminal — `password to unlock default:` — for the user's login keychain
+ * password. We must inherit stdio so the child can read from the parent's
+ * TTY; piped stdio causes security to consume an empty line and fail with
+ * "exit code null" / "wrong password."
+ *
+ * That means this function only works when called from an interactive shell.
+ * Callers in non-TTY contexts should fall back to instructing the user to
+ * run `clementine config keychain-fix-acl` from their own terminal.
+ */
+/**
+ * Discover which keychain a (service, account) pair lives in. Returns the
+ * path or null if find-generic-password can't locate it (in which case we
+ * skip — the entry isn't reachable via standard search anyway).
+ */
+function locateKeychain(service, account) {
+    const probe = spawnSync('/usr/bin/security', [
+        'find-generic-password',
+        '-s', service,
+        '-a', account,
+    ], {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        timeout: 5000,
+        encoding: 'utf-8',
+    });
+    if (probe.status !== 0)
+        return null;
+    // First line is `keychain: "/path/to/keychain"` — extract.
+    const first = (probe.stdout || '').split('\n')[0] ?? '';
+    const m = first.match(/^keychain:\s+"([^"]+)"/);
+    return m ? m[1] : null;
+}
+export function fixAcl(service, account) {
+    const keychainPath = locateKeychain(service, account);
+    if (!keychainPath) {
+        return {
+            service,
+            account,
+            status: 'failed',
+            error: 'item not findable via standard search (may be in iCloud or a non-default keychain) — leaving alone',
+        };
+    }
+    // Pass the keychain path as the trailing positional arg so partition-list
+    // doesn't search the wrong store.
+    const args = [
+        'set-generic-password-partition-list',
+        '-s', service,
+        '-a', account,
+        '-S', 'apple-tool:,apple:',
+        keychainPath,
+    ];
+    const result = spawnSync('/usr/bin/security', args, {
+        stdio: 'inherit',
+        timeout: 120_000,
+    });
+    if (result.status === 0) {
+        return { service, account, status: 'fixed' };
+    }
+    return {
+        service,
+        account,
+        status: 'failed',
+        error: result.error?.message ?? `exit code ${result.status}`,
+    };
+}
+/**
+ * Plan + apply: enumerate entries, fix each Clementine-shaped one in turn.
+ * Foreign entries (other apps under the legacy "clementine" service) get
+ * reported with status='skipped-foreign' and never touched.
+ */
+export function fixAllClementineEntries() {
+    const entries = listClementineKeychainEntries();
+    const results = [];
+    for (const entry of entries) {
+        if (!entry.isClementine) {
+            results.push({ service: entry.service, account: entry.account, status: 'skipped-foreign' });
+            continue;
+        }
+        results.push(fixAcl(entry.service, entry.account));
+    }
+    return results;
+}
+//# sourceMappingURL=keychain-fix-acl.js.map

package/dist/config/migrate-from-keychain.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Inverse of migrate-keychain.ts: pulls non-credential values OUT of the
+ * macOS keychain and back into plaintext .env entries.
+ *
+ * Why this exists: an earlier env_set bug routed every value to keychain
+ * regardless of whether the key looked like a credential, producing stale
+ * keychain entries for things like TASK_BUDGET_HEARTBEAT (a token-count
+ * config knob, not a secret). Each one costs the user a keychain prompt
+ * for no benefit. This module reverses that mistake — and the user-rule
+ * "only actual API keys belong in keychain" stays enforced going forward
+ * by the env_set classifier fix in 897bb97.
+ *
+ * For each line in .env that holds a `keychain:` ref AND whose key does
+ * NOT match the sensitivity classifier:
+ *   1. Resolve via `security find-generic-password`
+ *   2. Replace the .env line with `KEY=<plaintext value>`
+ *   3. Delete the keychain entry
+ *
+ * Atomic: phase-1 reads + writes succeed in a temp file before the original
+ * .env is replaced via rename. Keychain deletes happen last, so a partial
+ * failure leaves the keychain entry intact (no data loss).
+ *
+ * Idempotent + opt-in: lines whose key IS credential-shaped pass through
+ * untouched even when stored as a keychain ref — we don't undo legitimate
+ * keychain storage. --key filter for surgical migrations.
+ */
+export type ReverseMigrationStatus = 'migrated' | 'sensitive-skipped' | 'not-keychain' | 'unresolvable' | 'skipped';
+export interface ReverseMigrationCandidate {
+    key: string;
+    status: ReverseMigrationStatus;
+    /** The keychain stub itself (always safe to log — it's just an account name). */
+    ref?: string;
+}
+export interface ReverseMigrationPlan {
+    envPath: string;
+    candidates: ReverseMigrationCandidate[];
+    /** Keys this run would migrate out of keychain. */
+    toMigrate: string[];
+    /** Refs that look bad — surfaced separately so doctor can flag them. */
+    unresolvable: string[];
+}
+export interface ReverseMigrationResult {
+    envPath: string;
+    migrated: string[];
+    failed: Array<{
+        key: string;
+        error: string;
+    }>;
+}
+/**
+ * Pure read + classify pass — no .env writes, no keychain deletes, but
+ * DOES make read-only `security find-generic-password` calls to detect
+ * unresolvable refs (and to verify resolvable ones won't fail later).
+ */
+export declare function planReverseMigration(baseDir: string, opts?: {
+    only?: string[];
+}): ReverseMigrationPlan;
+/**
+ * Apply the migration. Two phases:
+ *   1. Rewrite .env in a temp file, swapping each migrated ref for plaintext.
+ *      If anything throws, the original .env is untouched.
+ *   2. Atomically rename the temp file over .env.
+ *   3. Delete each migrated key's keychain entry. Best-effort — failure to
+ *      delete is logged but doesn't roll back the .env update (the value
+ *      is now safely in .env regardless).
+ */
+export declare function applyReverseMigration(baseDir: string, opts?: {
+    only?: string[];
+}): ReverseMigrationResult;
+//# sourceMappingURL=migrate-from-keychain.d.ts.map

package/dist/config/migrate-from-keychain.js

@@ -0,0 +1,173 @@
+/**
+ * Inverse of migrate-keychain.ts: pulls non-credential values OUT of the
+ * macOS keychain and back into plaintext .env entries.
+ *
+ * Why this exists: an earlier env_set bug routed every value to keychain
+ * regardless of whether the key looked like a credential, producing stale
+ * keychain entries for things like TASK_BUDGET_HEARTBEAT (a token-count
+ * config knob, not a secret). Each one costs the user a keychain prompt
+ * for no benefit. This module reverses that mistake — and the user-rule
+ * "only actual API keys belong in keychain" stays enforced going forward
+ * by the env_set classifier fix in 897bb97.
+ *
+ * For each line in .env that holds a `keychain:` ref AND whose key does
+ * NOT match the sensitivity classifier:
+ *   1. Resolve via `security find-generic-password`
+ *   2. Replace the .env line with `KEY=<plaintext value>`
+ *   3. Delete the keychain entry
+ *
+ * Atomic: phase-1 reads + writes succeed in a temp file before the original
+ * .env is replaced via rename. Keychain deletes happen last, so a partial
+ * failure leaves the keychain entry intact (no data loss).
+ *
+ * Idempotent + opt-in: lines whose key IS credential-shaped pass through
+ * untouched even when stored as a keychain ref — we don't undo legitimate
+ * keychain storage. --key filter for surgical migrations.
+ */
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import * as keychain from '../secrets/keychain.js';
+import { isSensitiveEnvKey } from '../secrets/sensitivity.js';
+const REF_PREFIX = 'keychain:'; // pragma: allowlist secret
+function parseLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#'))
+        return { raw: line, passthrough: true };
+    const eq = trimmed.indexOf('=');
+    if (eq === -1)
+        return { raw: line, passthrough: true };
+    const key = trimmed.slice(0, eq);
+    let value = trimmed.slice(eq + 1);
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1);
+    }
+    return { raw: line, key, value, passthrough: false };
+}
+function refAccount(stub) {
+    return stub.slice(REF_PREFIX.length);
+}
+function tryResolveRef(stub) {
+    // Account names are stored under the well-known service "clementine-agent",
+    // and the stub is encoded as keychain:<service>-<envVar>. The actual
+    // keychain lookup uses the env-var name as the account label, which is
+    // also the suffix of the stub past the service prefix.
+    const account = refAccount(stub);
+    // The keychain `get(envVar)` helper expects just the env-var name; our
+    // stub format is `keychain:clementine-agent-<envVar>`, so strip the
+    // service prefix before delegating.
+    const SERVICE_PREFIX = 'clementine-agent-';
+    const envVar = account.startsWith(SERVICE_PREFIX) ? account.slice(SERVICE_PREFIX.length) : account;
+    return keychain.get(envVar);
+}
+/**
+ * Pure read + classify pass — no .env writes, no keychain deletes, but
+ * DOES make read-only `security find-generic-password` calls to detect
+ * unresolvable refs (and to verify resolvable ones won't fail later).
+ */
+export function planReverseMigration(baseDir, opts = {}) {
+    const envPath = path.join(baseDir, '.env');
+    if (!existsSync(envPath)) {
+        return { envPath, candidates: [], toMigrate: [], unresolvable: [] };
+    }
+    const raw = readFileSync(envPath, 'utf-8');
+    const onlySet = opts.only ? new Set(opts.only) : undefined;
+    const candidates = [];
+    const toMigrate = [];
+    const unresolvable = [];
+    for (const line of raw.split('\n')) {
+        const parsed = parseLine(line);
+        if (parsed.passthrough || !parsed.key || parsed.value === undefined)
+            continue;
+        if (onlySet && !onlySet.has(parsed.key)) {
+            candidates.push({ key: parsed.key, status: 'skipped' });
+            continue;
+        }
+        if (!parsed.value.startsWith(REF_PREFIX)) {
+            candidates.push({ key: parsed.key, status: 'not-keychain' });
+            continue;
+        }
+        if (isSensitiveEnvKey(parsed.key)) {
+            candidates.push({ key: parsed.key, status: 'sensitive-skipped', ref: parsed.value });
+            continue;
+        }
+        // Try to resolve. If unresolvable, surface separately — caller decides
+        // whether to delete the orphan stub.
+        const resolved = tryResolveRef(parsed.value);
+        if (resolved === undefined) {
+            candidates.push({ key: parsed.key, status: 'unresolvable', ref: parsed.value });
+            unresolvable.push(parsed.key);
+            continue;
+        }
+        candidates.push({ key: parsed.key, status: 'migrated', ref: parsed.value });
+        toMigrate.push(parsed.key);
+    }
+    return { envPath, candidates, toMigrate, unresolvable };
+}
+/**
+ * Apply the migration. Two phases:
+ *   1. Rewrite .env in a temp file, swapping each migrated ref for plaintext.
+ *      If anything throws, the original .env is untouched.
+ *   2. Atomically rename the temp file over .env.
+ *   3. Delete each migrated key's keychain entry. Best-effort — failure to
+ *      delete is logged but doesn't roll back the .env update (the value
+ *      is now safely in .env regardless).
+ */
+export function applyReverseMigration(baseDir, opts = {}) {
+    const envPath = path.join(baseDir, '.env');
+    const result = { envPath, migrated: [], failed: [] };
+    if (!existsSync(envPath))
+        return result;
+    const raw = readFileSync(envPath, 'utf-8');
+    const onlySet = opts.only ? new Set(opts.only) : undefined;
+    const lines = raw.split('\n');
+    const parsedLines = lines.map(parseLine);
+    // Phase 1: resolve every target via keychain (read-only). Bail before
+    // touching anything if any target is unresolvable — caller can rerun
+    // with --key to skip the bad ones.
+    const newValues = new Map();
+    for (const parsed of parsedLines) {
+        if (parsed.passthrough || !parsed.key || parsed.value === undefined)
+            continue;
+        if (onlySet && !onlySet.has(parsed.key))
+            continue;
+        if (!parsed.value.startsWith(REF_PREFIX))
+            continue;
+        if (isSensitiveEnvKey(parsed.key))
+            continue;
+        const resolved = tryResolveRef(parsed.value);
+        if (resolved === undefined) {
+            result.failed.push({ key: parsed.key, error: `keychain entry missing or unreadable for ${parsed.value}` });
+            continue;
+        }
+        newValues.set(parsed.key, resolved);
+    }
+    if (result.failed.length > 0)
+        return result;
+    if (newValues.size === 0)
+        return result;
+    // Phase 2: rewrite .env atomically.
+    const newLines = parsedLines.map((parsed) => {
+        if (parsed.passthrough || !parsed.key)
+            return parsed.raw;
+        const newValue = newValues.get(parsed.key);
+        if (newValue === undefined)
+            return parsed.raw;
+        return `${parsed.key}=${newValue}`;
+    });
+    const tmp = `${envPath}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmp, newLines.join('\n'));
+    renameSync(tmp, envPath);
+    // Phase 3: best-effort keychain deletes.
+    for (const key of newValues.keys()) {
+        try {
+            keychain.remove(key);
+        }
+        catch {
+            /* keychain delete failure is non-fatal — the value is in .env now */
+        }
+        result.migrated.push(key);
+    }
+    return result;
+}
+//# sourceMappingURL=migrate-from-keychain.js.map

package/dist/config.d.ts

@@ -14,6 +14,13 @@ export declare const BASE_DIR: string;
 export declare function envSnapshot(): Record<string, string | undefined>;
 /** Test-only: clear the keychain ref cache so re-resolution can be tested. */
 export declare function _resetKeychainRefCache(): void;
+/**
+ * Return the keychain stubs that couldn't be resolved this process. Used by
+ * the daemon entrypoint to log a clear remediation hint at boot if any
+ * keychain reads are failing (typically: ACL not yet partition-listed →
+ * `clementine config keychain-fix-acl` fixes it).
+ */
+export declare function getFailedKeychainResolutions(): string[];
 export declare const VAULT_DIR: string;
 export declare const SYSTEM_DIR: string;
 export declare const DAILY_NOTES_DIR: string;

package/dist/config.js

@@ -60,6 +60,16 @@ const resolvedKeychainRefs = new Map();
 function isKeychainRef(value) {
     return typeof value === 'string' && value.startsWith(KEYCHAIN_REF_PREFIX);
 }
+/**
+ * Hard cap on each `security find-generic-password` shell call. The macOS
+ * keychain prompts the user for read access on first use of any entry created
+ * with restrictive ACL (`-T ''`). If the prompt doesn't appear (hidden behind
+ * a window, denied silently, or the user is afk), the call would otherwise
+ * block indefinitely — which means `clementine` and the daemon would hang at
+ * boot. Cap and fall through to the caller's default; the failure caches as
+ * null so we don't re-prompt this process. Override via env if needed.
+ */
+const KEYCHAIN_TIMEOUT_MS = Math.max(500, parseInt(env['CLEMENTINE_KEYCHAIN_TIMEOUT_MS'] ?? process.env.CLEMENTINE_KEYCHAIN_TIMEOUT_MS ?? '3000', 10) || 3000);
 function resolveKeychainRef(stub) {
     if (resolvedKeychainRefs.has(stub)) {
         const cached = resolvedKeychainRefs.get(stub);
@@ -69,7 +79,7 @@ function resolveKeychainRef(stub) {
     // is the account name under the well-known service "clementine-agent".
     const account = stub.slice(KEYCHAIN_REF_PREFIX.length);
     try {
-        const result = execSync(`security find-generic-password -s clementine-agent -a ${shellEscape(account)} -w`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+        const result = execSync(`security find-generic-password -s clementine-agent -a ${shellEscape(account)} -w`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], timeout: KEYCHAIN_TIMEOUT_MS }).trim();
         resolvedKeychainRefs.set(stub, result || null);
         return result || undefined;
     }
@@ -107,6 +117,20 @@ export function envSnapshot() {
 export function _resetKeychainRefCache() {
     resolvedKeychainRefs.clear();
 }
+/**
+ * Return the keychain stubs that couldn't be resolved this process. Used by
+ * the daemon entrypoint to log a clear remediation hint at boot if any
+ * keychain reads are failing (typically: ACL not yet partition-listed →
+ * `clementine config keychain-fix-acl` fixes it).
+ */
+export function getFailedKeychainResolutions() {
+    const out = [];
+    for (const [stub, value] of resolvedKeychainRefs) {
+        if (value === null)
+            out.push(stub);
+    }
+    return out;
+}
 // ── Paths ────────────────────────────────────────────────────────────
 export const VAULT_DIR = path.join(BASE_DIR, 'vault');
 export const SYSTEM_DIR = path.join(VAULT_DIR, '00-System');
@@ -158,7 +182,7 @@ function getSecret(envKey, keychainService) {
         return local;
     const service = keychainService ?? ASSISTANT_NAME.toLowerCase();
     try {
-        const result = execSync(`security find-generic-password -s ${shellEscape(service)} -a ${shellEscape(envKey)} -w`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+        const result = execSync(`security find-generic-password -s ${shellEscape(service)} -a ${shellEscape(envKey)} -w`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], timeout: KEYCHAIN_TIMEOUT_MS });
         return result.trim();
     }
     catch {

package/dist/gateway/cron-scheduler.d.ts

@@ -32,6 +32,25 @@ export declare function parseAgentCronJobs(agentsDir: string): CronJobDefinition
  * Returns null on success, or the error message on failure.
  */
 export declare function validateCronYaml(content: string): string | null;
+/**
+ * Detect duplicate job definitions across the global CRON.md and agent-scoped
+ * CRON.md files. A "duplicate" is a global job tagged with `agentSlug: X`
+ * whose bare name matches a job defined in `agents/X/CRON.md` — i.e. the same
+ * conceptual job exists in two places, usually with diverged prompts.
+ *
+ * Returns a list of warnings; pure function, safe to call from any surface.
+ * The scheduler logs these on every reload so the user sees them on first
+ * boot AND on every CRON.md edit.
+ */
+export interface DuplicateJobWarning {
+    bareName: string;
+    agentSlug: string;
+    globalJobName: string;
+    agentJobName: string;
+    /** Diverged fields between the two definitions, for actionable reporting. */
+    divergedFields: string[];
+}
+export declare function findDuplicateJobDefinitions(globalJobs: CronJobDefinition[], agentJobs: CronJobDefinition[]): DuplicateJobWarning[];
 export declare function classifyError(err: unknown): 'transient' | 'permanent';
 /**
  * Classify a TerminalReason from the SDK into a retry strategy.

package/dist/gateway/cron-scheduler.js

@@ -193,6 +193,43 @@ export function validateCronYaml(content) {
         return err instanceof Error ? err.message : String(err);
     }
 }
+export function findDuplicateJobDefinitions(globalJobs, agentJobs) {
+    const warnings = [];
+    // Index agent jobs by `${slug}:${bareName}` (which is how parseAgentCronJobs
+    // names them). For each global job with an agentSlug, look up the
+    // corresponding agent-scoped name.
+    const agentByName = new Map();
+    for (const a of agentJobs)
+        agentByName.set(a.name, a);
+    for (const g of globalJobs) {
+        if (!g.agentSlug)
+            continue;
+        const expected = `${g.agentSlug}:${g.name}`;
+        const a = agentByName.get(expected);
+        if (!a)
+            continue;
+        // Found a duplicate. Compute diverged fields so the warning is actionable.
+        const diverged = [];
+        const compare = [
+            'schedule', 'enabled', 'tier', 'mode', 'maxHours', 'maxTurns',
+            'workDir', 'prompt', 'preCheck',
+        ];
+        for (const f of compare) {
+            const gv = g[f];
+            const av = a[f];
+            if (JSON.stringify(gv) !== JSON.stringify(av))
+                diverged.push(f);
+        }
+        warnings.push({
+            bareName: g.name,
+            agentSlug: g.agentSlug,
+            globalJobName: g.name,
+            agentJobName: a.name,
+            divergedFields: diverged,
+        });
+    }
+    return warnings;
+}
 // ── Retry / backoff ──────────────────────────────────────────────────
 /** Exponential backoff schedule in ms: 30s, 1m, 5m, 15m, 60m */
 const BACKOFF_MS = [30_000, 60_000, 300_000, 900_000, 3_600_000];
@@ -425,10 +462,21 @@ export class CronScheduler {
     }
     /** Load job definitions from CRON.md and agent dirs without scheduling tasks. */
     loadJobDefinitions() {
-        this.jobs = parseCronJobs();
+        const globalJobs = parseCronJobs();
         const agentJobs = parseAgentCronJobs(AGENTS_DIR);
-        if (agentJobs.length > 0) {
-            this.jobs.push(...agentJobs);
+        this.jobs = [...globalJobs, ...agentJobs];
+        // Surface duplicate definitions loud — these are footguns where the same
+        // conceptual job is defined in both global and agent-scoped CRON.md, often
+        // with diverged prompts. The user usually wants one of them deleted.
+        const dupes = findDuplicateJobDefinitions(globalJobs, agentJobs);
+        for (const d of dupes) {
+            logger.warn({
+                bareName: d.bareName,
+                agentSlug: d.agentSlug,
+                globalJob: d.globalJobName,
+                agentJob: d.agentJobName,
+                divergedFields: d.divergedFields,
+            }, `Duplicate cron definition: '${d.bareName}' is defined in both global CRON.md (with agentSlug=${d.agentSlug}) and agents/${d.agentSlug}/CRON.md. Consolidate to avoid confusion — pick one and delete the other.`);
         }
     }
     /** Register a listener that fires when system state changes (job start/finish, self-improve, etc). */

package/dist/index.js

@@ -548,6 +548,17 @@ async function asyncMain() {
         hydrateSecretsFromEnv();
     }
     catch { /* non-fatal — non-macOS systems, or keychain unavailable */ }
+    // ── Surface keychain resolution failures with a clear remediation hint ──
+    // If any keychain ref couldn't be read at module-init time, the user is
+    // probably hitting the per-process approval-dialog issue (entry written
+    // with the wrong ACL). The fix is one command — print it loud so they
+    // don't have to grep for the answer.
+    const failedKcRefs = config.getFailedKeychainResolutions();
+    if (failedKcRefs.length > 0) {
+        logger.warn({ count: failedKcRefs.length, refs: failedKcRefs }, `${failedKcRefs.length} keychain reference(s) could not be resolved at startup.`);
+        logger.warn('Affected channels/integrations may be degraded. Fix in one command: clementine config keychain-fix-acl');
+        logger.warn('See: https://github.com/Natebreynolds/Clementine-AI-Assistant#keychain-prompts');
+    }
     // ── Check MCP extension permissions ────────────────────────────
     try {
         const { checkPermissionsOnStartup, bootstrapClaudeIntegrationsFromAuditLog, probeAvailableTools } = await import('./agent/mcp-bridge.js');

package/dist/secrets/keychain.js

@@ -54,14 +54,20 @@ export function set(envVar, value) {
         throw new Error('Keychain unavailable on this platform');
     }
     const account = `${SERVICE_NAME}-${envVar}`;
-    // -U updates existing entry in place; -s = service; -a = account; -w = password
+    // -U updates existing entry in place; -s = service; -a = account; -w = password.
+    // -T /usr/bin/security pre-approves the `security` CLI itself — that's what
+    // every Clementine read goes through, so reads via clementine/the daemon
+    // don't produce a per-process keychain dialog. Without this flag, every
+    // node process that reads the entry would block on a UI prompt that may
+    // never appear (hidden behind windows, dismissed silently, etc.) — which
+    // is the bug that motivated this change.
     const result = spawnSync('/usr/bin/security', [
         'add-generic-password',
         '-U',
         '-s', SERVICE_NAME,
         '-a', account,
         '-w', value,
-        '-T', '', // no apps pre-approved — will prompt on first read; user can approve for login session
+        '-T', '/usr/bin/security',
         '-l', `Clementine: ${envVar}`,
     ], { stdio: 'pipe' });
     if (result.status !== 0) {

package/dist/tools/admin-tools.js

@@ -122,10 +122,10 @@ export function registerAdminTools(server) {
         return textResult(`Timer set. Reminder in ${minutes} minute${minutes !== 1 ? 's' : ''} (~${fireTime}): "${message}"`);
     });
     // ── Env self-configuration (owner-DM only) ────────────────────────────
-    server.tool('env_set', 'Save or update an env var. Owner-DM only. In "auto" mode (default), credential-shaped keys (API keys, tokens, secrets, passwords) go to the macOS Keychain; everything else goes to plain ~/.clementine/.env. Force keychain or env via the storage arg if you need to override. Changes take effect immediately; process.env gets the real value and the next tool call can use it. Use this when the owner gives a value in chat — never tell them to hand-edit files.', {
+    server.tool('env_set', 'Save or update an env var. Owner-DM only. Default behavior writes to plain ~/.clementine/.env (mode 0600). Pass storage="keychain" to opt into macOS Keychain storage — but be aware keychain entries can require per-app approval prompts on first read which create UX friction (see commit history for the rabbit hole). Use plain .env unless you specifically need at-rest encryption beyond filesystem permissions.', {
         key: z.string().describe('Env var name (uppercase with underscores, e.g. STRIPE_API_KEY)'),
         value: z.string().describe('The value to store. Never echo back to the user; it will be masked in logs.'),
-        storage: z.enum(['keychain', 'env', 'auto']).optional().describe('Where to store it. "auto" (default) routes credential-shaped keys to Keychain and config-shaped keys to plain .env. "keychain" forces Keychain. "env" forces plaintext .env.'),
+        storage: z.enum(['keychain', 'env', 'auto']).optional().describe('Where to store it. Default (and "auto"/"env") writes plaintext to ~/.clementine/.env. "keychain" opts into macOS Keychain — only use when at-rest encryption matters more than read ergonomics.'),
     }, async ({ key, value, storage }) => {
         const gate = requireOwnerDm();
         if (!gate.ok)
@@ -137,14 +137,19 @@ export function registerAdminTools(server) {
         if (!value)
             return textResult('Refused: empty value. Use env_unset to remove a key.');
         const mode = storage ?? 'auto';
-        const looksSensitive = isSensitiveEnvKey(normalizedKey);
-        // auto mode: keychain-route only credential-shaped keys, so config knobs
-        // (BUDGET_*, OWNER_NAME, etc.) stay readable as plain .env values.
-        const useKeychain = mode === 'keychain' ||
-            (mode === 'auto' && looksSensitive && keychain.isAvailable());
+        // Keychain is now strictly opt-in. The legacy 'auto' mode used to route
+        // credential-shaped keys to keychain, but that produced a class of read-
+        // approval dialog UX bugs (see commits 88cfd99 .. c34da0b). Plaintext .env
+        // with mode 0600 is the safer default — credentials still encrypted at
+        // rest if FileVault is on, and no per-process keychain prompts.
+        const useKeychain = mode === 'keychain';
         if (mode === 'keychain' && !keychain.isAvailable()) {
             return textResult('Refused: Keychain storage requested but macOS Keychain is unavailable on this system.');
         }
+        // Reference unused-but-imported helper so the import line stays meaningful
+        // for grep — it's used by other modules and we may re-enable smart routing
+        // later behind a feature flag.
+        void isSensitiveEnvKey;
         const map = parseEnvFile();
         const existed = map.has(normalizedKey);
         let envFileValue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clementine-agent",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",