@phnx-labs/agents-cli 1.19.2 → 1.20.3

package/dist/commands/cli.js

@@ -0,0 +1,244 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import chalk from 'chalk';
+import { confirm } from '@inquirer/prompts';
+import { listCliManifests, listCliStatus, resolveCliManifest, installCli, describeMethod, describeCheck, selectInstallMethod, isCliInstalled, } from '../lib/cli-resources.js';
+import { getUserAgentsDir } from '../lib/state.js';
+import { isPromptCancelled } from './utils.js';
+function userCliDir() {
+    return path.join(getUserAgentsDir(), 'cli');
+}
+/** Render the status table — one row per declared CLI. */
+function printStatus(rows) {
+    if (rows.length === 0) {
+        console.log(chalk.gray('No CLIs declared.'));
+        console.log(chalk.gray(`Create one with: agents cli add <name>`));
+        return;
+    }
+    const nameWidth = Math.max(4, ...rows.map((r) => r.manifest.name.length));
+    for (const row of rows) {
+        const status = row.installed
+            ? chalk.green('installed')
+            : chalk.yellow('missing');
+        const name = row.manifest.name.padEnd(nameWidth);
+        const source = chalk.gray(`[${row.manifest.source}]`);
+        const desc = row.manifest.description ? '  ' + chalk.gray(row.manifest.description) : '';
+        console.log(`  ${name}  ${status}  ${source}${desc}`);
+    }
+}
+export function registerCliCommands(program) {
+    const cliCmd = program
+        .command('cli')
+        .description('Declare and install host CLI binaries (gh, higgsfield, glab, ...)')
+        .addHelpText('after', `
+CLI manifests live in <repo>/cli/<name>.yaml and declare how to install a
+binary on the host. On a fresh machine, 'agents cli install' runs the first
+compatible method (npm > brew > script > binary) for every declared entry.
+
+Examples:
+  # See which declared CLIs are installed on this host
+  agents cli list
+
+  # Install everything that's missing
+  agents cli install
+
+  # Install one
+  agents cli install higgsfield
+
+  # Show the manifest detail
+  agents cli view higgsfield
+
+  # Exit 0 if all declared CLIs are installed (use in CI / setup scripts)
+  agents cli check
+
+When to use:
+  - After 'agents pull' on a new machine, to materialize host binaries
+  - In a team setup: commit cli/ entries so teammates get the same toolchain
+`);
+    cliCmd
+        .command('list')
+        .description('Show all declared CLIs and whether each is installed on this host')
+        .action(() => {
+        const { statuses, errors } = listCliStatus(process.cwd());
+        printStatus(statuses);
+        for (const err of errors) {
+            console.log(chalk.red(`  parse error: ${err.file}: ${err.reason}`));
+        }
+    });
+    cliCmd
+        .command('check')
+        .description('Exit 0 if every declared CLI is installed, 1 otherwise')
+        .action(() => {
+        const { statuses, errors } = listCliStatus(process.cwd());
+        const missing = statuses.filter((s) => !s.installed);
+        if (errors.length > 0) {
+            for (const err of errors) {
+                console.error(chalk.red(`parse error: ${err.file}: ${err.reason}`));
+            }
+            process.exit(1);
+        }
+        if (missing.length === 0) {
+            console.log(chalk.green(`All ${statuses.length} declared CLI(s) installed.`));
+            return;
+        }
+        console.log(chalk.yellow(`Missing: ${missing.map((s) => s.manifest.name).join(', ')}`));
+        process.exit(1);
+    });
+    cliCmd
+        .command('install [name]')
+        .description('Install one (by name) or all missing declared CLIs')
+        .option('-y, --yes', 'skip the confirmation prompt')
+        .option('--dry-run', 'print install commands without executing them')
+        .option('--force', 'reinstall even when the check command currently passes')
+        .action(async (nameArg, opts) => {
+        let targets;
+        if (nameArg) {
+            const manifest = resolveCliManifest(nameArg, process.cwd());
+            if (!manifest) {
+                console.error(chalk.red(`No CLI manifest named "${nameArg}".`));
+                console.error(chalk.gray(`Looked in: ${userCliDir()}`));
+                process.exit(1);
+            }
+            targets = [manifest];
+        }
+        else {
+            const { manifests, errors } = listCliManifests(process.cwd());
+            for (const err of errors) {
+                console.error(chalk.red(`parse error: ${err.file}: ${err.reason}`));
+            }
+            if (manifests.length === 0) {
+                console.log(chalk.gray('No CLIs declared. Nothing to install.'));
+                return;
+            }
+            targets = manifests;
+        }
+        // Filter out already-installed unless --force
+        const work = targets.filter((m) => opts.force || !isCliInstalled(m));
+        if (work.length === 0) {
+            console.log(chalk.green(`All ${targets.length} declared CLI(s) already installed.`));
+            return;
+        }
+        // Preview + confirm
+        console.log(chalk.bold('\nWill install:'));
+        for (const m of work) {
+            const method = selectInstallMethod(m);
+            const action = method ? describeMethod(method) : chalk.red('no compatible install method');
+            console.log(`  ${chalk.cyan(m.name.padEnd(20))} ${chalk.gray(action)}`);
+        }
+        console.log('');
+        if (!opts.yes && !opts.dryRun) {
+            try {
+                const proceed = await confirm({ message: 'Proceed?', default: true });
+                if (!proceed) {
+                    console.log(chalk.gray('Cancelled.'));
+                    return;
+                }
+            }
+            catch (err) {
+                if (isPromptCancelled(err)) {
+                    console.log(chalk.gray('Cancelled.'));
+                    return;
+                }
+                throw err;
+            }
+        }
+        // Execute
+        let failures = 0;
+        for (const m of work) {
+            console.log(chalk.bold(`\n→ ${m.name}`));
+            const result = installCli(m, { dryRun: opts.dryRun });
+            if (result.output)
+                console.log(chalk.gray(result.output));
+            if (result.error) {
+                console.log(chalk.red(`  ${result.error}`));
+                failures++;
+                continue;
+            }
+            if (opts.dryRun)
+                continue;
+            if (result.installed) {
+                console.log(chalk.green(`  installed (${describeMethod(result.method)})`));
+                if (m.postInstall) {
+                    console.log(chalk.gray(m.postInstall.trim().split('\n').map((l) => '  ' + l).join('\n')));
+                }
+            }
+            else {
+                console.log(chalk.yellow(`  install command ran but \`${describeCheck(m.check)}\` still fails — check the output above`));
+                failures++;
+            }
+        }
+        if (failures > 0)
+            process.exit(1);
+    });
+    cliCmd
+        .command('view <name>')
+        .description('Show the parsed manifest detail')
+        .action((name) => {
+        const manifest = resolveCliManifest(name, process.cwd());
+        if (!manifest) {
+            console.error(chalk.red(`No CLI manifest named "${name}".`));
+            process.exit(1);
+        }
+        console.log(chalk.bold.cyan(manifest.name));
+        if (manifest.description)
+            console.log('  ' + chalk.gray(manifest.description));
+        if (manifest.homepage)
+            console.log('  ' + chalk.gray(manifest.homepage));
+        console.log('  ' + chalk.gray(`source: ${manifest.source}`));
+        console.log('  ' + chalk.gray(`file: ${manifest.path}`));
+        console.log('');
+        console.log(chalk.bold('  check'));
+        console.log('    ' + describeCheck(manifest.check));
+        console.log('');
+        console.log(chalk.bold('  install methods'));
+        for (const method of manifest.install) {
+            console.log('    ' + describeMethod(method));
+        }
+        if (manifest.postInstall) {
+            console.log('');
+            console.log(chalk.bold('  post_install'));
+            for (const line of manifest.postInstall.trim().split('\n')) {
+                console.log('    ' + line);
+            }
+        }
+        console.log('');
+        console.log(`  status: ${isCliInstalled(manifest) ? chalk.green('installed') : chalk.yellow('missing')}`);
+    });
+    cliCmd
+        .command('add <name>')
+        .description('Scaffold a new manifest at ~/.agents/cli/<name>.yaml')
+        .option('--npm <pkg>', 'declare an npm install method')
+        .option('--brew <formula>', 'declare a brew install method')
+        .option('--script <url>', 'declare a curl|sh install method')
+        .option('--description <text>', 'one-line description')
+        .option('--homepage <url>', 'project homepage')
+        .action((name, opts) => {
+        const dir = userCliDir();
+        fs.mkdirSync(dir, { recursive: true });
+        const target = path.join(dir, `${name}.yaml`);
+        if (fs.existsSync(target)) {
+            console.error(chalk.red(`Already exists: ${target}`));
+            process.exit(1);
+        }
+        const methods = [];
+        if (opts.npm)
+            methods.push(`  - npm: "${opts.npm}"`);
+        if (opts.brew)
+            methods.push(`  - brew: ${opts.brew}`);
+        if (opts.script)
+            methods.push(`  - script: ${opts.script}`);
+        if (methods.length === 0) {
+            methods.push(`  - npm: "${name}"`);
+        }
+        const lines = [
+            `name: ${name}`,
+            ...(opts.description ? [`description: ${opts.description}`] : []),
+            ...(opts.homepage ? [`homepage: ${opts.homepage}`] : []),
+            `check: ${name} --version`,
+            `install:`,
+            ...methods,
+        ];
+        fs.writeFileSync(target, lines.join('\n') + '\n');
+        console.log(chalk.green(`Created ${target}`));
+    });
+}

