@phnx-labs/agents-cli 1.20.0 → 1.20.3

package/dist/lib/versions.js

@@ -511,16 +511,130 @@ export function getActuallySyncedResources(agent, version, options = {}) {
     }
     return result;
 }
+/**
+ * Names that exist ONLY in the project's `.agents/` layer (no matching entry in
+ * user/system/extra layers). Sync intentionally skips project-layer commands,
+ * skills, hooks, subagents, plugins, and workflows for security — see the
+ * defense comments above each sync branch in syncResourcesToVersion. Without
+ * this filter, those names would forever appear in the "New resources" diff
+ * because they live in `available` but never reach `actuallySynced`.
+ */
+export function getProjectOnlyResources(cwd = process.cwd()) {
+    const empty = {
+        commands: new Set(), skills: new Set(), hooks: new Set(),
+        subagents: new Set(), plugins: new Set(), workflows: new Set(),
+    };
+    const projectAgentsDir = getProjectAgentsDir(cwd);
+    if (!projectAgentsDir)
+        return empty;
+    const trustedBases = [getUserAgentsDir(), getAgentsDir(), ...getEnabledExtraRepos().map(e => e.dir)];
+    const trustedNames = (relSubdir, predicate) => {
+        const acc = new Set();
+        for (const base of trustedBases) {
+            const dir = path.join(base, relSubdir);
+            if (!fs.existsSync(dir))
+                continue;
+            try {
+                for (const entry of fs.readdirSync(dir)) {
+                    if (entry.startsWith('.'))
+                        continue;
+                    if (predicate(path.join(dir, entry), entry))
+                        acc.add(entry);
+                }
+            }
+            catch { /* ignore unreadable */ }
+        }
+        return acc;
+    };
+    const readProjectNames = (relSubdir, predicate) => {
+        const dir = path.join(projectAgentsDir, relSubdir);
+        if (!fs.existsSync(dir))
+            return [];
+        try {
+            return fs.readdirSync(dir)
+                .filter(e => !e.startsWith('.'))
+                .filter(e => predicate(path.join(dir, e), e));
+        }
+        catch {
+            return [];
+        }
+    };
+    const isMdFile = (full, name) => name.endsWith('.md') && (() => { try {
+        return fs.statSync(full).isFile();
+    }
+    catch {
+        return false;
+    } })();
+    const isDir = (full) => { try {
+        return fs.statSync(full).isDirectory();
+    }
+    catch {
+        return false;
+    } };
+    const hasFile = (sub) => (full) => isDir(full) && fs.existsSync(path.join(full, sub));
+    const stripMd = (n) => n.replace(/\.md$/, '');
+    const trustedCommands = new Set([...trustedNames('commands', isMdFile)].map(stripMd));
+    const projectCommands = readProjectNames('commands', isMdFile).map(stripMd);
+    for (const n of projectCommands)
+        if (!trustedCommands.has(n))
+            empty.commands.add(n);
+    const trustedSkills = trustedNames('skills', (full) => isDir(full));
+    for (const n of readProjectNames('skills', (full) => isDir(full)))
+        if (!trustedSkills.has(n))
+            empty.skills.add(n);
+    // Hooks: project entries are files; trusted entries are also files. Name match
+    // is filename-with-extension (sync compares by full filename, line 2031).
+    const trustedHooks = trustedNames('hooks', (full) => { try {
+        return fs.statSync(full).isFile();
+    }
+    catch {
+        return false;
+    } });
+    for (const n of readProjectNames('hooks', (full) => { try {
+        return fs.statSync(full).isFile();
+    }
+    catch {
+        return false;
+    } })) {
+        if (!trustedHooks.has(n))
+            empty.hooks.add(n);
+    }
+    const trustedSubagents = trustedNames('subagents', hasFile('AGENT.md'));
+    for (const n of readProjectNames('subagents', hasFile('AGENT.md'))) {
+        if (!trustedSubagents.has(n))
+            empty.subagents.add(n);
+    }
+    const trustedWorkflows = trustedNames('workflows', hasFile('WORKFLOW.md'));
+    for (const n of readProjectNames('workflows', hasFile('WORKFLOW.md'))) {
+        if (!trustedWorkflows.has(n))
+            empty.workflows.add(n);
+    }
+    const trustedPlugins = trustedNames('plugins', hasFile('.claude-plugin/plugin.json'));
+    for (const n of readProjectNames('plugins', hasFile('.claude-plugin/plugin.json'))) {
+        if (!trustedPlugins.has(n))
+            empty.plugins.add(n);
+    }
+    return empty;
+}
 /**
  * Compare available resources with what's ACTUALLY synced to version home.
  * Returns only NEW resources that haven't been synced yet.
  * Source of truth: the actual files/config, NOT agents.yaml tracking.
+ *
+ * `projectOnly` (recommended): the result of `getProjectOnlyResources(cwd)`.
+ * Names listed there are filtered out for kinds that sync intentionally
+ * excludes the project layer — otherwise they would re-appear as "new"
+ * on every run and "Yes, sync all new" would silently do nothing for them.
  */
