@phnx-labs/agents-cli 1.20.16 → 1.20.18

package/dist/commands/exec.js

@@ -7,9 +7,11 @@
  */
 import chalk from 'chalk';
 import { setHelpSections } from '../lib/help.js';
+import { parseLoopInterval } from '../lib/loop.js';
 import { AGENTS } from '../lib/agents.js';
 import * as fs from 'fs';
 import * as path from 'path';
+import * as os from 'os';
 /** Type guard that narrows a string to a known AgentId. */
 function isValidAgent(agent) {
     return agent in AGENTS;
@@ -21,6 +23,83 @@ function formatRotationBanner(result, verb = 'balanced') {
     const ratio = `${healthy.length} of ${healthy.length + excluded.length} healthy`;
     return `[agents] ${verb} picked ${label} (${ratio})`;
 }
+/**
+ * Build the LoopConfig the driver consumes from CLI flags and/or a workflow's
+ * `loop:` frontmatter block (issue #332). Returns undefined when neither source
+ * activates a loop (the common single-shot run). CLI flags take precedence over
+ * the workflow's declared values field-by-field, so `--max-iterations 5`
+ * overrides a workflow's `max_iterations: 3`.
+ *
+ * `--loop` with no sub-options is a valid bare loop (driver applies its own
+ * maxIterations safety cap). A workflow `loop:` block activates a loop even
+ * without `--loop` so `agents run <workflow>` honors a declared loop.
+ */
+export function buildLoopConfig(flags, workflowLoop) {
+    const active = flags.loop === true || workflowLoop !== undefined;
+    if (!active)
+        return undefined;
+    const cfg = {};
+    // until: CLI > workflow. Only `signal` is supported.
+    const until = flags.until ?? workflowLoop?.until;
+    if (until !== undefined) {
+        if (until !== 'signal') {
+            throw new Error(`Invalid --until '${until}'. Only 'signal' is supported.`);
+        }
+        cfg.until = 'signal';
+    }
+    // max_iterations: CLI > workflow.
+    if (flags.maxIterations !== undefined) {
+        const n = Number(flags.maxIterations);
+        if (!Number.isInteger(n) || n <= 0) {
+            throw new Error(`Invalid --max-iterations '${flags.maxIterations}'. Use a positive integer.`);
+        }
+        cfg.maxIterations = n;
+    }
+    else if (workflowLoop?.max_iterations !== undefined) {
+        cfg.maxIterations = workflowLoop.max_iterations;
+    }
+    // budget (tokens): CLI > workflow.
+    if (flags.budget !== undefined) {
+        const b = Number(flags.budget);
+        if (!Number.isFinite(b) || b <= 0) {
+            throw new Error(`Invalid --budget '${flags.budget}'. Use a positive token count.`);
+        }
+        cfg.budget = b;
+    }
+    else if (workflowLoop?.budget !== undefined) {
+        cfg.budget = workflowLoop.budget;
+    }
+    // interval: CLI > workflow. Validate eagerly — an unparseable interval
+    // (e.g. "30s", "5", "abc") must be rejected here, not silently coalesced to
+    // 0ms (back-to-back) at run time. "0" is the one accepted non-duration value.
+    const interval = flags.interval ?? workflowLoop?.interval;
+    if (interval !== undefined) {
+        try {
+            parseLoopInterval(interval);
+        }
+        catch {
+            throw new Error(`Invalid --interval '${interval}'. Use "0" for back-to-back or a duration like "30m", "1h", "2h30m" (units: w/d/h/m).`);
+        }
+        cfg.interval = interval;
+    }
+    return cfg;
+}
+/** Map a loop stop reason to a process exit code. condition-met/max are clean exits. */
+export function loopExitCode(stoppedBy) {
+    switch (stoppedBy) {
+        case 'condition-met':
+        case 'max':
+            return 0;
+        case 'budget':
+            return 7; // mirrors BUDGET_KILL_EXIT_CODE so CI can tell a budget stop apart
+        case 'signal':
+            return 130; // 128 + SIGINT(2)
+        case 'stalled':
+        case 'error':
+        default:
+            return 1;
+    }
+}
 /** Register the `agents run <agent> [prompt]` command. */
 export function registerRunCommand(program) {
     const runCmd = program
@@ -44,7 +123,14 @@ export function registerRunCommand(program) {
         .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('-b, --balanced', 'Shortcut for --strategy balanced. Ignored when @version is pinned.')
         .option('--strategy <strategy>', 'Version/account selection strategy: pinned | available | balanced. Defaults to run.<agent>.strategy, then pinned. (Legacy `rotate` accepted as alias for `balanced`.)')
-        .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.');
+        .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.')
+        .option('-y, --yes', 'Skip the interactive budget-confirm prompt (require_confirm_over). Never skips a hard budget block.', false)
+        .option('--loop', 'Re-inject the prompt/entrypoint each iteration until a stop condition (issue #332). Guards (--max-iterations, --budget, --until) are enforced outside the agent. Writes a checkpoint after every iteration for --resume-checkpoint.')
+        .option('--resume-checkpoint <file>', 'Resume a killed loop run from its checkpoint.json. Continues from the last completed iteration, reusing the same runId, session id, prompt, and loop config.')
+        .option('--max-iterations <n>', 'Loop hard cap: stop after N iterations (stoppedBy: max). Loop only.')
+        .option('--budget <tokens>', 'Loop token hard-cap: stop once cumulative tokens reach this (stoppedBy: budget), enforced outside the agent. Loop only.')
+        .option('--until <signal>', 'Loop stop condition. `signal` reads <runDir>/loop-signal.json {continue,reason} each iteration; absent or continue:false stops (fail-closed). Loop only.')
+        .option('--interval <dur>', 'Loop delay between iterations ("0" back-to-back, "30m" paces). Loop only.');
     setHelpSections(runCmd, {
         examples: `
       # Headless, read-only: investigate or summarize without writing files
@@ -85,7 +171,85 @@ export function registerRunCommand(program) {
     `,
     });
     runCmd.action(async (agentSpec, prompt, options) => {
-        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode, defaultModeFor, headlessPlanStallCommand }, { ALL_AGENT_IDS }, { profileExists, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, RUN_STRATEGIES }, { getGlobalDefault, getVersionHomePath, resolveVersion, resolveVersionAlias }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef }, { resolveRunDefaults },] = await Promise.all([
+        // --resume-checkpoint short-circuits normal dispatch entirely: the
+        // checkpoint already carries the agent, version, prompt, session id,
+        // iteration, and loop config of the killed run. Reconstruct ExecOptions
+        // straight from it and continue the loop from the last completed
+        // iteration, reusing the SAME runId/runDir (issue #332).
+        if (options.resumeCheckpoint) {
+            const { readCheckpoint } = await import('../lib/checkpoint.js');
+            const { runLoop } = await import('../lib/loop.js');
+            const { getRunsDir } = await import('../lib/state.js');
+            const cp = readCheckpoint(options.resumeCheckpoint);
+            if (!cp) {
+                console.error(chalk.red(`Checkpoint not found or unreadable: ${options.resumeCheckpoint}`));
+                process.exit(1);
+            }
+            const runDir = path.join(getRunsDir(), cp.id);
+            fs.mkdirSync(runDir, { recursive: true });
+            const resumeExec = {
+                agent: cp.agent,
+                version: cp.version,
+                prompt: cp.prompt,
+                mode: options.mode,
+                effort: options.effort,
+                cwd: options.cwd,
+                sessionId: cp.sessionId,
+                json: true,
+                headless: true,
+            };
+            // Resume honors the checkpoint's loop config, but lets the resume
+            // command RAISE the bounds field-by-field — `--max-iterations 4` on a
+            // checkpoint capped at 2 is the natural "continue, run more" gesture.
+            // Flags override; unspecified fields fall through from the checkpoint.
+            const resumeLoop = { ...cp.loop };
+            if (options.maxIterations !== undefined) {
+                const n = Number(options.maxIterations);
+                if (!Number.isInteger(n) || n <= 0) {
+                    console.error(chalk.red(`Invalid --max-iterations '${options.maxIterations}'. Use a positive integer.`));
+                    process.exit(1);
+                }
+                resumeLoop.maxIterations = n;
+            }
+            if (options.budget !== undefined) {
+                const b = Number(options.budget);
+                if (!Number.isFinite(b) || b <= 0) {
+                    console.error(chalk.red(`Invalid --budget '${options.budget}'. Use a positive token count.`));
+                    process.exit(1);
+                }
+                resumeLoop.budget = b;
+            }
+            if (options.interval !== undefined) {
+                try {
+                    parseLoopInterval(options.interval);
+                }
+                catch {
+                    console.error(chalk.red(`Invalid --interval '${options.interval}'. Use "0" for back-to-back or a duration like "30m", "1h", "2h30m" (units: w/d/h/m).`));
+                    process.exit(1);
+                }
+                resumeLoop.interval = options.interval;
+            }
+            if (options.until !== undefined) {
+                if (options.until !== 'signal') {
+                    console.error(chalk.red(`Invalid --until '${options.until}'. Only 'signal' is supported.`));
+                    process.exit(1);
+                }
+                resumeLoop.until = 'signal';
+            }
+            process.stderr.write(chalk.gray(`[loop] resuming ${cp.agent} run ${cp.id} from iteration ${cp.iteration + 1} (session ${(cp.sessionId ?? '').slice(0, 8)})\n`));
+            const result = await runLoop(resumeExec, resumeLoop, {
+                runId: cp.id,
+                runDir,
+                agent: cp.agent,
+                version: cp.version,
+                startIteration: cp.iteration + 1,
+                startTokens: cp.cumulativeTokens ?? 0,
+                sessionId: cp.sessionId,
+            });
+            process.stderr.write(chalk.gray(`[loop] stopped: ${result.stoppedBy} after ${result.iterations} iteration(s), ${result.tokens} tokens\n`));
+            process.exit(loopExitCode(result.stoppedBy));
+        }
+        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode, defaultModeFor, headlessPlanStallCommand }, { ALL_AGENT_IDS }, { profileExists, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, RUN_STRATEGIES }, { getGlobalDefault, getVersionHomePath, resolveVersion, resolveVersionAlias }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef, resolveAllowedSubagents }, { resolveRunDefaults }, { getMcpServersByName, buildWorkflowMcpConfig }, { supports },] = await Promise.all([
             import('../lib/exec.js'),
             import('../lib/agents.js'),
             import('../lib/profiles.js'),
@@ -95,6 +259,8 @@ export function registerRunCommand(program) {
             import('../lib/plugins.js'),
             import('../lib/workflows.js'),
             import('../lib/run-defaults.js'),
+            import('../lib/mcp.js'),
+            import('../lib/capabilities.js'),
         ]);
         const isValidAgent = (agent) => ALL_AGENT_IDS.includes(agent);
         // Parse agent@version
@@ -104,6 +270,12 @@ export function registerRunCommand(program) {
         let profileEnv;
         let fromProfile = false;
         let workflowModel;
+        // WORKFLOW.md capability scoping, translated to Claude headless flags below.
+        let workflowToolsRestrict;
+        let workflowMcpConfigPath;
+        // WORKFLOW.md `loop:` block (issue #332). When a workflow declares it,
+        // `agents run <workflow>` honors the loop without a --loop flag.
+        let workflowLoop;
         const cwd = options.cwd ?? process.cwd();
         if (isValidAgent(rawAgent)) {
             agent = rawAgent;
@@ -139,15 +311,46 @@ export function registerRunCommand(program) {
             if (typeof workflowFrontmatter?.model === 'string' && workflowFrontmatter.model.trim() !== '') {
                 workflowModel = workflowFrontmatter.model.trim();
             }
+            workflowLoop = workflowFrontmatter?.loop;
             const resolvedVersion = resolveVersionAlias('claude', version);
             const versionHome = getVersionHomePath('claude', resolvedVersion ?? getGlobalDefault('claude') ?? '');
             const claudeAgentsDir = path.join(versionHome, '.claude', 'agents');
-            // Copy subagents/*.md into ~/.claude/agents/ so Claude's Agent tool finds them.
+            // Copy subagents/*.md into ~/.claude/agents/ so Claude's Agent tool finds
+            // them. allowedAgents enforcement (issue #324): when the workflow declares
+            // `allowedAgents:`, copy ONLY those subagent files (matched by filename
+            // stem, e.g. security.md -> "security"). A subagent whose definition isn't
+            // on disk can't be dispatched — this is the actual, fail-closed mechanism.
+            // (Claude's `--agents` flag DEFINES custom agents; it does not restrict
+            // which subagents may be dispatched, so it is not used here.)
             const subagentsDir = path.join(workflowDir, 'subagents');
+            const allowedAgents = workflowFrontmatter?.allowedAgents;
             if (fs.existsSync(subagentsDir)) {
                 fs.mkdirSync(claudeAgentsDir, { recursive: true });
-                for (const file of fs.readdirSync(subagentsDir).filter(f => f.endsWith('.md'))) {
+                // Fail-closed subagent scoping (issue #324). resolveAllowedSubagents
+                // distinguishes "allowedAgents absent" (undefined -> copy all) from
+                // "present but empty" (=> copy ZERO). An explicit `allowedAgents: []`
+                // must mean "allow none", never silently widen to "allow all".
+                const allFiles = fs.readdirSync(subagentsDir).filter(f => f.endsWith('.md'));
+                const { allowedStems, missing } = resolveAllowedSubagents(allFiles, allowedAgents);
+                const allowStemSet = new Set(allowedStems);
+                let copied = 0;
+                let skipped = 0;
+                for (const file of allFiles) {
+                    const stem = file.replace(/\.md$/, '');
+                    if (!allowStemSet.has(stem)) {
+                        skipped++;
+                        continue;
+                    }
                     fs.copyFileSync(path.join(subagentsDir, file), path.join(claudeAgentsDir, file));
+                    copied++;
+                }
+                if (allowedAgents !== undefined) {
+                    // Surface any allowedAgents entry with no matching subagent file, and
+                    // report how many were filtered out, so the scope is auditable.
+                    if (missing.length > 0) {
+                        process.stderr.write(chalk.yellow(`[workflow] allowedAgents not found in subagents/: ${missing.join(', ')}\n`));
+                    }
+                    process.stderr.write(chalk.gray(`[workflow] subagents restricted to allowedAgents: copied ${copied}, withheld ${skipped}\n`));
                 }
             }
             // Feed WORKFLOW.md body (strip frontmatter) as orchestrator system context.
@@ -201,8 +404,60 @@ export function registerRunCommand(program) {
                     }
                 }
             }
+            // Capability scoping: translate WORKFLOW.md `tools:` / `mcpServers:` into
+            // the Claude headless flags that ACTUALLY restrict the run (verified
+            // against `claude --help`): tools -> `--tools` (restricts the available
+            // built-in tool set), mcpServers -> `--mcp-config` + `--strict-mcp-config`
+            // (loads ONLY the named servers). `allowedAgents:` is enforced separately,
+            // above, by copying only the allowed subagent definition files. Gated
+            // behind the `allowlist` capability — if the resolved agent lacks it, warn
+            // loudly rather than silently dropping the declaration (issue #324).
+            const scopeVersion = resolveVersionAlias('claude', version) ?? getGlobalDefault('claude') ?? undefined;
+            const allowlist = supports('claude', 'allowlist', scopeVersion);
+            const tools = workflowFrontmatter?.tools;
+            const mcpServerNames = workflowFrontmatter?.mcpServers;
+            const hasScoping = (tools && tools.length > 0)
+                || (mcpServerNames && mcpServerNames.length > 0)
+                || (allowedAgents && allowedAgents.length > 0);
+            if (hasScoping && !allowlist.ok) {
+                process.stderr.write(chalk.yellow(`[workflow] tools/mcpServers declared but unenforceable on claude${scopeVersion ? `@${scopeVersion}` : ''} (allowlist ${allowlist.reason ?? 'unsupported'}) — running unscoped\n`));
+            }
+            else if (hasScoping) {
+                if (tools && tools.length > 0) {
+                    workflowToolsRestrict = tools;
+                    process.stderr.write(chalk.gray(`[workflow] restricting available tools to: ${tools.join(', ')} (Write/Bash/Edit unavailable unless listed)\n`));
+                }
+                if (mcpServerNames && mcpServerNames.length > 0) {
+                    const servers = getMcpServersByName(mcpServerNames, { cwd });
+                    const found = new Set(servers.map(s => s.name));
+                    const missing = mcpServerNames.filter(n => !found.has(n));
+                    if (missing.length > 0) {
+                        process.stderr.write(chalk.yellow(`[workflow] mcpServers not found in registry, skipped: ${missing.join(', ')}\n`));
+                    }
+                    // Fail-closed: `mcpServers:` was declared, so the run MUST be scoped to
+                    // a config — never fall through to the user's ambient MCP set. When
+                    // zero declared names resolve to installed servers, write a locked-down
+                    // empty config (`{ "mcpServers": {} }`); with `--strict-mcp-config` the
+                    // run gets NO MCP servers, which is LESS access than ambient (issue #324).
+                    const mcpConfig = buildWorkflowMcpConfig(servers);
+                    const configDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agents-workflow-mcp-'));
+                    workflowMcpConfigPath = path.join(configDir, 'mcp-config.json');
+                    // 0o600: the config embeds server `env` which can carry tokens.
+                    // Cleaned up after the run (finally block below).
+                    fs.writeFileSync(workflowMcpConfigPath, mcpConfig, { mode: 0o600 });
+                    if (servers.length > 0) {
+                        process.stderr.write(chalk.gray(`[workflow] scoping MCP servers to ONLY: ${servers.map(s => s.name).join(', ')}\n`));
+                    }
+                    else {
+                        process.stderr.write(chalk.yellow(`[workflow] no declared mcpServers resolved — scoping run to NO MCP servers (fail-closed)\n`));
+                    }
+                }
+            }
+            // Count the subagents THIS workflow made available (after allowedAgents
+            // filtering), not every file in the shared agents dir. Same fail-closed
+            // semantics as the copy above: `allowedAgents: []` -> 0.
             const subagentCount = fs.existsSync(subagentsDir)
-                ? fs.readdirSync(subagentsDir).filter(f => f.endsWith('.md')).length
+                ? resolveAllowedSubagents(fs.readdirSync(subagentsDir).filter(f => f.endsWith('.md')), allowedAgents).allowedStems.length
                 : 0;
             process.stderr.write(chalk.gray(`Workflow '${rawAgent}' → claude (${subagentCount} subagents)\n`));
         }
@@ -385,6 +640,8 @@ export function registerRunCommand(program) {
             verbose: options.verbose,
             timeout: options.timeout,
             env,
+            toolsRestrict: workflowToolsRestrict,
+            mcpConfigPath: workflowMcpConfigPath,
         };
         if (options.interactive && options.headless) {
             console.error(chalk.red('--interactive and --headless are mutually exclusive. Pass one, or neither (mode is inferred from prompt presence).'));
@@ -463,10 +720,128 @@ export function registerRunCommand(program) {
                 process.exit(1);
             }
         }
+        // Budget pre-flight gate (issue #346). Estimate the run's cost and, when a
+        // cap is configured with on_exceed:block, refuse to launch if it would push
+        // a cap over the line — exiting non-zero so CI/headless inherit the block.
+        // --yes skips ONLY the interactive confirm threshold, never a hard block.
+        {
+            const { runPreflightGate } = await import('../lib/budget/preflight.js');
+            const { resolveEffectiveModel } = await import('../lib/models.js');
+            // Estimate against the model that will ACTUALLY run, not an unpriced
+            // `${agent}-default` placeholder (which made estimateCost return $0 and
+            // silently neutered the per_run/per_day gate for the common no-`--model`
+            // case). When `model` is undefined the spawned CLI uses its built-in
+            // default, which we recover from the extracted catalog. If we still can't
+            // resolve a concrete model, pass the placeholder — the gate now treats an
+            // unpriced estimate under active caps as needing confirmation, so it is
+            // never a silent $0 wave-through.
+            const effectiveModel = resolveEffectiveModel(agent, version ?? '', model) ?? `${agent}-default`;
+            const gate = runPreflightGate({
+                agent,
+                model: effectiveModel,
+                mode,
+                prompt,
+                project: cwd,
+                cwd,
+            });
+            if (!gate.dormant) {
+                if (!options.quiet) {
+                    process.stderr.write(chalk.gray(gate.banner + '\n'));
+                }
+                if (!gate.decision.allow) {
+                    // Hard block. --yes does NOT override (acceptance criterion).
+                    console.error(chalk.red(`[budget] BLOCKED: ${gate.decision.reason}`));
+                    console.error(chalk.gray(`Raise the cap in agents.yaml budget: or set on_exceed: warn to proceed.`));
+                    process.exit(2);
+                }
+                if (gate.decision.needsConfirm && !options.yes) {
+                    if (!process.stdin.isTTY) {
+                        // Non-interactive (CI/headless) and no --yes: cannot confirm — refuse.
+                        console.error(chalk.red(`[budget] ${gate.decision.reason}`));
+                        console.error(chalk.gray(`Re-run with --yes to confirm the spend, or lower require_confirm_over.`));
+                        process.exit(2);
+                    }
+                    const { confirm } = await import('@inquirer/prompts');
+                    const proceed = await confirm({
+                        message: `${gate.decision.reason}. Proceed?`,
+                        default: false,
+                    });
+                    if (!proceed) {
+                        console.error(chalk.yellow('[budget] aborted by user.'));
+                        process.exit(2);
+                    }
+                }
+                else if (gate.decision.blockedCap && gate.decision.allow && !options.quiet) {
+                    // on_exceed:warn overrun notice (allowed but reported).
+                    process.stderr.write(chalk.yellow(`[budget] WARN: ${gate.decision.reason}\n`));
+                }
+            }
+        }
         const cmd = buildExecCommand(execOptions);
         if (!options.quiet) {
             process.stderr.write(chalk.gray(`Running: ${cmd.join(' ')}\n\n`));
         }
+        // Remove the ephemeral mcp-config (and its temp dir) after the run. It is
+        // written at mode 0o600 but still embeds server `env` (possibly tokens),
+        // so it must not linger in tmp. Synchronous so it completes before exit.
+        const cleanupWorkflowMcpConfig = () => {
+            if (!workflowMcpConfigPath)
+                return;
+            try {
+                fs.rmSync(path.dirname(workflowMcpConfigPath), { recursive: true, force: true });
+            }
+            catch {
+                // best-effort: nothing actionable if the temp dir is already gone.
+            }
+        };
+        // Loop dispatch (issue #332). Active when --loop is passed OR a workflow
+        // declares a `loop:` block. The loop path runs AFTER the #346 pre-flight
+        // gate above (which fired once) — the loop's token budget is an ADDITIONAL
+        // guard, not a replacement. Composable, not bypassing.
+        let loopConfig;
+        try {
+            loopConfig = buildLoopConfig(options, workflowLoop);
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+        if (loopConfig) {
+            if (prompt === undefined) {
+                console.error(chalk.red('--loop requires a prompt (or a workflow whose loop is paired with a prompt). The loop re-injects the prompt each iteration.'));
+                process.exit(1);
+            }
+            if (options.interactive) {
+                console.error(chalk.red('--loop is headless-only. The loop re-injects programmatically; an interactive TUI cannot be re-driven.'));
+                process.exit(1);
+            }
+            if (fallback.length > 0) {
+                console.error(chalk.red('--loop is not compatible with --fallback yet. Drop one.'));
+                process.exit(1);
+            }
+            const { runLoop } = await import('../lib/loop.js');
+            const { getRunsDir } = await import('../lib/state.js');
+            const runId = `loop-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+            const runDir = path.join(getRunsDir(), runId);
+            fs.mkdirSync(runDir, { recursive: true });
+            process.stderr.write(chalk.gray(`[loop] run ${runId} — max ${loopConfig.maxIterations ?? '∞'}${loopConfig.budget ? `, budget ${loopConfig.budget} tokens` : ''}${loopConfig.until ? `, until ${loopConfig.until}` : ''}${loopConfig.interval ? `, interval ${loopConfig.interval}` : ''}\n`));
+            try {
+                const result = await runLoop({ ...execOptions, json: true, headless: true }, loopConfig, {
+                    runId,
+                    runDir,
+                    agent,
+                    version,
+                });
+                cleanupWorkflowMcpConfig();
+                process.stderr.write(chalk.gray(`[loop] stopped: ${result.stoppedBy} after ${result.iterations} iteration(s), ${result.tokens} tokens (checkpoint: ${path.join(runDir, 'checkpoint.json')})\n`));
+                process.exit(loopExitCode(result.stoppedBy));
+            }
+            catch (err) {
+                cleanupWorkflowMcpConfig();
+                console.error(chalk.red(`Loop failed for ${agent}: ${err.message}`));
+                process.exit(1);
+            }
+        }
         try {
             let exitCode;
             if (fallback.length > 0) {
@@ -476,9 +851,11 @@ export function registerRunCommand(program) {
             else {
                 exitCode = await execAgent(execOptions);
             }
+            cleanupWorkflowMcpConfig();
             process.exit(exitCode);
         }
         catch (err) {
+            cleanupWorkflowMcpConfig();
             console.error(chalk.red(`Failed to execute ${agent}: ${err.message}`));
             process.exit(1);
         }

package/dist/commands/secrets.d.ts

@@ -6,5 +6,20 @@
  * Keychain. Bundles are injected at run time via `agents run --secrets`.
  */
 import type { Command } from 'commander';
+/**
+ * SSH target for `export --to-ssh`: a bare ssh-config host alias (e.g. `yosemite-s0`)
+ * or `user@host`. The strict allowlist blocks shell metacharacters and a leading `-`
+ * so a target can't be smuggled in as an ssh argv flag.
+ */
+export declare const SSH_TARGET_RE: RegExp;
+export declare function assertValidSshTarget(host: string): void;
+/**
+ * Serialize a resolved env map to `.env` lines that round-trip losslessly through
+ * `parseDotenv` on the remote: `KEY="VALUE"`. parseDotenv strips exactly one outer
+ * quote pair and takes the inner bytes verbatim (no unescaping), so any single-line
+ * value survives unchanged with no escaping. Newlines would break its line-based
+ * parse, so multi-line values are rejected rather than silently corrupted.
+ */
+export declare function bundleEnvToDotenv(env: Record<string, string>): string;
 /** Register the `agents secrets` command tree. */
 export declare function registerSecretsCommands(program: Command): void;