package/dist/commands/cloud.js

@@ -68,7 +68,7 @@ Examples:
   agents cloud run "add pytest fixtures for the new billing module" --provider codex --env env_a1b2c3 --agent codex --timeout 30m
 
   # Factory pod targeting a specific computer (Droid)
-  agents cloud run "QA the new onboarding flow end-to-end" --provider factory --computer mac-mini-1 --agent droid
+  agents cloud run "QA the new onboarding flow end-to-end" --provider factory --computer linux-vm-1 --agent droid
 
   # See every cloud task you've dispatched (most recent first)
   agents cloud list

package/dist/commands/commands.js

@@ -9,9 +9,9 @@ import { cloneRepo } from '../lib/git.js';
 import { discoverCommands, resolveCommandSource, installCommandCentrally, listCentralCommands, listInstalledCommandsWithScope, getCommandInfo, diffVersionCommands, iterCommandsCapableVersions, removeCommandFromVersion, } from '../lib/commands.js';
 import { getCommandsDir } from '../lib/state.js';
 import { showResourceList, buildTargetsSection, } from './resource-view.js';
-import { getGlobalDefault, resolveVersionAlias, syncResourcesToVersion, promptAgentVersionSelection, getVersionHomePath, resolveAgentVersionTargets, } from '../lib/versions.js';
+import { listInstalledVersions, getGlobalDefault, resolveVersionAlias, syncResourcesToVersion, promptAgentVersionSelection, getVersionHomePath, resolveInstalledAgentTargets, } from '../lib/versions.js';
 import { recordVersionResources } from '../lib/state.js';