-export function getNewResources(available, actuallySynced) {
+export function getNewResources(available, actuallySynced, projectOnly) {
+    const exclude = projectOnly || {
+        commands: new Set(), skills: new Set(), hooks: new Set(),
+        subagents: new Set(), plugins: new Set(), workflows: new Set(),
+    };
     return {
-        commands: available.commands.filter(c => !actuallySynced.commands.includes(c)),
-        skills: available.skills.filter(s => !actuallySynced.skills.includes(s)),
-        hooks: available.hooks.filter(h => !actuallySynced.hooks.includes(h)),
+        commands: available.commands.filter(c => !actuallySynced.commands.includes(c) && !exclude.commands.has(c)),
+        skills: available.skills.filter(s => !actuallySynced.skills.includes(s) && !exclude.skills.has(s)),
+        hooks: available.hooks.filter(h => !actuallySynced.hooks.includes(h) && !exclude.hooks.has(h)),
         // Memory/rules presets are mutually exclusive — only one can be active.
         // If any preset is synced, don't report others as "new".
         memory: actuallySynced.memory.length > 0
@@ -528,9 +642,9 @@ export function getNewResources(available, actuallySynced) {
             : available.memory.filter(m => !actuallySynced.memory.includes(m)),
         mcp: available.mcp.filter(m => !actuallySynced.mcp.includes(m)),
         permissions: available.permissions.filter(p => !actuallySynced.permissions.includes(p)),
-        subagents: available.subagents.filter(s => !actuallySynced.subagents.includes(s)),
-        plugins: available.plugins.filter(p => !actuallySynced.plugins.includes(p)),
-        workflows: available.workflows.filter(w => !actuallySynced.workflows.includes(w)),
+        subagents: available.subagents.filter(s => !actuallySynced.subagents.includes(s) && !exclude.subagents.has(s)),
+        plugins: available.plugins.filter(p => !actuallySynced.plugins.includes(p) && !exclude.plugins.has(p)),
+        workflows: available.workflows.filter(w => !actuallySynced.workflows.includes(w) && !exclude.workflows.has(w)),
         // Promptcuts aren't version-scoped — the hook reads ~/.agents/promptcuts.yaml
         // directly, so there is never a "new" per-version state to reconcile.
         promptcuts: false,
@@ -1027,56 +1141,50 @@ export function setGlobalDefault(agent, version) {
  */
 export async function installVersion(agent, version, onProgress) {
     const agentConfig = AGENTS[agent];
-    if (!agentConfig.npmPackage) {
-        // Support agents that provide an installScript (cursor, roo, goose, kiro, grok, etc.)
-        if (agentConfig.installScript) {
-            // For grok we give special love because the user asked for first-class support
-            if (agent === 'grok') {
-                onProgress?.(`Installing Grok ${version} via official installer...`);
-                try {
-                    const script = agentConfig.installScript.replace('VERSION', version);
-                    // The official installer supports -s <version>
-                    const { exec } = await import('child_process');
-                    const { promisify } = await import('util');
-                    const execAsync = promisify(exec);
-                    await execAsync(script, { timeout: 120000 });
-                    onProgress?.('Grok binary installed. Setting up agents-cli version home for isolation...');
-                }
-                catch (err) {
-                    return { success: false, installedVersion: version, error: `Grok installer failed: ${err.message}` };
-                }
-            }
-            else {
-                return {
-                    success: false,
-                    installedVersion: version,
-                    error: `${agent} uses an external installer. Run: ${agentConfig.installScript}`,
-                };
-            }
-        }
-        else {
-            return { success: false, installedVersion: version, error: 'Agent has no npm package' };
-        }
-    }
     // Validate before deriving filesystem paths or npm package specs. The CLI
     // parser already enforces this for user input; this guard protects direct
     // callers and tests the critical install path at the source.
     if (!VERSION_RE.test(version)) {
         throw new Error(`Invalid version: ${JSON.stringify(version)}`);
     }
+    if (!agentConfig.npmPackage) {
+        if (!agentConfig.installScript) {
+            return { success: false, installedVersion: version, error: 'Agent has no npm package' };
+        }
+        if (version !== 'latest' && !agentConfig.installScript.includes('VERSION')) {
+            return {
+                success: false,
+                installedVersion: version,
+                error: `${agentConfig.name} installer does not support version-pinned installs. Use ${agent}@latest.`,
+            };
+        }
+        let installedVersion = version;
+        try {
+            const script = agentConfig.installScript.replaceAll('VERSION', version);
+            onProgress?.(`Installing ${agentConfig.name}@${version} via official installer...`);
+            await execAsync(script, { timeout: 120000 });
+            if (version === 'latest') {
+                installedVersion = await getCliVersionFromPath(agent) || version;
+            }
+            onProgress?.(`${agentConfig.name} installed. Setting up agents-cli version home for isolation...`);
+        }
+        catch (err) {
+            emit('version.install', { agent, version, error: err.message });
+            return { success: false, installedVersion: version, error: `${agentConfig.name} installer failed: ${err.message}` };
+        }
+        ensureAgentsDir();
+        const versionDir = getVersionDir(agent, installedVersion);
+        fs.mkdirSync(versionDir, { recursive: true });
+        fs.mkdirSync(path.join(versionDir, 'home'), { recursive: true });
+        createVersionedAlias(agent, installedVersion);
+        emit('version.install', { agent, version: installedVersion });
+        return { success: true, installedVersion };
+    }
     ensureAgentsDir();
     const versionDir = getVersionDir(agent, version);
     // Create version directory and isolated home
     fs.mkdirSync(versionDir, { recursive: true });
     fs.mkdirSync(path.join(versionDir, 'home'), { recursive: true });
-    // For agents using external installers (especially grok), we don't do npm install.
-    // The binary is managed by the agent's own installer; we only manage the isolated home + resources.
-    if (agent === 'grok' || !agentConfig.npmPackage) {
-        // Grok (and similar) — binary already installed by the step above (or user ran external installer).
-        // We still want to record the version for config isolation.
-        createVersionedAlias(agent, version);
-        return { success: true, installedVersion: version };
-    }
     // Initialize package.json (only for real npm agents)
     const packageJson = {
         name: `agents-${agent}-${version}`,
@@ -1408,6 +1516,18 @@ export async function getInstalledVersion(agent, version) {
         return version;
     }
 }
+async function getCliVersionFromPath(agent) {
+    const agentConfig = AGENTS[agent];
+    try {
+        await execFileAsync('which', [agentConfig.cliCommand]);
+        const { stdout } = await execFileAsync(agentConfig.cliCommand, ['--version'], { timeout: 3000 });
+        const match = stdout.match(/(\d+\.\d+\.\d+)/);
+        return match ? match[1] : null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Get the diff between central resources (~/.agents/) and what's synced to a version.
  * Uses filesystem state - no tracking needed.
@@ -1646,12 +1766,11 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
             }
         }
     }
-    // Fast guard: skip the entire sync when no selection is active and nothing
-    // has changed since the last full sync. Drops steady-state cost from ~16s
-    // (unconditional file copies) to ~8-15ms (`isStale` walks the manifest's
-    // fingerprints, short-circuiting at the first mismatch). Numbers from
-    // scripts/bench-staleness.ts against a real ~50-resource project.
-    if (!selection && !options.force) {
+    // Fast guard: skip the entire sync when the caller requested a full sync and
+    // nothing has changed since the last full sync. Pattern-derived selections
+    // still count as full syncs because they are the persisted intended scope,
+    // not a one-off caller override.
+    if (!userPassedSelection && !options.force) {
         const manifest = loadManifest(agent, version);
         if (manifest && !isStale(manifest, agent, version, cwd)) {
             return { commands: false, skills: false, hooks: false, memory: [], permissions: false, mcp: [], subagents: [], plugins: [], workflows: [] };
@@ -1758,8 +1877,8 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     // not pass an explicit `selection`. Callers that pass explicit selections
     // are using the incremental/additive API (sync exactly these; leave others
     // alone), so the sweep would be a contract violation there. The
-    // cross-project leak fixed by RUSH-670 always comes from the no-selection
-    // shim auto-sync at launch.
+    // cross-project leak always comes from the no-selection shim auto-sync at
+    // launch.
     if (!userPassedSelection && COMMANDS_CAPABLE_AGENTS.includes(agent) && !shouldInstallCommandAsSkill(agent, version)) {
         const commandsTargetSweep = path.join(agentDir, agentConfig.commandsSubdir);
         if (fs.existsSync(commandsTargetSweep)) {
@@ -2121,6 +2240,24 @@ export function getEffectiveHome(agentId) {
     }
     return os.homedir();
 }
+/**
+ * Thrown when the user references an agent@version that is not installed.
+ * Carries the parsed (agentId, version) so callers can react — e.g. prompt
+ * to install it on demand — without having to parse the error message.
+ */
+export class VersionNotInstalledError extends Error {
+    agentId;
+    version;
+    installedVersions;
+    constructor(agentId, version, installedVersions) {
+        const installed = installedVersions.length > 0 ? installedVersions.join(', ') : '(none)';
+        super(`Version ${version} is not installed for ${AGENTS[agentId].name}. Installed versions: ${installed}`);
+        this.agentId = agentId;
+        this.version = version;
+        this.installedVersions = installedVersions;
+        this.name = 'VersionNotInstalledError';
+    }
+}
 /**
  * Resolve a comma-separated --agents list into concrete version selections.
  * Bare agents target the default version, or the newest installed version when no default exists.
@@ -2130,10 +2267,26 @@ export function resolveAgentVersionTargets(value, availableAgents, options = {})
     const selectedAgents = [];
     const versionSelections = new Map();
     const explicitSelections = new Set();
-    const targets = value
+    const rawTargets = value
         .split(',')
         .map((item) => item.trim())
         .filter(Boolean);
+    // Expand literal `all` (with optional @all) into every available agent's all
+    // installed versions. Skip agents with no installed versions so `all` is
+    // lenient — only explicit `claude@all` errors when claude isn't installed.
+    const targets = [];
+    for (const t of rawTargets) {
+        if (t === 'all' || t === 'all@all') {
+            for (const a of availableAgents) {
+                if (listInstalledVersions(a).length > 0) {
+                    targets.push(`${a}@all`);
+                }
+            }
+        }
+        else {
+            targets.push(t);
+        }
+    }
     for (const target of targets) {
         const atIndex = target.indexOf('@');
         const agentToken = (atIndex === -1 ? target : target.slice(0, atIndex)).trim();
@@ -2142,7 +2295,7 @@ export function resolveAgentVersionTargets(value, availableAgents, options = {})
             continue;
         }
         if (atIndex !== -1 && !versionToken) {
-            throw new Error(`Missing version in --agents entry '${target}'. Use agent@x.y.z or agent@default.`);
+            throw new Error(`Missing version in --agents entry '${target}'. Use agent@x.y.z, agent@default, or agent@all.`);
         }
         const agentId = resolveAgentName(agentToken);
         if (!agentId || !availableAgents.includes(agentId)) {
@@ -2182,8 +2335,13 @@ export function resolveAgentVersionTargets(value, availableAgents, options = {})
             explicitSelections.add(agentId);
             continue;
         }
+        if (versionToken === 'all') {
+            versionSelections.set(agentId, [...installedVersions]);
+            explicitSelections.add(agentId);
+            continue;
+        }
         if (!installedVersions.includes(versionToken)) {
-            throw new Error(`Version ${versionToken} is not installed for ${AGENTS[agentId].name}. Installed versions: ${installedVersions.join(', ')}`);
+            throw new VersionNotInstalledError(agentId, versionToken, installedVersions);
         }
         const explicitVersions = explicitSelections.has(agentId)
             ? (versionSelections.get(agentId) || [])
@@ -2206,10 +2364,28 @@ export function resolveInstalledAgentTargets(value, availableAgents, options = {
     const selectedAgents = [];
     const directAgents = [];
     const versionSelections = new Map();
-    const targets = value
+    const rawTargets = value
         .split(',')
         .map((item) => item.trim())
         .filter(Boolean);
+    // Expand literal `all` (with optional @all) into every available agent's all
+    // installed versions. Skip agents with no installed versions so `all` is
+    // lenient — only explicit `claude@all` errors when claude isn't installed.
+    // Mirrors resolveAgentVersionTargets so every --agents flag site supports
+    // the same selector syntax.
+    const targets = [];
+    for (const t of rawTargets) {
+        if (t === 'all' || t === 'all@all') {
+            for (const a of availableAgents) {
+                if (listInstalledVersions(a).length > 0) {
+                    targets.push(`${a}@all`);
+                }
+            }
+        }
+        else {
+            targets.push(t);
+        }
+    }
     const addVersionTarget = (agentId, version) => {
         const versions = versionSelections.get(agentId) || [];
         if (!versions.includes(version)) {
@@ -2229,7 +2405,7 @@ export function resolveInstalledAgentTargets(value, availableAgents, options = {
             continue;
         }
         if (atIndex !== -1 && !versionToken) {
-            throw new Error(`Missing version in --agents entry '${target}'. Use agent@x.y.z or agent@default.`);
+            throw new Error(`Missing version in --agents entry '${target}'. Use agent@x.y.z, agent@default, or agent@all.`);
         }
         const agentId = resolveAgentName(agentToken);
         if (!agentId || !availableAgents.includes(agentId)) {
@@ -2262,11 +2438,20 @@ export function resolveInstalledAgentTargets(value, availableAgents, options = {
             addVersionTarget(agentId, defaultVersion);
             continue;
         }
+        if (versionToken === 'all') {
+            if (installedVersions.length === 0) {
+                throw new Error(`No managed versions are installed for ${AGENTS[agentId].name}. Run: agents add ${agentId}@latest`);
+            }
+            for (const version of installedVersions) {
+                addVersionTarget(agentId, version);
+            }
+            continue;
+        }
         if (installedVersions.length === 0) {
             throw new Error(`No managed versions are installed for ${AGENTS[agentId].name}. Run: agents add ${agentId}@latest`);
         }
         if (!installedVersions.includes(versionToken)) {
-            throw new Error(`Version ${versionToken} is not installed for ${AGENTS[agentId].name}. Installed versions: ${installedVersions.join(', ')}`);
+            throw new VersionNotInstalledError(agentId, versionToken, installedVersions);
         }
         addVersionTarget(agentId, versionToken);
     }
@@ -2320,9 +2505,15 @@ export async function promptAgentVersionSelection(availableAgents, options = {})
         const defaultVer = getGlobalDefault(agentId);
         if (versions.length === 0)
             return `${AGENTS[agentId].name}  ${chalk.gray('(not installed)')}`;
-        if (defaultVer)
-            return `${AGENTS[agentId].name}  ${chalk.gray(`(active: ${defaultVer})`)}`;
-        return `${AGENTS[agentId].name}  ${chalk.gray(`(${versions[0]})`)}`;
+        // Surface the version count when there's more than one — mirrors the new
+        // `--agents <agent>@all` syntax so users can see at a glance how many
+        // versions `@all` would target before the per-version prompt fires.
+        const detail = versions.length > 1
+            ? (defaultVer
+                ? `active: ${defaultVer}, ${versions.length} versions installed`
+                : `${versions.length} versions installed`)
+            : (defaultVer ?? versions[0]);
+        return `${AGENTS[agentId].name}  ${chalk.gray(`(${detail})`)}`;
     };
     let selectedAgents;
     if (options.skipPrompts) {
@@ -2337,6 +2528,18 @@ export async function promptAgentVersionSelection(availableAgents, options = {})
         }
     }
     else {
+        // Non-TTY without an explicit --agents value used to silently fall through
+        // to default-picking inside the caller. That's surprising in scripts — fail
+        // loud and point at the new `--agents` syntax instead.
+        if (!(process.stdin.isTTY && process.stdout.isTTY)) {
+            throw new Error('Non-interactive shell: cannot prompt for agent/version selection.\n' +
+                'Pass --agents explicitly. Examples:\n' +
+                '  --agents claude              (default version)\n' +
+                '  --agents claude@all          (every installed Claude version)\n' +
+                '  --agents claude@2.1.141      (a specific version)\n' +
+                '  --agents all                 (every installed version of every capable agent)\n' +
+                'Or pass --yes to auto-pick defaults.');
+        }
         // Prompt for agent selection
         const checkboxResult = await checkbox({
             message: 'Which agents should receive these resources?',
@@ -2371,7 +2574,7 @@ export async function promptAgentVersionSelection(availableAgents, options = {})
             const versionResult = await checkbox({
                 message: `Which versions of ${AGENTS[agentId].name} should receive these resources?`,
                 choices: [
-                    { name: chalk.bold('All versions'), value: 'all', checked: false },
+                    { name: chalk.bold(`All versions (${versions.length})`), value: 'all', checked: false },
                     ...versions.map((v) => {
                         const base = v === defaultVer ? `${v} (default)` : v;
                         let label = base.padEnd(maxLabelLen);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.0",
+  "version": "1.20.3",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",
@@ -25,12 +25,13 @@
     "dist/**/*.d.ts",
     "dist/lib/secrets/Agents CLI.app/**",
     "scripts/postinstall.js",
+    "scripts/install-helper.js",
     "CHANGELOG.md",
     "README.md",
     "LICENSE"
   ],
   "publishConfig": {
-    "provenance": true
+    "provenance": false
   },
   "repository": {
     "type": "git",
@@ -78,8 +79,8 @@
     "@xterm/headless": "6.0.0",
     "@zed-industries/agent-client-protocol": "0.4.5",
     "chalk": "5.6.2",
-    "commander": "12.1.0",
-    "croner": "9.1.0",
+    "commander": "15.0.0",
+    "croner": "10.0.1",
     "diff": "9.0.0",
     "marked": "15.0.12",
     "marked-terminal": "7.3.0",
@@ -88,14 +89,14 @@
     "proper-lockfile": "4.1.2",
     "simple-git": "3.36.0",
     "smol-toml": "1.6.1",
-    "yaml": "2.8.3"
+    "yaml": "2.9.0"
   },
   "devDependencies": {
-    "@types/diff": "6.0.0",
+    "@types/diff": "8.0.0",
     "@types/marked-terminal": "6.1.1",
-    "@types/node": "22.19.10",
+    "@types/node": "25.9.1",
     "tsx": "4.22.3",
-    "typescript": "5.9.3",
+    "typescript": "6.0.3",
     "vitest": "4.1.6"
   }
 }

package/scripts/install-helper.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+/**
+ * Copy the bundled `Agents CLI.app` to a stable user-scoped path so its
+ * keychain ACLs survive future npm installs/updates.
+ *
+ * Source:      dist/lib/secrets/Agents CLI.app   (in the installed npm package)
+ *              bin/Agents CLI.app                 (in a raw working tree)
+ * Destination: ~/Library/Application Support/agents-cli/Agents CLI.app
+ *
+ * Invoked by scripts/postinstall.js on global install, and by
+ * scripts/install.sh for dev installs. Pure Node, no agents-cli imports,
+ * so it runs before the package's TS is wired up.
+ *
+ * macOS only — silently no-ops on other platforms so postinstall stays clean.
+ */
+
+import { spawnSync } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+
+const APP_BUNDLE_NAME = 'Agents CLI.app';
+const INSTALL_DIR_NAME = 'agents-cli';
+
+function destAppPath() {
+  return path.join(os.homedir(), 'Library', 'Application Support', INSTALL_DIR_NAME, APP_BUNDLE_NAME);
+}
+
+function findSourceApp() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  // From scripts/install-helper.js, look in the installed npm layout first
+  // (../dist/lib/secrets/...) then a raw repo layout (../bin/...).
+  const candidates = [
+    path.resolve(here, '..', 'dist', 'lib', 'secrets', APP_BUNDLE_NAME),
+    path.resolve(here, '..', 'bin', APP_BUNDLE_NAME),
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(c)) return c;
+  }
+  return null;
+}
+
+function codesignVerify(appPath) {
+  const r = spawnSync('codesign', ['--verify', '--deep', '--strict', appPath], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    encoding: 'utf-8',
+  });
+  return { ok: r.status === 0, output: (r.stderr || r.stdout || '').toString().trim() };
+}
+
+function copyAppBundle(src, dest) {
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  if (fs.existsSync(dest)) fs.rmSync(dest, { recursive: true, force: true });
+  const r = spawnSync('cp', ['-R', src, dest], { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf-8' });
+  if (r.status !== 0) {
+    const msg = (r.stderr || r.stdout || '').toString().trim();
+    throw new Error(`Failed to copy ${src} -> ${dest}: ${msg || 'unknown error'}`);
+  }
+}
+
+function main() {
+  if (process.platform !== 'darwin') return;
+  const force = process.argv.includes('--force');
+  const dest = destAppPath();
+
+  if (!force && fs.existsSync(dest) && codesignVerify(dest).ok) {
+    return;
+  }
+
+  const src = findSourceApp();
+  if (!src) {
+    // No source bundle to install. Stay silent during postinstall so we don't
+    // create noise on Linux/Windows or on builds that intentionally omit the
+    // helper. `agents helper install` surfaces a clearer error if a user
+    // actually needs the helper.
+    return;
+  }
+
+  try {
+    copyAppBundle(src, dest);
+  } catch (err) {
+    process.stderr.write(`agents-cli: failed to install Keychain helper: ${err.message}\n`);
+    return;
+  }
+
+  const verify = codesignVerify(dest);
+  if (!verify.ok) {
+    process.stderr.write(
+      `agents-cli: installed helper failed codesign verification at ${dest}\n${verify.output}\n`
+    );
+    return;
+  }
+  process.stdout.write(`  Installed Keychain helper: ${dest}\n`);
+}
+
+main();

package/scripts/postinstall.js

@@ -7,6 +7,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import * as readline from 'readline';
+import { spawnSync } from 'child_process';
 import { fileURLToPath } from 'url';
 
 const HOME = os.homedir();
@@ -14,6 +15,16 @@ const SHIMS_DIR = path.join(HOME, '.agents', '.cache', 'shims');
 const SYSTEM_DIR = path.join(HOME, '.agents-system');
 const USER_DIR = path.join(HOME, '.agents');
 const AGENTS_BIN = fileURLToPath(new URL('../dist/index.js', import.meta.url));
+const INSTALL_HELPER_SCRIPT = fileURLToPath(new URL('./install-helper.js', import.meta.url));
+
+function installKeychainHelper() {
+  if (process.platform !== 'darwin') return;
+  if (!fs.existsSync(INSTALL_HELPER_SCRIPT)) return;
+  // Sub-process so a hard failure (codesign / spctl missing on a weird host)
+  // can't take down the rest of postinstall. install-helper.js stays silent
+  // on no-op and emits one stdout line on success.
+  spawnSync(process.execPath, [INSTALL_HELPER_SCRIPT], { stdio: 'inherit' });
+}
 
 function shellQuote(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
@@ -24,6 +35,7 @@ const isGlobalInstall = process.env.npm_config_global || process.argv.includes('
 if (!isGlobalInstall) {
   // Still create user directories for local installs
   fs.mkdirSync(USER_DIR, { recursive: true, mode: 0o700 });
+  installKeychainHelper();
   console.log(`
 agents-cli installed locally.
 To complete setup, run: npx agents setup
@@ -36,6 +48,10 @@ fs.mkdirSync(SHIMS_DIR, { recursive: true });
 fs.mkdirSync(SYSTEM_DIR, { recursive: true });
 fs.mkdirSync(USER_DIR, { recursive: true, mode: 0o700 });
 
+// Copy the signed macOS Keychain helper to a stable user path so its trusted-app
+// ACLs survive future npm publishes (which re-sign the bundle).
+installKeychainHelper();
+
 // One-shot idempotent migrations
 function runMigrations() {
   // 1. Move agents.yaml from system to user repo