@phnx-labs/agents-cli 0.1.0 → 1.14.1

package/dist/commands/daemon.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Deprecated daemon commands.
+ *
+ * Registers the hidden `agents daemon` command tree as backward-compatible
+ * aliases for `agents routines` scheduler lifecycle commands. Scheduled
+ * for removal in v2.0.
+ */
 import type { Command } from 'commander';
+/** Register the deprecated `agents daemon` command tree. */
 export declare function registerDaemonCommands(program: Command): void;
-//# sourceMappingURL=daemon.d.ts.map

package/dist/commands/daemon.js

@@ -1,11 +1,21 @@
+/**
+ * Deprecated daemon commands.
+ *
+ * Registers the hidden `agents daemon` command tree as backward-compatible
+ * aliases for `agents routines` scheduler lifecycle commands. Scheduled
+ * for removal in v2.0.
+ */
+import { spawn } from 'child_process';
 import chalk from 'chalk';
 import * as path from 'path';
 import { startDaemon, stopDaemon, isDaemonRunning, readDaemonPid, readDaemonLog, runDaemon, } from '../lib/daemon.js';
 import { listJobs as listAllJobs } from '../lib/routines.js';
 import { JobScheduler } from '../lib/scheduler.js';
+/** Print a deprecation warning pointing to the replacement command. */
 function warnDeprecated(subcommand, replacement) {
     console.log(chalk.yellow(`\u26a0  'agents daemon ${subcommand}' is deprecated and will be removed in v2.0. Use '${replacement}' instead.\n`));
 }