-import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, promptRemovalTargets, } from './utils.js';
+import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, promptRemovalTargets, resolveAgentTargetsAutoInstalling, } from './utils.js';
 /** Register the `agents commands` command tree (list, add, remove, sync, prune, view). */
 export function registerCommandsCommands(program) {
     const commandsCmd = program
@@ -214,13 +214,17 @@ Examples:
             let selectedAgents;
             let versionSelections;
             if (options.agents) {
-                const result = resolveAgentVersionTargets(options.agents, ALL_AGENT_IDS);
+                const result = await resolveAgentTargetsAutoInstalling(options.agents, ALL_AGENT_IDS, { yes: options.yes });
+                if (!result) {
+                    console.log(chalk.gray('Cancelled.'));
+                    return;
+                }
                 selectedAgents = result.selectedAgents;
                 versionSelections = result.versionSelections;
             }
             else {
                 const result = await promptAgentVersionSelection(ALL_AGENT_IDS, {
-                    skipPrompts: options.yes || !isInteractiveTerminal(),
+                    skipPrompts: options.yes,
                 });
                 selectedAgents = result.selectedAgents;
                 versionSelections = result.versionSelections;
@@ -334,11 +338,24 @@ Examples:
                 console.log(chalk.yellow(`  Command '${cmdName}' not found in any version.`));
                 continue;
             }
-            // Filter by --agents if specified
+            // Filter by --agents if specified. Routes through resolveInstalledAgentTargets
+            // so the same selector syntax used everywhere else (agent, agent@default,
+            // agent@x.y.z, agent@all, literal all) works here too.
             let availableTargets = cmdInfo.targets;
             if (options?.agents) {
-                const requestedAgents = new Set(options.agents.split(','));
-                availableTargets = availableTargets.filter((t) => requestedAgents.has(t.agent));
+                const requestedTargets = resolveInstalledAgentTargets(options.agents, ALL_AGENT_IDS);
+                const requested = new Set();
+                for (const aid of requestedTargets.directAgents) {
+                    for (const ver of listInstalledVersions(aid)) {
+                        requested.add(`${aid}@${ver}`);
+                    }
+                }
+                for (const [aid, versions] of requestedTargets.versionSelections) {
+                    for (const ver of versions) {
+                        requested.add(`${aid}@${ver}`);
+                    }
+                }
+                availableTargets = availableTargets.filter((t) => requested.has(`${t.agent}@${t.version}`));
             }
             if (availableTargets.length === 0) {
                 console.log(chalk.yellow(`  Command '${cmdName}' not found in specified agents.`));
@@ -383,17 +400,17 @@ Examples:
         .action(() => {
         console.error(chalk.red('"agents commands sync" is gone.'));
         console.error(chalk.gray('Sync runs automatically when you launch the agent.'));
-        console.error(chalk.gray('To remove orphans, use:  agents prune commands'));
+        console.error(chalk.gray('To remove orphans, use:  agents prune cleanup commands'));
         process.exit(1);
     });
-    // `commands prune` moved to the top-level `agents prune` command.
+    // `commands prune` moved to the top-level `agents prune cleanup` command.
     commandsCmd
         .command('prune', { hidden: true })
         .allowUnknownOption()
         .allowExcessArguments()
         .action(() => {
         console.error(chalk.red('"agents commands prune" moved.'));
-        console.error(chalk.gray('Use:  agents prune commands   (or `agents prune` for everything)'));
+        console.error(chalk.gray('Use:  agents prune cleanup commands   (or `agents prune cleanup` for everything)'));
         process.exit(1);
     });
     commandsCmd

package/dist/commands/computer.js

@@ -3,7 +3,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { registerCommandGroups } from '../lib/help.js';
-import { openComputerClient, resolveHelperApp, resolveHelperExec, resolveSocketPath, resolveLogPath, resolvePolicyPath, describeTransport, loadComputerAllowList, writeComputerPolicy, } from '../lib/computer-rpc.js';
+import { openComputerClient, resolveHelperApp, resolveHelperExec, resolveSocketPath, resolveLogPath, resolvePolicyPath, resolvePeersPath, describeTransport, loadComputerAllowList, loadDefaultPeers, writeComputerPolicy, writeComputerPeers, } from '../lib/computer-rpc.js';
 // Help groups — mirror `agents browser` so the mental model carries over.
 const COMPUTER_HELP_GROUPS = [
     { title: 'Installation', names: ['install-helper'] },
@@ -46,6 +46,8 @@ function registerStatusCommand(program) {
         const previewParts = allowed.slice(0, 5);
         const previewSuffix = allowed.length > 5 ? ` (+${allowed.length - 5} more)` : '';
         console.log(`policy:    ${allowed.length} app${allowed.length === 1 ? '' : 's'} allowed${allowed.length > 0 ? `: ${previewParts.join(', ')}${previewSuffix}` : ''}`);
+        const callers = loadDefaultPeers();
+        console.log(`peers:     ${callers.length} caller${callers.length === 1 ? '' : 's'} (peer-auth on socket)`);
         if (!installed) {
             console.log('');
             console.log('Run:  agents computer install-helper');
@@ -284,6 +286,15 @@ function registerStartCommand(program) {
             console.log(`        add to ~/.agents/permissions/groups/<name>.yaml under allow:`);
             console.log(`          - "Computer(com.apple.finder)"`);
         }
+        // Peer-auth allow list — which caller executables may connect to
+        // the socket. Default: this CLI's Node binary, plus Rush.app if
+        // installed. A `nc -U socket` from a malicious npm postinstall has
+        // a different exec path and gets refused at accept().
+        const callers = loadDefaultPeers();
+        writeComputerPeers(callers);
+        console.log(`peers:  ${callers.length} caller${callers.length === 1 ? '' : 's'} allowed (${resolvePeersPath()})`);
+        for (const p of callers)
+            console.log(`        ${p}`);
         // Bootout first to clear any prior registration. Best-effort.
         try {
             execFileSync('/bin/launchctl', ['bootout', domain, plistPath], { stdio: 'pipe' });
@@ -356,6 +367,12 @@ function registerReloadCommand(program) {
         const allowed = loadComputerAllowList();
         writeComputerPolicy(allowed);
         console.log(`policy: ${allowed.length} app${allowed.length === 1 ? '' : 's'} allowed (${resolvePolicyPath()})`);
+        // Rewrite peers list too — an upgrade of the npm-global CLI moves
+        // its node path; without this the reloaded daemon would reject the
+        // very binary that just signaled it.
+        const callers = loadDefaultPeers();
+        writeComputerPeers(callers);
+        console.log(`peers:  ${callers.length} caller${callers.length === 1 ? '' : 's'} allowed (${resolvePeersPath()})`);
         // Resolve the daemon's pid via `launchctl list <label>`. The plist
         // output includes a "PID" key when the service is running.
         const uid = process.getuid?.();

package/dist/commands/doctor.d.ts

@@ -15,7 +15,7 @@
  *      unified diff body for each divergent file. Mirrors the resolution that
  *      the shim drives at runtime: project > user > system > extras.
  *
- * Read-only: doctor never mutates state. Run `agents prune` to act on orphan
+ * Read-only: doctor never mutates state. Run `agents prune cleanup` to act on orphan
  * readouts, or just launch the agent to apply pending sync.
  */
 import type { Command } from 'commander';

package/dist/commands/doctor.js

@@ -114,7 +114,7 @@ function renderOverviewText(clis, syncRows, orphanRows) {
             const label = `${AGENT_NAMES[row.agent] || row.agent}@${row.version}`;
             console.log(`  ${chalk.yellow('warn ')}  ${label}  ${chalk.gray(parts.join(', '))}`);
         }
-        console.log(chalk.gray('  Run `agents prune` to remove.'));
+        console.log(chalk.gray('  Run `agents prune cleanup` to remove.'));
     }
 }
 function parseTargetArg(arg) {
@@ -310,7 +310,7 @@ function renderTargetText(report, options) {
     }
     else {
         console.log(`  Verdict: ${verdictParts.join(', ')}.`);
-        console.log(chalk.gray(`  Run \`agents sync --agent ${report.agent} --agent-version ${report.version}\` to reconcile, or \`agents prune\` to drop extras.`));
+        console.log(chalk.gray(`  Run \`agents sync --agent ${report.agent} --agent-version ${report.version}\` to reconcile, or \`agents prune cleanup\` to drop extras.`));
     }
 }
 // ─── command registration ────────────────────────────────────────────────────

package/dist/commands/exec.js

@@ -6,20 +6,13 @@
  * injection, and multi-agent fallback chains for rate-limit resilience.
  */
 import chalk from 'chalk';
-import { buildExecCommand, parseExecEnv, execAgent, runWithFallback, AGENT_COMMANDS, } from '../lib/exec.js';
-import { profileExists, resolveProfileForRun } from '../lib/profiles.js';
 import { setHelpSections } from '../lib/help.js';
-import { readBundle, resolveBundleEnv, describeBundle } from '../lib/secrets/bundles.js';
-import { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, RUN_STRATEGIES, } from '../lib/rotate.js';
-import { getGlobalDefault, getVersionHomePath, resolveVersionAlias } from '../lib/versions.js';
-import { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion } from '../lib/plugins.js';
-import { parseWorkflowFrontmatter, resolveWorkflowRef } from '../lib/workflows.js';
+import { AGENTS } from '../lib/agents.js';
 import * as fs from 'fs';
 import * as path from 'path';
-const VALID_AGENTS = Object.keys(AGENT_COMMANDS);
 /** Type guard that narrows a string to a known AgentId. */
 function isValidAgent(agent) {
-    return VALID_AGENTS.includes(agent);
+    return agent in AGENTS;
 }
 /** Build a one-line banner describing which version the strategy picked. */
 function formatRotationBanner(result, verb = 'balanced') {
@@ -33,7 +26,7 @@ export function registerRunCommand(program) {
     const runCmd = program
         .command('run <agent> [prompt]')
         .description('Execute an agent. Pass a prompt for headless runs; omit it to launch the agent interactively.')
-        .option('-m, --mode <mode>', 'How much the agent can do: plan (read-only), edit (can write files), full (writes + all permissions)', 'plan')
+        .option('-m, --mode <mode>', 'How much the agent can do: plan (read-only), edit (can write files), auto (smart classifier auto-approves safe ops, prompts for risky), skip (bypass all permission prompts). \'full\' accepted as alias for skip.', 'plan')
         .option('-e, --effort <effort>', 'Reasoning effort: low | medium | high | xhigh | max | auto (claude and codex only)', 'auto')
         .option('--model <model>', 'Override the model directly (e.g., claude-opus-4-6)')
         .option('--env <key=value>', 'Pass environment variable to the agent (repeatable, e.g., --env DEBUG=1 --env API_KEY=xyz)', (val, prev) => [...prev, val], [])
@@ -73,8 +66,12 @@ export function registerRunCommand(program) {
       agents run claude "deploy the worker" --secrets prod --mode edit
     `,
         notes: `
-      Modes:
-        plan  read-only       edit  can write files       full  writes + all permissions
+      Modes (not every agent supports every mode — check agents.yaml capabilities):
+        plan  read-only investigation; no writes, no shell side-effects
+        edit  may edit files; prompts for shell / risky operations
+        auto  smart classifier auto-approves safe ops, prompts for risky (claude, copilot)
+        skip  bypass every permission prompt (dangerously-skip-permissions)
+        Legacy 'full' is silently rewritten to 'skip'.
 
       Run strategy (set via --strategy or run.<agent>.strategy in agents.yaml):
         pinned     use the workspace/global pinned version (default)
@@ -88,6 +85,17 @@ export function registerRunCommand(program) {
     `,
     });
     runCmd.action(async (agentSpec, prompt, options) => {
+        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode }, { ALL_AGENT_IDS }, { profileExists, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, RUN_STRATEGIES }, { getGlobalDefault, getVersionHomePath, resolveVersionAlias }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef },] = await Promise.all([
+            import('../lib/exec.js'),
+            import('../lib/agents.js'),
+            import('../lib/profiles.js'),
+            import('../lib/secrets/bundles.js'),
+            import('../lib/rotate.js'),
+            import('../lib/versions.js'),
+            import('../lib/plugins.js'),
+            import('../lib/workflows.js'),
+        ]);
+        const isValidAgent = (agent) => ALL_AGENT_IDS.includes(agent);
         // Parse agent@version
         const [rawAgent, rawVersion] = agentSpec.split('@');
         let agent;
@@ -195,7 +203,7 @@ export function registerRunCommand(program) {
         }
         else {
             console.error(chalk.red(`Unknown agent: ${rawAgent}`));
-            console.error(chalk.gray(`Available agents: ${VALID_AGENTS.join(', ')}`));
+            console.error(chalk.gray(`Available agents: ${ALL_AGENT_IDS.join(', ')}`));
             console.error(chalk.gray(`Or add a profile: agents profiles add <name>`));
             process.exit(1);
         }
@@ -244,9 +252,21 @@ export function registerRunCommand(program) {
                 }
             }
         }
+        // Accept the four canonical modes plus 'full' as a permanent silent
+        // alias for 'skip' (rewritten downstream by normalizeMode in exec.ts).
         const mode = options.mode;
-        if (!['plan', 'edit', 'full'].includes(mode)) {
-            console.error(chalk.red(`Invalid mode: ${mode}. Use 'plan', 'edit', or 'full'`));
+        if (!['plan', 'edit', 'auto', 'skip', 'full'].includes(mode)) {
+            console.error(chalk.red(`Invalid mode: ${mode}. Use plan, edit, auto, or skip ('full' accepted as alias for skip).`));
+            process.exit(1);
+        }
+        // Surface capability errors as a clean CLI message instead of a stack
+        // trace from buildExecCommand. resolveMode degrades 'auto' silently and
+        // throws on unsupported 'plan'/'skip' — we catch and pretty-print.
+        try {
+            resolveMode(agent, normalizeMode(mode));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
             process.exit(1);
         }
         const effort = options.effort;
@@ -268,7 +288,7 @@ export function registerRunCommand(program) {
         let secretsEnv = {};
         for (const bundleName of options.secrets) {
             try {
-                const bundle = readBundle(bundleName);
+                const { bundle, env: bundleEnv } = readAndResolveBundleEnv(bundleName, { caller: `agent ${agent}` });
                 const entries = describeBundle(bundle);
                 const counts = {};
                 for (const e of entries) {
@@ -276,7 +296,7 @@ export function registerRunCommand(program) {
                 }
                 const breakdown = Object.entries(counts).map(([k, v]) => `${v} ${k}`).join(', ');
                 console.log(chalk.gray(`[secrets] Resolved ${bundleName}: ${entries.length} keys (${breakdown})`));
-                secretsEnv = { ...secretsEnv, ...resolveBundleEnv(bundle, { caller: `agent ${agent}` }) };
+                secretsEnv = { ...secretsEnv, ...bundleEnv };
             }
             catch (err) {
                 console.error(chalk.red(err.message));
@@ -328,7 +348,7 @@ export function registerRunCommand(program) {
                 const [fbAgent, fbVersion] = entry.split('@');
                 if (!isValidAgent(fbAgent)) {
                     console.error(chalk.red(`Unknown fallback agent: ${fbAgent}`));
-                    console.error(chalk.gray(`Available: ${VALID_AGENTS.join(', ')}`));
+                    console.error(chalk.gray(`Available: ${ALL_AGENT_IDS.join(', ')}`));
                     process.exit(1);
                 }
                 if (fbAgent === agent) {

package/dist/commands/factory.d.ts

@@ -1,19 +1,8 @@
 /**
- * Software Factory CLI -- thin client over `prix/factory/service`.
+ * Software Factory CLI — submits Linear issues to a remote orchestrator.
  *
- * One verb today:
- *
- *   agents factory submit <linear-ref>   POST /factory/submit
- *
- * Everything else (planner pod, worker dispatch, PR-merged/CI-failed
- * webhooks, retry caps, heartbeat reaper) lives server-side in
- * `agents/prix/factory/service/src/factory.ts`, driven by the
- * `factory-tick` k8s CronJob. The laptop is optional after submit.
- *
- * Future verbs (list / status / tail / cancel / message) are intentionally
- * deferred until the matching server endpoints land; they'll be thin
- * clients too. No supervisor, ledger, oracle, or `~/.agents/factory/`
- * registry on the laptop -- ever.
+ * Requires FACTORY_FLOOR_URL pointing at a Factory-compatible endpoint.
+ * Beta-gated; enable with `agents beta enable factory`.
  */
 import type { Command } from 'commander';
 export declare function registerFactoryCommands(program: Command): void;

package/dist/commands/factory.js

@@ -51,8 +51,8 @@ export function registerFactoryCommands(program) {
         .description('Software Factory -- submit Linear tickets to the cloud orchestrator.')
         .addHelpText('after', `
 Examples:
-  agents factory submit EXAMPLE-2451
-  agents factory submit https://linear.app/example/issue/EXAMPLE-2451
+  agents factory submit PROJ-123
+  agents factory submit https://linear.app/example/issue/PROJ-123
 `);
     factory.hook('preAction', () => {
         if (enabled)
@@ -63,7 +63,7 @@ Examples:
     });
     factory
         .command('submit <linear-ref>')
-        .description('Submit a Linear issue (EXAMPLE-123 or URL) to the Software Factory.')
+        .description('Submit a Linear issue (PROJ-123 or URL) to the Software Factory.')
         .option('--json', 'Output machine-readable JSON')
         .action(async (ref, opts) => {
         const result = await postFactorySubmit(ref);

package/dist/commands/feedback.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `agents feedback` — frictionless, in-CLI feedback. Opens a Discussion
+ * pre-filled with version + OS + agent inventory; falls back to printing the
+ * URL when no browser is available.
+ */
+import type { Command } from 'commander';
+export declare function registerFeedbackCommand(program: Command): void;