@phnx-labs/agents-cli 1.20.12 → 1.20.14

package/dist/commands/wallet.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `agents wallet` — a device-local credit-card vault backed by macOS Keychain.
+ *
+ * UX intent matches Apple Wallet: list cards freely (no biometric), reveal
+ * a card with Touch ID. Card numbers never leave the device. This is NOT
+ * Apple Pay — we store the real PAN, not a network DPAN, and do not generate
+ * per-transaction cryptograms. The help text reflects this.
+ *
+ * Bundle layout:
+ *   ~/.agents/wallet/cards.json                   metadata (id, last4, brand, exp)
+ *   agents-cli.secrets.wallet.<id>                JSON {pan, cvc, cardholder}
+ */
+import type { Command } from 'commander';
+export declare function registerWalletCommands(program: Command): void;

package/dist/commands/wallet.js

@@ -0,0 +1,199 @@
+/**
+ * `agents wallet` — a device-local credit-card vault backed by macOS Keychain.
+ *
+ * UX intent matches Apple Wallet: list cards freely (no biometric), reveal
+ * a card with Touch ID. Card numbers never leave the device. This is NOT
+ * Apple Pay — we store the real PAN, not a network DPAN, and do not generate
+ * per-transaction cryptograms. The help text reflects this.
+ *
+ * Bundle layout:
+ *   ~/.agents/wallet/cards.json                   metadata (id, last4, brand, exp)
+ *   agents-cli.secrets.wallet.<id>                JSON {pan, cvc, cardholder}
+ */
+import chalk from 'chalk';
+import { addCard, detectBrand, isValidLuhn, listCards, removeCard, renameCard, showCard, } from '../lib/wallet/index.js';
+import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
+import { setHelpSections } from '../lib/help.js';
+function brandLabel(b) {
+    switch (b) {
+        case 'visa': return 'Visa';
+        case 'mastercard': return 'Mastercard';
+        case 'amex': return 'American Express';
+        case 'discover': return 'Discover';
+        case 'diners': return 'Diners Club';
+        case 'jcb': return 'JCB';
+        case 'unionpay': return 'UnionPay';
+        default: return 'Card';
+    }
+}
+function formatExp(month, year) {
+    return `${month}/${year.slice(-2)}`;
+}
+function renderRow(c) {
+    const nick = c.nickname.padEnd(24);
+    const brand = brandLabel(c.brand).padEnd(18);
+    const last4 = `•••• ${c.last4}`.padEnd(10);
+    const exp = formatExp(c.exp_month, c.exp_year);
+    return `  ${chalk.cyan(nick)} ${brand} ${last4} ${chalk.gray('exp ' + exp)}  ${chalk.gray(c.id)}`;
+}
+async function promptString(message, validate) {
+    const { input } = await import('@inquirer/prompts');
+    return await input({ message, validate });
+}
+async function promptSecret(message) {
+    const { password } = await import('@inquirer/prompts');
+    return await password({ message, mask: true });
+}
+function requireTTY(action) {
+    if (!isInteractiveTerminal()) {
+        throw new Error(`'agents wallet ${action}' requires an interactive terminal.`);
+    }
+}
+export function registerWalletCommands(program) {
+    const cmd = program
+        .command('wallet')
+        .description('Device-local credit-card vault backed by macOS Keychain (Touch ID required to reveal). ' +
+        'Encrypted at rest, never leaves your device. Not Apple Pay — stores real PANs, no tokenization.');
+    setHelpSections(cmd, {
+        examples: `
+      $ agents wallet add                              # interactive: PAN, CVC, expiry, nickname
+      $ agents wallet list                             # last 4 only, no Touch ID prompt
+      $ agents wallet show personal-amex               # Touch ID required, reveals full card
+      $ agents wallet rename personal-amex "Travel"
+      $ agents wallet remove personal-amex
+    `,
+    });
+    cmd
+        .command('add')
+        .description('Add a card to the vault. Interactive prompt for PAN, CVC, expiry, cardholder, nickname.')
+        .option('--nickname <name>', 'Set the nickname non-interactively (still prompts for PAN/CVC)')
+        .option('--stdin-json', 'Read all fields as a JSON object on stdin (for IPC callers). Emits the new card metadata as JSON to stdout.')
+        .action(async (opts) => {
+        try {
+            if (opts.stdinJson) {
+                const raw = await new Promise((resolve, reject) => {
+                    const chunks = [];
+                    process.stdin.on('data', (c) => {
+                        chunks.push(typeof c === 'string' ? Buffer.from(c) : c);
+                    });
+                    process.stdin.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
+                    process.stdin.on('error', reject);
+                });
+                const input = JSON.parse(raw);
+                const meta = addCard(input);
+                process.stdout.write(JSON.stringify({ card: meta }) + '\n');
+                return;
+            }
+            requireTTY('add');
+            const pan = (await promptSecret('Card number')).replace(/\s+/g, '');
+            if (!/^\d+$/.test(pan))
+                throw new Error('PAN must contain only digits.');
+            if (!isValidLuhn(pan))
+                throw new Error('PAN failed Luhn checksum — typo?');
+            const brand = detectBrand(pan);
+            console.log(chalk.gray(`Detected: ${brandLabel(brand)} •••• ${pan.slice(-4)}`));
+            const exp_month = await promptString('Expiration month (MM)', (v) => {
+                const n = Number(v);
+                return Number.isInteger(n) && n >= 1 && n <= 12 ? true : 'Month must be 1-12';
+            });
+            const exp_year = await promptString('Expiration year (YY or YYYY)', (v) => {
+                const d = v.replace(/\D/g, '');
+                return d.length === 2 || d.length === 4 ? true : 'Year must be 2 or 4 digits';
+            });
+            const cvc = (await promptSecret('CVC')).replace(/\s+/g, '');
+            if (!/^\d{3,4}$/.test(cvc))
+                throw new Error('CVC must be 3 or 4 digits.');
+            const cardholder = await promptString('Cardholder name (as printed)');
+            const nickname = opts.nickname?.trim() || await promptString('Nickname (e.g. Personal Amex)', (v) => v.trim() ? true : 'Required');
+            const meta = addCard({ nickname, pan, cvc, cardholder, exp_month, exp_year });
+            console.log(chalk.green(`Added ${brandLabel(meta.brand)} •••• ${meta.last4} as '${meta.nickname}' (id: ${meta.id})`));
+        }
+        catch (err) {
+            if (isPromptCancelled(err))
+                return;
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    cmd
+        .command('list')
+        .alias('ls')
+        .description('List stored cards (metadata only — last 4, brand, expiry). No biometric prompt.')
+        .option('--json', 'Emit JSON to stdout')
+        .action((opts) => {
+        try {
+            const cards = listCards();
+            if (opts.json) {
+                process.stdout.write(JSON.stringify({ cards }, null, 2) + '\n');
+                return;
+            }
+            if (cards.length === 0) {
+                console.log(chalk.gray('No cards in wallet. Try: agents wallet add'));
+                return;
+            }
+            console.log(chalk.bold(`  ${'NICKNAME'.padEnd(24)} ${'BRAND'.padEnd(18)} ${'LAST4'.padEnd(10)} EXP        ID`));
+            for (const c of cards)
+                console.log(renderRow(c));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    cmd
+        .command('show <id>')
+        .description('Reveal a card. Touch ID required. Argument is a card id or nickname.')
+        .option('--json', 'Emit JSON to stdout (still triggers Touch ID)')
+        .action((id, opts) => {
+        try {
+            const full = showCard(id);
+            if (opts.json) {
+                process.stdout.write(JSON.stringify(full, null, 2) + '\n');
+                return;
+            }
+            console.log();
+            console.log(chalk.bold(`  ${full.nickname}`));
+            console.log(`  ${chalk.gray('Brand     ')} ${brandLabel(full.brand)}`);
+            console.log(`  ${chalk.gray('Number    ')} ${full.pan.match(/.{1,4}/g)?.join(' ') ?? full.pan}`);
+            console.log(`  ${chalk.gray('CVC       ')} ${full.cvc}`);
+            console.log(`  ${chalk.gray('Expires   ')} ${formatExp(full.exp_month, full.exp_year)}`);
+            console.log(`  ${chalk.gray('Holder    ')} ${full.cardholder}`);
+            console.log();
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    cmd
+        .command('remove <id>')
+        .alias('rm')
+        .description('Remove a card from the vault. Argument is a card id or nickname.')
+        .action((id) => {
+        try {
+            const meta = removeCard(id);
+            if (!meta) {
+                console.error(chalk.red(`No card found matching '${id}'.`));
+                process.exit(1);
+            }
+            console.log(chalk.green(`Removed '${meta.nickname}' (${brandLabel(meta.brand)} •••• ${meta.last4}).`));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    cmd
+        .command('rename <id> <new-nickname>')
+        .description('Rename a card. Argument is the current id or nickname.')
+        .action((id, newNickname) => {
+        try {
+            const meta = renameCard(id, newNickname);
+            console.log(chalk.green(`Renamed to '${meta.nickname}'.`));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+}

package/dist/index.js

@@ -78,7 +78,7 @@ import { registerRunCommand } from './commands/exec.js';
 import { registerModelsCommand } from './commands/models.js';
 import { registerDefaultsCommands } from './commands/defaults.js';
 import { registerPruneCommand } from './commands/prune.js';
-import { registerTrashCommands } from './commands/trash.js';
+import { registerTrashCommands, registerRestoreCommand } from './commands/trash.js';
 import { registerDoctorCommand } from './commands/doctor.js';
 import { registerSubagentsCommands } from './commands/subagents.js';
 import { registerPluginsCommands } from './commands/plugins.js';
@@ -93,6 +93,7 @@ import { registerBrowserCommand } from './commands/browser.js';
 import { registerComputerCommand } from './commands/computer.js';
 import { registerProfilesCommands } from './commands/profiles.js';
 import { registerSecretsCommands } from './commands/secrets.js';
+import { registerWalletCommands } from './commands/wallet.js';
 import { registerHelperCommand } from './commands/helper.js';
 import { registerFactoryCommands } from './commands/factory.js';
 import { registerUsageCommand } from './commands/usage.js';
@@ -655,6 +656,7 @@ registerDefaultsCommands(program);
 registerModelsCommand(program);
 registerPruneCommand(program);
 registerTrashCommands(program);
+registerRestoreCommand(program);
 registerDoctorCommand(program);
 // Deprecated 'exec' alias for 'run'
 program
@@ -669,6 +671,7 @@ program
 });
 registerProfilesCommands(program);
 registerSecretsCommands(program);
+registerWalletCommands(program);
 registerHelperCommand(program);
 registerBetaCommands(program);
 registerSyncCommand(program);

package/dist/lib/agents.js

@@ -90,41 +90,44 @@ function findInPath(command) {
     return null;
 }
 /** Grok-specific binary resolution.
- * Grok does not live in node_modules/.bin. Its versioned binaries live in
- * ~/.grok/downloads/ with names like `grok-0.1.218-macos-aarch64`.
- * We still use the agents-cli version dir for *config isolation* via GROK_HOME.
+ * Grok does not live in node_modules/.bin. Its versioned binaries live in each
+ * managed version home under `.grok/downloads/`, so detection must not follow
+ * the host ~/.grok config symlink.
  */
 function resolveGrokBinary(version) {
-    const grokDownloads = path.join(HOME, '.grok', 'downloads');
-    if (!fs.existsSync(grokDownloads))
-        return null;
-    const entries = fs.readdirSync(grokDownloads);
-    // Prefer exact version match in filename
     if (version && version !== 'latest') {
-        const match = entries.find((e) => e.includes(version) && e.startsWith('grok-'));
-        if (match)
-            return path.join(grokDownloads, match);
-    }
-    // Fallback: the "current" symlink or the plain `grok-*` without version in name
-    const current = entries.find((e) => e === 'grok' || e.startsWith('grok-') && !e.match(/grok-\d/));
-    if (current)
-        return path.join(grokDownloads, current);
-    // Last resort: newest file by mtime
+        const binaryPath = getBinaryPath('grok', version);
+        if (fs.existsSync(binaryPath))
+            return binaryPath;
+        return null;
+    }
+    const resolvedVersion = resolveVersion('grok', process.cwd());
+    if (resolvedVersion) {
+        const binaryPath = getBinaryPath('grok', resolvedVersion);
+        if (fs.existsSync(binaryPath))
+            return binaryPath;
+    }
+    const grokVersionsDir = path.join(getVersionsDir(), 'grok');
+    if (!fs.existsSync(grokVersionsDir))
+        return null;
     let latest = null;
     let latestMtime = 0;
-    for (const e of entries) {
-        if (!e.startsWith('grok-'))
+    for (const entry of fs.readdirSync(grokVersionsDir, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const binaryPath = getBinaryPath('grok', entry.name);
+        if (!fs.existsSync(binaryPath))
             continue;
         try {
-            const stat = fs.statSync(path.join(grokDownloads, e));
+            const stat = fs.statSync(binaryPath);
             if (stat.mtimeMs > latestMtime) {
                 latestMtime = stat.mtimeMs;
-                latest = e;
+                latest = binaryPath;
             }
         }
         catch { }
     }
-    return latest ? path.join(grokDownloads, latest) : null;
+    return latest;
 }
 function splitCommandLine(command) {
     const args = [];
@@ -482,6 +485,44 @@ export const AGENTS = {
             rulesImports: false,
         },
     },
+    // Factory AI Droid CLI (`droid`) — agentic coding CLI from factory.ai.
+    // Install: `curl -fsSL https://app.factory.ai/cli | sh` (no npm package).
+    // Binary is NOT in node_modules/.bin — resolved via resolveDroidBinary().
+    // Config: `~/.factory/` (settings.json, mcp.json, droids/, commands/).
+    // Memory: native AGENTS.md. Subagents = custom droids (top-level .md files
+    // in ~/.factory/droids/). Config isolation rides the ~/.factory symlink
+    // switch (no FACTORY_HOME env var exists). Headless: `droid exec "<prompt>"`
+    // with --auto low|medium|high, -o stream-json, -m <model>, -r <effort>.
+    droid: {
+        id: 'droid',
+        name: 'Droid',
+        color: 'yellowBright',
+        cliCommand: 'droid',
+        npmPackage: '',
+        installScript: 'curl -fsSL https://app.factory.ai/cli | sh',
+        configDir: path.join(HOME, '.factory'),
+        commandsDir: path.join(HOME, '.factory', 'commands'),
+        commandsSubdir: 'commands',
+        skillsDir: '', // no skills concept
+        hooksDir: 'hooks',
+        instructionsFile: 'AGENTS.md',
+        format: 'markdown',
+        variableSyntax: '$ARGUMENTS',
+        supportsHooks: false,
+        capabilities: {
+            hooks: false,
+            mcp: true,
+            allowlist: false,
+            skills: false,
+            commands: true,
+            plugins: false,
+            subagents: true,
+            rules: { file: 'AGENTS.md' },
+            workflows: false,
+            modes: ['plan', 'edit', 'auto', 'skip'],
+            rulesImports: false,
+        },
+    },
 };
 /** All registered agent IDs derived from the AGENTS registry. */
 export const ALL_AGENT_IDS = Object.keys(AGENTS);
@@ -1353,6 +1394,9 @@ export function getUserMcpConfigPath(agentId) {
         case 'grok':
             // grok mcp.json — exact field schema verified at first install
             return path.join(agent.configDir, 'mcp.json');
+        case 'droid':
+            // Factory AI Droid stores MCPs in ~/.factory/mcp.json
+            return path.join(agent.configDir, 'mcp.json');
         default:
             // Gemini and others use settings.json
             return path.join(agent.configDir, 'settings.json');
@@ -1387,6 +1431,8 @@ export function getMcpConfigPathForHome(agentId, home) {
             return path.join(home, '.gemini', 'antigravity-cli', 'mcp_config.json');
         case 'grok':
             return path.join(home, '.grok', 'config.toml');
+        case 'droid':
+            return path.join(home, '.factory', 'mcp.json');
         default:
             return path.join(home, agentConfigDirName(agentId), 'settings.json');
     }
@@ -1423,6 +1469,8 @@ function getProjectMcpConfigPath(agentId, cwd = process.cwd()) {
             return path.join(cwd, '.gemini', 'antigravity-cli', 'mcp_config.json');
         case 'grok':
             return path.join(cwd, '.grok', 'config.toml');
+        case 'droid':
+            return path.join(cwd, '.factory', 'mcp.json');
         default:
             return path.join(cwd, `.${agentId}`, 'settings.json');
     }

package/dist/lib/browser/ipc.d.ts

@@ -16,4 +16,11 @@ export declare class BrowserIPCServer {
     stop(): Promise<void>;
     private handleRequest;
 }
+/**
+ * Decide whether a running daemon is stale and must be restarted. A daemon
+ * is stale when it reports a concrete version that differs from this CLI's.
+ * `undefined`/`'unknown'` means the daemon is too old to answer the `version`
+ * action reliably — don't churn it on that ambiguous signal.
+ */
+export declare function shouldRestartStaleDaemon(daemonVersion: string | undefined, clientVersion: string): boolean;
 export declare function sendIPCRequest(request: IPCRequest, opts?: IPCRequestOptions): Promise<IPCResponse>;

package/dist/lib/browser/ipc.js

@@ -3,7 +3,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { IS_WINDOWS, ipcEndpoint } from '../platform/index.js';
 import { getHelpersDir } from '../state.js';
-import { startDaemon } from '../daemon.js';
+import { startDaemon, stopDaemon } from '../daemon.js';
 import { getCliVersion } from '../version.js';
 const SOCKET_NAME = 'browser.sock';
 export class BrowserDaemonNotRunningError extends Error {
@@ -453,41 +453,51 @@ export class BrowserIPCServer {
         }
     }
 }
-let versionCheckedThisProcess = false;
+let versionReconciledThisProcess = false;
 /**
- * Check the daemon's version against ours and warn loudly when they
- * differ. Fires at most once per CLI process — successive calls in the
- * same `agents browser ...` invocation are cheap. The whole reason this
- * code exists: a launchd-managed registry daemon kept serving stale code
- * to a dev-build CLI for an entire session and nothing surfaced it.
+ * Decide whether a running daemon is stale and must be restarted. A daemon
+ * is stale when it reports a concrete version that differs from this CLI's.
+ * `undefined`/`'unknown'` means the daemon is too old to answer the `version`
+ * action reliably — don't churn it on that ambiguous signal.
  */
-async function maybeWarnVersionMismatch() {
-    if (versionCheckedThisProcess)
+export function shouldRestartStaleDaemon(daemonVersion, clientVersion) {
+    if (!daemonVersion || daemonVersion === 'unknown')
+        return false;
+    return daemonVersion !== clientVersion;
+}
+/**
+ * Reconcile the running daemon's version with ours. If the daemon is serving
+ * stale code, stop and restart it so this request — and the rest of the
+ * session — runs the current build. Runs at most once per CLI process. The
+ * whole reason this exists: a launchd-managed daemon kept serving stale code
+ * to a dev-build CLI for an entire session and nothing surfaced it (#291).
+ */
+async function reconcileDaemonVersion(socketPath) {
+    if (versionReconciledThisProcess)
         return;
-    versionCheckedThisProcess = true;
+    versionReconciledThisProcess = true;
+    let daemon;
     try {
-        const resp = await sendRawIPCRequest({ action: 'version' });
-        const daemon = resp.version;
-        const client = getCliVersion();
-        if (!daemon || daemon === 'unknown' || daemon === client)
-            return;
-        process.stderr.write(`\nwarning: browser daemon is on ${daemon} but this CLI is on ${client}.\n` +
-            `         Run \`agents daemon restart\` to load the current code.\n\n`);
+        const resp = await sendRawIPCRequest({ action: 'version' }, { autoStartDaemon: false });
+        daemon = resp.version;
     }
     catch {
-        // daemon might be an older build that doesn't speak 'version' — that's
-        // itself a hint, but a noisy one. Stay silent on this path.
+        // Daemon unreachable or too old to speak 'version' — leave it alone.
+        return;
     }
+    const client = getCliVersion();
+    if (!shouldRestartStaleDaemon(daemon, client))
+        return;
+    process.stderr.write(`\nbrowser daemon was on ${daemon}, this CLI is on ${client} — restarting it to load current code.\n\n`);
+    stopDaemon();
+    startDaemon();
+    if (!(await isDaemonReachable())) {
+        await waitForSocket(socketPath, 6000);
+    }
+    await new Promise((r) => setTimeout(r, 300));
 }
 export async function sendIPCRequest(request, opts = {}) {
-    const result = await sendRawIPCRequest(request, opts);
-    // Run the version check after the user's request returns — keeps the
-    // critical path zero-overhead and ensures `start` doesn't get blocked
-    // on a daemon-restart warning that the user hasn't read yet.
-    if (request.action !== 'version') {
-        maybeWarnVersionMismatch().catch(() => { });
-    }
-    return result;
+    return sendRawIPCRequest(request, opts);
 }
 async function sendRawIPCRequest(request, opts = {}) {
     const socketPath = getSocketPath();
@@ -510,6 +520,12 @@ async function sendRawIPCRequest(request, opts = {}) {
         }
         await new Promise((r) => setTimeout(r, 300));
     }
+    // Before serving a real request, make sure the daemon isn't running stale
+    // code. Skips the internal `version` probe (avoids recursion) and callers
+    // that opt out of auto-start. No-ops once reconciled or when versions match.
+    if (request.action !== 'version' && autoStartDaemon) {
+        await reconcileDaemonVersion(socketPath);
+    }
     return new Promise((resolve, reject) => {
         const socket = net.createConnection(endpoint);
         let buffer = '';

package/dist/lib/capabilities.js

@@ -24,7 +24,13 @@ function compareVersions(a, b) {
     return 0;
 }
 function getCapability(agent, cap) {
-    return AGENTS[agent].capabilities[cap];
+    // Guard against unknown agent ids (e.g. a caller passing "claude@2.1.168"
+    // instead of "claude"). Without this, AGENTS[agent] is undefined and the
+    // property access throws an opaque TypeError instead of reporting false.
+    const def = AGENTS[agent];
+    if (!def)
+        return false;
+    return def.capabilities[cap];
 }
 /**
  * True when the agent supports the capability on at least some version.

package/dist/lib/command-skills.d.ts

@@ -7,6 +7,7 @@ export declare function shouldInstallCommandAsSkill(agent: AgentId, version: str
 export declare function commandSkillName(commandName: string): string;
 export declare function buildCommandSkillContent(commandName: string, sourcePath: string): string;
 export declare function skillSourceExists(skillName: string, skillSourceDirs: Array<string | null | undefined>): boolean;
+export declare function readSkillSourceCommandMarker(skillName: string, skillSourceDirs: Array<string | null | undefined>): string | null;
 export declare function installCommandSkillToVersion(agentDir: string, commandName: string, sourcePath: string, skillSourceDirs?: Array<string | null | undefined>): {
     success: boolean;
     skipped?: boolean;

package/dist/lib/command-skills.js

@@ -74,18 +74,34 @@ export function buildCommandSkillContent(commandName, sourcePath) {
         '',
     ].join('\n');
 }
-export function skillSourceExists(skillName, skillSourceDirs) {
-    return skillSourceDirs.some((dir) => {
+function findSkillSourceDir(skillName, skillSourceDirs) {
+    for (const dir of skillSourceDirs) {
         if (!dir)
-            return false;
+            continue;
         const candidate = path.join(dir, skillName);
-        return fs.existsSync(candidate) && fs.lstatSync(candidate).isDirectory();
-    });
+        if (fs.existsSync(candidate) && fs.lstatSync(candidate).isDirectory()) {
+            return candidate;
+        }
+    }
+    return null;
+}
+export function skillSourceExists(skillName, skillSourceDirs) {
+    return findSkillSourceDir(skillName, skillSourceDirs) !== null;
+}
+export function readSkillSourceCommandMarker(skillName, skillSourceDirs) {
+    const sourceDir = findSkillSourceDir(skillName, skillSourceDirs);
+    if (!sourceDir)
+        return null;
+    return readSkillCommandMarker(path.join(sourceDir, 'SKILL.md'));
 }
 export function installCommandSkillToVersion(agentDir, commandName, sourcePath, skillSourceDirs = []) {
     const skillName = commandSkillName(commandName);
-    if (skillSourceExists(skillName, skillSourceDirs)) {
-        return { success: false, skipped: true, error: `Skill '${skillName}' already exists` };
+    const existingSkillSource = findSkillSourceDir(skillName, skillSourceDirs);
+    if (existingSkillSource) {
+        const sourceMarker = readSkillCommandMarker(path.join(existingSkillSource, 'SKILL.md'));
+        if (sourceMarker !== commandName) {
+            return { success: true, skipped: true, error: `Skill '${skillName}' already exists` };
+        }
     }
     const skillsDir = safeJoin(agentDir, 'skills');
     const skillDir = safeJoin(skillsDir, skillName);

package/dist/lib/exec.d.ts

@@ -12,6 +12,29 @@ export type ExecMode = Mode;
  * boundary rather than silently picking a wrong code path.
  */
 export declare function normalizeMode(input: string | null | undefined): Mode;
+/**
+ * Detect the headless-plan stall footgun.
+ *
+ * A slash command (e.g. `/code:commit`) run headless under the IMPLICIT default
+ * `plan` mode hangs forever: plan is read-only, so the agent calls ExitPlanMode
+ * to start working, and in a headless run there is no TTY to approve it. The
+ * process just sits there. Callers use this to fail fast with a fix instead.
+ *
+ * Returns the offending command token (e.g. `/code:commit`) when the run should
+ * be blocked, else null. Guards are deliberately narrow:
+ *   - interactive runs / no prompt        -> not headless, never blocks
+ *   - explicit --mode (modeIsDefault false) -> respected; `--mode plan` is a
+ *     legitimate read-only command run and must not be blocked
+ *   - resolved mode is not `plan`          -> only plan stalls at ExitPlanMode
+ *   - prompt is not a slash command        -> natural-language read-only prompts
+ *     ("summarize commits") are a valid default-plan use and must not be blocked
+ */
+export declare function headlessPlanStallCommand(args: {
+    prompt: string | undefined;
+    interactive: boolean | undefined;
+    mode: string;
+    modeIsDefault: boolean;
+}): string | null;
 /**
  * Resolve a requested mode against an agent's capability table.
  *
@@ -45,11 +68,12 @@ export interface ExecOptions {
     version?: string;
     /** Omit to launch the CLI interactively -- no prompt, no --print, stdio fully inherited. */
     prompt?: string;
-    /** Force interactive mode even when a prompt is provided. */
+    /** Force interactive mode even when a prompt is provided. Wins over `headless`. */
     interactive?: boolean;
     mode: ExecMode;
     effort: ExecEffort;
     cwd?: string;
+    /** Force headless mode even when no prompt is provided (e.g. piping via stdin). */
     headless?: boolean;
     json?: boolean;
     model?: string;
@@ -59,6 +83,13 @@ export interface ExecOptions {
     verbose?: boolean;
     env?: Record<string, string>;
 }
+/**
+ * Resolve interactive vs headless. Explicit flags are definitive and win over
+ * inference: `--interactive` forces interactive, `--headless` forces headless.
+ * With neither flag, prompt presence decides (prompt -> headless, none -> interactive).
+ * `--interactive` takes precedence over `--headless`; the CLI layer rejects passing both.
+ */
+export declare function resolveInteractive(options: Pick<ExecOptions, 'interactive' | 'headless' | 'prompt'>): boolean;
 /** Parse an array of KEY=VALUE strings into an env record. Returns undefined for empty input. */
 export declare function parseExecEnv(entries: string[]): Record<string, string> | undefined;
 /**