+/** Register the deprecated `agents daemon` command tree. */
 export function registerDaemonCommands(program) {
     const daemonCmd = program
         .command('daemon', { hidden: true })
@@ -81,12 +91,11 @@ you never need to start it manually.
         .action(async (options) => {
         warnDeprecated('logs', 'agents routines scheduler-logs');
         if (options.follow) {
-            const { exec: execCb } = await import('child_process');
             const { getAgentsDir } = await import('../lib/state.js');
             const logPath = path.join(getAgentsDir(), 'daemon.log');
-            const child = execCb(`tail -f "${logPath}"`);
-            child.stdout?.pipe(process.stdout);
-            child.stderr?.pipe(process.stderr);
+            const child = spawn('tail', ['-f', logPath], { stdio: ['ignore', 'pipe', 'pipe'] });
+            child.stdout.pipe(process.stdout);
+            child.stderr.pipe(process.stderr);
             child.on('exit', () => process.exit(0));
             process.on('SIGINT', () => { child.kill(); process.exit(0); });
             return;
@@ -107,4 +116,3 @@ you never need to start it manually.
         await runDaemon();
     });
 }
-//# sourceMappingURL=daemon.js.map

package/dist/commands/doctor.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `agents doctor` — diagnostic readout across the install.
+ *
+ * Three sections:
+ *   1. CLI availability — which agent binaries can be invoked.
+ *   2. Sync status — per (agent, default-version), is the version-home sync
+ *      manifest fresh? (sync runs at launch; this surfaces what would happen.)
+ *   3. Orphans — per resource type per default version, count of files that
+ *      would be removed by `agents prune`.
+ *
+ * Read-only: doctor never mutates state. Run `agents prune` to act on the
+ * orphan readout, or just launch the agent to apply pending sync.
+ */
+import type { Command } from 'commander';
+export declare function registerDoctorCommand(program: Command): void;

package/dist/commands/doctor.js

@@ -0,0 +1,132 @@
+import chalk from 'chalk';
+import { checkAllClis } from '../lib/teams/agents.js';
+import { AGENTS, ALL_AGENT_IDS } from '../lib/agents.js';
+import { getAvailableResources, getGlobalDefault, } from '../lib/versions.js';
+import { loadSyncManifest, isSyncStale } from '../lib/sync-manifest.js';
+import { diffVersionCommands, iterCommandsCapableVersions } from '../lib/commands.js';
+import { diffVersionSkills, iterSkillsCapableVersions } from '../lib/skills.js';
+import { diffVersionHooks, iterHooksCapableVersions } from '../lib/hooks.js';
+const AGENT_NAMES = Object.fromEntries(ALL_AGENT_IDS.map((id) => [id, AGENTS[id].name]));
+function checkSyncStatus(cwd) {
+    const rows = [];
+    for (const agent of ALL_AGENT_IDS) {
+        const version = getGlobalDefault(agent);
+        if (!version)
+            continue;
+        const manifest = loadSyncManifest(agent, version);
+        if (!manifest) {
+            rows.push({ agent, version, status: 'never-synced' });
+            continue;
+        }
+        const available = getAvailableResources(cwd);
+        const stale = isSyncStale(manifest, available, agent, version, cwd);
+        rows.push({ agent, version, status: stale ? 'stale' : 'fresh' });
+    }
+    return rows;
+}
+function countOrphans() {
+    const byKey = new Map();
+    const ensure = (agent, version) => {
+        const key = `${agent}@${version}`;
+        let row = byKey.get(key);
+        if (!row) {
+            row = { agent, version, commands: 0, skills: 0, hooks: 0 };
+            byKey.set(key, row);
+        }
+        return row;
+    };
+    for (const { agent, version } of iterCommandsCapableVersions()) {
+        if (version !== getGlobalDefault(agent))
+            continue;
+        const diff = diffVersionCommands(agent, version);
+        if (diff.orphans.length > 0)
+            ensure(agent, version).commands = diff.orphans.length;
+    }
+    for (const { agent, version } of iterSkillsCapableVersions()) {
+        if (version !== getGlobalDefault(agent))
+            continue;
+        const diff = diffVersionSkills(agent, version);
+        if (diff.orphans.length > 0)
+            ensure(agent, version).skills = diff.orphans.length;
+    }
+    for (const { agent, version } of iterHooksCapableVersions()) {
+        if (version !== getGlobalDefault(agent))
+            continue;
+        const diff = diffVersionHooks(agent, version);
+        if (diff.orphans.length > 0)
+            ensure(agent, version).hooks = diff.orphans.length;
+    }
+    return Array.from(byKey.values()).filter((r) => r.commands + r.skills + r.hooks > 0);
+}
+function renderText(clis, syncRows, orphanRows) {
+    console.log(chalk.bold('Agent CLIs'));
+    if (Object.keys(clis).length === 0) {
+        console.log(chalk.gray('  (no agents reported)'));
+    }
+    else {
+        for (const [name, entry] of Object.entries(clis)) {
+            const pretty = AGENT_NAMES[name] || name;
+            if (entry.installed) {
+                console.log(`  ${chalk.green('ready')}  ${pretty.padEnd(10)} ${chalk.gray(entry.path || '')}`);
+            }
+            else {
+                console.log(`  ${chalk.red('no   ')}  ${pretty.padEnd(10)} ${chalk.gray(entry.error || 'not installed')}`);
+            }
+        }
+    }
+    console.log();
+    console.log(chalk.bold('Sync status (default versions)'));
+    if (syncRows.length === 0) {
+        console.log(chalk.gray('  (no default versions set; pin one with `agents use <agent>@<version>`)'));
+    }
+    else {
+        for (const row of syncRows) {
+            const label = `${AGENT_NAMES[row.agent] || row.agent}@${row.version}`;
+            if (row.status === 'fresh') {
+                console.log(`  ${chalk.green('fresh')}  ${label}`);
+            }
+            else if (row.status === 'stale') {
+                console.log(`  ${chalk.yellow('stale')}  ${label}  ${chalk.gray('— will sync on next launch')}`);
+            }
+            else {
+                console.log(`  ${chalk.gray('cold ')}  ${label}  ${chalk.gray('— never synced; first launch will populate')}`);
+            }
+        }
+    }
+    console.log();
+    console.log(chalk.bold('Orphans (default versions)'));
+    if (orphanRows.length === 0) {
+        console.log(chalk.gray('  (none — version homes match central sources)'));
+    }
+    else {
+        for (const row of orphanRows) {
+            const parts = [];
+            if (row.commands > 0)
+                parts.push(`${row.commands} command${row.commands === 1 ? '' : 's'}`);
+            if (row.skills > 0)
+                parts.push(`${row.skills} skill${row.skills === 1 ? '' : 's'}`);
+            if (row.hooks > 0)
+                parts.push(`${row.hooks} hook${row.hooks === 1 ? '' : 's'}`);
+            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.'));
+    }
+}
+export function registerDoctorCommand(program) {
+    program
+        .command('doctor')
+        .description('Diagnose CLI availability, sync status, and orphan resources')
+        .option('--json', 'Output machine-readable JSON')
+        .action((opts) => {
+        const cwd = process.cwd();
+        const clis = checkAllClis();
+        const syncRows = checkSyncStatus(cwd);
+        const orphanRows = countOrphans();
+        if (opts.json) {
+            console.log(JSON.stringify({ clis, sync: syncRows, orphans: orphanRows }, null, 2));
+            return;
+        }
+        renderText(clis, syncRows, orphanRows);
+    });
+}

package/dist/commands/drive.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Drive sync commands.
+ *
+ * Registers the `agents drive` command tree for syncing agent session
+ * history across machines via rsync. Supports pull, push, attach
+ * (redirect agent homes to drive), and detach operations.
+ */
 import type { Command } from 'commander';
+/** Register the `agents drive` command tree. */
 export declare function registerDriveCommands(program: Command): void;
-//# sourceMappingURL=drive.d.ts.map

package/dist/commands/drive.js

@@ -1,9 +1,19 @@
+/**
+ * Drive sync commands.
+ *
+ * Registers the `agents drive` command tree for syncing agent session
+ * history across machines via rsync. Supports pull, push, attach
+ * (redirect agent homes to drive), and detach operations.
+ */
 import chalk from 'chalk';
 import ora from 'ora';
+import { betaEnableHint, isBetaEnabled } from '../lib/beta.js';
 import { setRemote, pull, push, attach, detach, getDriveStatus, } from '../lib/drive-sync.js';
+/** Register the `agents drive` command tree. */
 export function registerDriveCommands(program) {
+    const enabled = isBetaEnabled('drive');
     const driveCmd = program
-        .command('drive')
+        .command('drive', { hidden: !enabled })
         .description('Sync agent session history across machines via rsync. Set up once, then pull/push to keep sessions in sync.')
         .addHelpText('after', `
 Typical workflow:
@@ -24,13 +34,20 @@ Typical workflow:
 Use case: Keep session history consistent across your laptop and desktop,
 or back up sessions to a server you control.
 `);
+    driveCmd.hook('preAction', () => {
+        if (enabled)
+            return;
+        console.error(chalk.red('agents drive is in beta.'));
+        console.error(chalk.gray(betaEnableHint('drive')));
+        process.exit(1);
+    });
     driveCmd
         .command('remote <target>')
         .description('Set the rsync remote target (e.g., user@hostname). Sessions sync to <target>:~/.agents/drive/')
         .addHelpText('after', `
 Examples:
   # Set remote to a server
-  agents drive remote muqsit@spark
+  agents drive remote user@server
 
   # Set remote to a local machine on your network
   agents drive remote macbook.local
@@ -146,6 +163,7 @@ Example:
         }
     });
 }
+/** Format an ISO timestamp as a human-readable relative time (e.g. "5 min ago"). */
 function formatTime(iso) {
     const d = new Date(iso);
     const now = Date.now();
@@ -163,4 +181,3 @@ function formatTime(iso) {
     const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
     return `${months[d.getMonth()]} ${d.getDate()}`;
 }
-//# sourceMappingURL=drive.js.map

package/dist/commands/exec.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Agent execution command.
+ *
+ * Registers the `agents run` command which spawns agent CLIs interactively
+ * or headlessly. Supports profile resolution, version rotation, secrets
+ * injection, and multi-agent fallback chains for rate-limit resilience.
+ */
 import type { Command } from 'commander';
+/** Register the `agents run <agent> [prompt]` command. */
 export declare function registerRunCommand(program: Command): void;
-//# sourceMappingURL=exec.d.ts.map

package/dist/commands/exec.js

@@ -1,18 +1,29 @@
+/**
+ * Agent execution command.
+ *
+ * Registers the `agents run` command which spawns agent CLIs interactively
+ * or headlessly. Supports profile resolution, version rotation, secrets
+ * 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 { readBundle, resolveBundleEnv } from '../lib/secrets-bundles.js';
-import { resolveRunVersion } from '../lib/rotate.js';
+import { readBundle, resolveBundleEnv } from '../lib/secrets/bundles.js';
+import { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, RUN_STRATEGIES, } from '../lib/rotate.js';
+import { resolveVersionAlias } from '../lib/versions.js';
 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);
 }
+/** Build a one-line banner describing which version the rotation picked. */
 function formatRotationBanner(result) {
     const { picked, healthy, excluded } = result;
     const label = picked.email ? `${picked.email} · ${picked.agent}@${picked.version}` : `${picked.agent}@${picked.version}`;
     const ratio = `${healthy.length} of ${healthy.length + excluded.length} healthy`;
     return `[agents] rotation picked ${label} (${ratio})`;
 }
+/** Register the `agents run <agent> [prompt]` command. */
 export function registerRunCommand(program) {
     program
         .command('run <agent> [prompt]')
@@ -26,20 +37,27 @@ export function registerRunCommand(program) {
         .option('--add-dir <dir>', 'Grant access to an additional directory outside the project (Claude only, repeatable)', (val, prev) => [...prev, val], [])
         .option('--json', 'Stream events as JSON lines (for parsing by other tools)')
         .option('--headless', 'Non-interactive mode (default for run)', true)
+        .option('-i, --interactive', 'Force interactive mode even when a prompt is provided')
         .option('--session-id <id>', 'Resume a previous conversation (Claude only)')
         .option('--verbose', 'Show detailed execution logs')
         .option('--timeout <duration>', 'Kill the agent after this duration (e.g., 30m, 1h, 2h30m)')
         .option('--fallback <agents>', 'Comma-separated agents to try on rate-limit failure. Each entry accepts an optional @version pin (e.g., codex@0.116.0,gemini). The primary runs first; if it exits with a rate-limit error, the next agent picks up via /continue handoff.')
-        .option('-r, --rotate', 'Rotate across installed versions of the agent. Picks the signed-in, not-out-of-credits account with the oldest last-active timestamp. Ignored when @version is pinned.')
+        .option('-r, --rotate', 'Shortcut for --strategy rotate. Ignored when @version is pinned.')
+        .option('--strategy <strategy>', 'Version/account selection strategy: pinned | available | rotate. Defaults to run.<agent>.strategy, then pinned.')
+        .option('--acp', 'Route through the Agent Client Protocol instead of direct exec. Supported for gemini, claude (via @zed-industries/claude-code-acp adapter). Unified event stream; emits ndjson when --json.')
         .addHelpText('after', `
 Modes:
   With a prompt -> headless (pipes output, no TTY, exits when the agent finishes).
   Without a prompt -> interactive (launches the agent's TUI; stdio is fully inherited).
 
-Version rotation (opt-in with --rotate):
-  Picks across installed versions using the account data 'agents view' already
-  shows: signed-in only, skip out-of-credits, least-recently-active wins. Useful
-  when you have multiple accounts of the same CLI and want to spread usage.
+Run strategy:
+  pinned     Use the workspace/global pinned version from agents.yaml.
+  available  Use the pinned version if it has usage available; otherwise switch
+             to another signed-in version with usage available.
+  rotate     Pick the signed-in account with usage available and the most
+             headroom; last-active breaks ties.
+  Configure with run.<agent>.strategy in agents.yaml, or override with
+  --strategy. --rotate is kept as a shortcut for --strategy rotate.
   Ignored when @version is pinned, when a profile is used, or with --fallback.
 
 Examples:
@@ -47,10 +65,10 @@ Examples:
   agents run claude
 
   # Interactive, rotate to the least-used healthy account
-  agents run claude --rotate
+  agents run claude --strategy rotate
 
-  # Headless, rotate per invocation (spreads across accounts over time)
-  agents run claude "summarize recent git commits" --mode plan --rotate
+  # Headless, switch away from the pinned version when usage is unavailable
+  agents run claude "summarize recent git commits" --mode plan --strategy available
 
   # Pin a specific version (rotation ignored)
   agents run codex@0.116.0 "fix linting errors in src/" --mode edit
@@ -108,37 +126,49 @@ Examples:
             console.error(chalk.gray(`Or add a profile: agents profiles add <name>`));
             process.exit(1);
         }
-        // Rotation is opt-in via --rotate. Default honors the pinned default
-        // version (from `agents use`) so behavior stays predictable. When
-        // opted in, pick the least-recently-active signed-in version that
-        // isn't out of credits. Skipped when @version is pinned, when running
-        // a profile (profile carries its own version + auth), or when a
-        // fallback chain is configured (fallback pins versions directly).
-        if (options.rotate) {
+        version = resolveVersionAlias(agent, version);
+        const cwd = options.cwd ?? process.cwd();
+        const configuredStrategy = getConfiguredRunStrategy(agent, cwd);
+        const explicitStrategy = options.strategy ? normalizeRunStrategy(options.strategy) : null;
+        if (options.strategy && !explicitStrategy) {
+            console.error(chalk.red(`Invalid strategy: ${options.strategy}. Use ${RUN_STRATEGIES.join(', ')}.`));
+            process.exit(1);
+        }
+        if (options.rotate && explicitStrategy && explicitStrategy !== 'rotate') {
+            console.error(chalk.red('--rotate conflicts with --strategy. Use one strategy override.'));
+            process.exit(1);
+        }
+        const strategy = options.rotate ? 'rotate' : explicitStrategy ?? configuredStrategy;
+        // Strategy only applies to bare agent invocations. Explicit @version,
+        // profiles, and fallback chains already define their execution target.
+        if (strategy !== 'pinned' || options.rotate || explicitStrategy) {
             if (version) {
-                process.stderr.write(chalk.yellow(`[agents] --rotate ignored: version ${version} is pinned\n`));
+                process.stderr.write(chalk.yellow(`[agents] strategy ${strategy} ignored: version ${version} is pinned\n`));
             }
             else if (fromProfile) {
-                process.stderr.write(chalk.yellow(`[agents] --rotate ignored: profile pins its own version/auth\n`));
+                process.stderr.write(chalk.yellow(`[agents] strategy ${strategy} ignored: profile pins its own version/auth\n`));
             }
             else if (options.fallback) {
-                process.stderr.write(chalk.yellow(`[agents] --rotate ignored: --fallback pins versions directly\n`));
+                process.stderr.write(chalk.yellow(`[agents] strategy ${strategy} ignored: --fallback pins versions directly\n`));
             }
             else {
                 try {
-                    const resolved = await resolveRunVersion(agent);
+                    const resolved = await resolveRunVersion(agent, strategy, cwd);
                     if (resolved.version) {
                         version = resolved.version;
                         if (resolved.rotation) {
-                            process.stderr.write(chalk.gray(formatRotationBanner(resolved.rotation) + '\n'));
+                            const banner = strategy === 'available'
+                                ? formatRotationBanner(resolved.rotation).replace('rotation picked', 'available picked')
+                                : formatRotationBanner(resolved.rotation);
+                            process.stderr.write(chalk.gray(banner + '\n'));
                         }
                     }
                     else {
-                        process.stderr.write(chalk.yellow(`[agents] --rotate found no healthy ${agent} version; falling back to defaults\n`));
+                        process.stderr.write(chalk.yellow(`[agents] strategy ${strategy} found no usable ${agent} version; falling back to defaults\n`));
                     }
                 }
                 catch (err) {
-                    process.stderr.write(chalk.yellow(`[agents] rotation skipped: ${err.message}\n`));
+                    process.stderr.write(chalk.yellow(`[agents] strategy ${strategy} skipped: ${err.message}\n`));
                 }
             }
         }
@@ -185,6 +215,7 @@ Examples:
             agent,
             version,
             prompt,
+            interactive: options.interactive,
             mode,
             effort,
             cwd: options.cwd,
@@ -197,6 +228,16 @@ Examples:
             timeout: options.timeout,
             env,
         };
+        if (options.interactive) {
+            if (options.fallback) {
+                console.error(chalk.red('--interactive is not compatible with --fallback. Fallback only works for headless prompt runs.'));
+                process.exit(1);
+            }
+            if (options.acp) {
+                console.error(chalk.red('--interactive is not compatible with --acp. ACP is a headless protocol.'));
+                process.exit(1);
+            }
+        }
         const fallback = [];
         if (options.fallback) {
             if (prompt === undefined) {
@@ -215,10 +256,39 @@ Examples:
                     console.error(chalk.red(`Fallback cannot include the primary agent (${agent}). Rate-limit fallback only helps when switching providers.`));
                     process.exit(1);
                 }
-                fallback.push({ agent: fbAgent, version: fbVersion || undefined });
+                fallback.push({ agent: fbAgent, version: resolveVersionAlias(fbAgent, fbVersion || undefined) });
+            }
+        }
+        if (options.acp) {
+            if (prompt === undefined) {
+                console.error(chalk.red('--acp requires a prompt. ACP is a programmatic protocol; interactive TUI sessions still use the native CLI.'));
+                process.exit(1);
+            }
+            if (fallback.length > 0) {
+                console.error(chalk.red('--acp is not compatible with --fallback yet. Drop one.'));
+                process.exit(1);
+            }
+            const { supportsAcp } = await import('../lib/acp/harnesses.js');
+            if (!supportsAcp(agent)) {
+                console.error(chalk.red(`Agent '${agent}' does not support ACP. Drop --acp to use direct exec.`));
+                process.exit(1);
+            }
+            const { runAcpHeadless } = await import('../lib/acp/run.js');
+            try {
+                const exitCode = await runAcpHeadless({
+                    agent,
+                    prompt,
+                    cwd: options.cwd ?? process.cwd(),
+                    mode,
+                    json: options.json ?? false,
+                });
+                process.exit(exitCode);
+            }
+            catch (err) {
+                console.error(chalk.red(`ACP run failed for ${agent}: ${err.message}`));
+                process.exit(1);
             }
         }
-        // Show what we're running (stderr so stdout stays clean for piping)
         const cmd = buildExecCommand(execOptions);
         process.stderr.write(chalk.gray(`Running: ${cmd.join(' ')}\n\n`));
         try {
@@ -238,4 +308,3 @@ Examples:
         }
     });
 }
-//# sourceMappingURL=exec.js.map

package/dist/commands/factory.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Software Factory CLI -- thin client over `prix/factory/service`.
+ *
+ * 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.
+ */
+import type { Command } from 'commander';
+export declare function registerFactoryCommands(program: Command): void;

package/dist/commands/factory.js

@@ -0,0 +1,71 @@
+import chalk from 'chalk';
+import * as fs from 'fs';
+import * as path from 'path';
+import { homedir } from 'os';
+import { betaEnableHint, isBetaEnabled } from '../lib/beta.js';
+const FACTORY_URL = process.env.FACTORY_FLOOR_URL ?? 'https://agents.427yosemite.com';
+function die(msg, code = 1) {
+    console.error(chalk.red(msg));
+    process.exit(code);
+}
+function readRushToken() {
+    const userYaml = path.join(homedir(), '.rush', 'user.yaml');
+    if (!fs.existsSync(userYaml)) {
+        die('Not logged in to Rush. Run `rush login` first.');
+    }
+    const raw = fs.readFileSync(userYaml, 'utf-8');
+    const match = raw.match(/access_token:\s*([^\s#]+)/);
+    if (!match) {
+        die('No session token in ~/.rush/user.yaml. Run `rush login` first.');
+    }
+    return match[1].replace(/^['"]|['"]$/g, '');
+}
+async function postFactorySubmit(ref) {
+    const token = readRushToken();
+    const res = await fetch(`${FACTORY_URL}/factory/submit`, {
+        method: 'POST',
+        headers: {
+            'Authorization': `Bearer ${token}`,
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ ref }),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        die(`Factory submit failed (${res.status}): ${body.slice(0, 400)}`);
+    }
+    return res.json();
+}
+export function registerFactoryCommands(program) {
+    const enabled = isBetaEnabled('factory');
+    const factory = program
+        .command('factory', { hidden: !enabled })
+        .description('Software Factory -- submit Linear tickets to the cloud orchestrator.')
+        .addHelpText('after', `
+Examples:
+  agents factory submit RUSH-2451
+  agents factory submit https://linear.app/getrush/issue/RUSH-2451
+`);
+    factory.hook('preAction', () => {
+        if (enabled)
+            return;
+        console.error(chalk.red('agents factory is in beta.'));
+        console.error(chalk.gray(betaEnableHint('factory')));
+        process.exit(1);
+    });
+    factory
+        .command('submit <linear-ref>')
+        .description('Submit a Linear issue (RUSH-123 or URL) to the Software Factory.')
+        .option('--json', 'Output machine-readable JSON')
+        .action(async (ref, opts) => {
+        const result = await postFactorySubmit(ref);
+        if (opts.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(chalk.green(`Submitted ${result.linear_identifier} (${result.label})`));
+        console.log(`  ticket       ${result.ticket_id}`);
+        console.log(`  execution    ${result.cloud_execution_id}`);
+        console.log(`  tail output  agents cloud tail ${result.cloud_execution_id}`);
+    });
+}

package/dist/commands/fork.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Repository fork command.
+ *
+ * Registers the `agents fork` command which forks the default system
+ * config repo to the user's GitHub account, reconfigures remotes
+ * (origin -> user fork, upstream -> system repo), and pushes.
+ */
 import type { Command } from 'commander';
+/** Register the `agents fork` command. */
 export declare function registerForkCommand(program: Command): void;
-//# sourceMappingURL=fork.d.ts.map

package/dist/commands/fork.js

@@ -1,9 +1,17 @@
+/**
+ * Repository fork command.
+ *
+ * Registers the `agents fork` command which forks the default system
+ * config repo to the user's GitHub account, reconfigures remotes
+ * (origin -> user fork, upstream -> system repo), and pushes.
+ */
 import chalk from 'chalk';
 import ora from 'ora';
 import { getAgentsDir, ensureAgentsDir } from '../lib/state.js';
 import { isGitRepo, isSystemRepoOrigin, getGitHubUsername, hasLocalChanges, setUpstreamRemote, setRemoteUrl, getRemoteUrl, } from '../lib/git.js';
 import { DEFAULT_SYSTEM_REPO, systemRepoSlug } from '../lib/types.js';
 import { isPromptCancelled } from './utils.js';
+/** Register the `agents fork` command. */
 export function registerForkCommand(program) {
     program
         .command('fork')
@@ -66,14 +74,14 @@ Requirements:
             spinner.succeed(`Logged in as ${username}`);
             // Fork the system repo
             const forkSpinner = ora('Forking system repo...').start();
-            const { exec } = await import('child_process');
+            const { execFile } = await import('child_process');
             const { promisify } = await import('util');
-            const execAsync = promisify(exec);
+            const execFileAsync = promisify(execFile);
             const repoSlug = systemRepoSlug(DEFAULT_SYSTEM_REPO);
             try {
                 // gh repo fork creates a fork and optionally clones it
                 // We just want to create the fork on GitHub, not clone
-                await execAsync(`gh repo fork ${repoSlug} --clone=false`);
+                await execFileAsync('gh', ['repo', 'fork', repoSlug, '--clone=false']);
                 forkSpinner.succeed(`Forked to ${username}/.agents`);
             }
             catch (err) {
@@ -136,4 +144,3 @@ Requirements:
         }
     });
 }
-//# sourceMappingURL=fork.js.map

package/dist/commands/hooks.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Hook management commands for automating workflows on agent events.
+ *
+ * Implements `agents hooks` -- list, add, remove, sync, prune, and view
+ * shell scripts that fire on agent lifecycle events (session start, file
+ * edit, task completion). Central storage lives in ~/.agents/hooks/ and
+ * scripts are synced to individual version homes.
+ */
 import type { Command } from 'commander';
+/** Register the `agents hooks` command tree (list, add, remove, sync, prune, view). */
 export declare function registerHooksCommands(program: Command): void;
-//# sourceMappingURL=hooks.d.ts.map