@phnx-labs/agents-cli 1.20.35 → 1.20.36

package/dist/commands/doctor.js

@@ -4,10 +4,8 @@ import { checkAllClis } from '../lib/teams/agents.js';
 import { AGENTS, ALL_AGENT_IDS, resolveAgentName, formatAgentError } from '../lib/agents.js';
 import { getGlobalDefault, getVersionHomePath, isVersionInstalled, listInstalledVersions, parseAgentSpec, } from '../lib/versions.js';
 import { loadManifest, isStale } from '../lib/staleness/index.js';
-import { diffVersionCommands, iterCommandsCapableVersions } from '../lib/commands.js';
-import { diffVersionSkills, iterSkillsCapableVersions } from '../lib/skills.js';
-import { iterHooksCapableVersions, listUnmanagedHooksInVersionHome } from '../lib/hooks.js';
 import { diffVersionResources, DOCTOR_ALL_KINDS, } from '../lib/doctor-diff.js';
+import { checkSyncStatus, countOrphans } from '../lib/drift.js';
 import { unifiedDiff, colorizeUnifiedDiff } from '../lib/diff-text.js';
 import { listCliStatus } from '../lib/cli-resources.js';
 import { setHelpSections } from '../lib/help.js';
@@ -17,33 +15,6 @@ import { terminalWidth, truncateToWidth, stringWidth, padToWidth } from '../lib/
 import * as fs from 'fs';
 const AGENT_NAMES = Object.fromEntries(ALL_AGENT_IDS.map((id) => [id, AGENTS[id].name]));
 // ─── overview mode (no target) ────────────────────────────────────────────────
-// Lines naming exactly what's out of sync for a version, plugins prioritized:
-// each divergent plugin gets its own line with specifics (stale mirror version,
-// invalid manifest, or the bundled skills/commands missing from the mirror —
-// the system-repo plugin content that matters most). Other kinds collapse to
-// compact counts so the readout stays scannable.
-function divergenceLines(report) {
-    const lines = [];
-    for (const p of report.kinds.plugins) {
-        if (p.status === 'missing')
-            lines.push(`plugin ${p.name} — not installed`);
-        else if (p.status === 'diff')
-            lines.push(`plugin ${p.name} — ${p.detail ?? 'mirror drifted'}`);
-    }
-    for (const kind of ['commands', 'skills', 'hooks', 'rules', 'mcp', 'permissions', 'subagents']) {
-        const rows = report.kinds[kind];
-        const miss = rows.filter((r) => r.status === 'missing').length;
-        const dif = rows.filter((r) => r.status === 'diff').length;
-        const bits = [];
-        if (miss)
-            bits.push(`${miss} missing`);
-        if (dif)
-            bits.push(`${dif} drifted`);
-        if (bits.length)
-            lines.push(`${kind.padEnd(11)} ${bits.join(' · ')}`);
-    }
-    return lines;
-}
 function collapseWhitespace(s) {
     return s.replace(/\s+/g, ' ').trim();
 }
@@ -78,65 +49,6 @@ function printWrappedLine(prefix, text) {
     for (const line of wrapLine(prefix, text))
         console.log(chalk.gray(line));
 }
-function checkSyncStatus(cwd) {
-    const rows = [];
-    // Every installed version, not just the default — a stale NON-default version
-    // (e.g. one you launched from yesterday) is exactly the rot that silently
-    // serves outdated/invalid resources and that `--fix` now heals. Hiding it here
-    // is why that class of bug went unnoticed.
-    for (const agent of ALL_AGENT_IDS) {
-        const def = getGlobalDefault(agent);
-        for (const version of listInstalledVersions(agent)) {
-            const manifest = loadManifest(agent, version);
-            const status = !manifest
-                ? 'never-synced'
-                : isStale(manifest, agent, version, cwd) ? 'stale' : 'fresh';
-            const row = { agent, version, status, isDefault: version === def };
-            if (status === 'stale') {
-                // Resolve the specifics against non-project layers (the global home is
-                // never reconciled against per-cwd project resources).
-                const report = diffVersionResources(agent, version, { cwd, excludeProject: true });
-                const lines = divergenceLines(report);
-                if (lines.length)
-                    row.divergence = lines;
-            }
-            rows.push(row);
-        }
-    }
-    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()) {
-        const diff = diffVersionCommands(agent, version);
-        if (diff.orphans.length > 0)
-            ensure(agent, version).commands = diff.orphans.length;
-    }
-    for (const { agent, version } of iterSkillsCapableVersions()) {
-        const diff = diffVersionSkills(agent, version);
-        if (diff.orphans.length > 0)
-            ensure(agent, version).skills = diff.orphans.length;
-    }
-    // Orphan hooks are scripts in the version home that no agents.yaml/hooks.yaml
-    // entry registers — so the registrar never wires them to an event and they
-    // never fire. (Distinct from the source-diff `diffVersionHooks().orphans`,
-    // which false-flags valid system-sourced registered hooks.)
-    for (const { agent, version } of iterHooksCapableVersions()) {
-        const dead = listUnmanagedHooksInVersionHome(agent, version);
-        if (dead.length > 0)
-            ensure(agent, version).hooks = dead.length;
-    }
-    return Array.from(byKey.values()).filter((r) => r.commands + r.skills + r.hooks > 0);
-}
 function renderOverviewText(clis, syncRows, orphanRows, hostClis) {
     console.log(chalk.bold('Agent CLIs'));
     // Show the fleet you actually run — agents that are ready in PATH, plus any

package/dist/commands/events.js

@@ -14,7 +14,7 @@
  */
 import chalk from 'chalk';
 import * as fs from 'fs';
-import { query, LOGS_PATH } from '../lib/events.js';
+import { query, getLogsPath } from '../lib/events.js';
 /** Parse `--since`: relative offsets (30s/5m/2h/7d/4w) or an ISO/absolute date. */
 function parseSince(s) {
     const m = s.match(/^(\d+)([smhdw])$/);
@@ -116,7 +116,7 @@ Examples:
         // query() returns newest-first; print oldest-first so a tail reads naturally.
         for (const r of records.slice().reverse())
             console.log(renderRow(r));
-        console.log(chalk.gray(`\n${records.length} event(s). Log: ${LOGS_PATH}`));
+        console.log(chalk.gray(`\n${records.length} event(s). Log: ${getLogsPath()}`));
     });
 }
 /** commander repeatable-option collector. */
@@ -126,7 +126,7 @@ function collect(value, previous) {
 /** Tail today's event file, printing new lines as they land. */
 async function followLog() {
     const today = new Date();
-    const file = `${LOGS_PATH}/events-${today.getFullYear()}-${String(today.getMonth() + 1).padStart(2, '0')}-${String(today.getDate()).padStart(2, '0')}.jsonl`;
+    const file = `${getLogsPath()}/events-${today.getFullYear()}-${String(today.getMonth() + 1).padStart(2, '0')}-${String(today.getDate()).padStart(2, '0')}.jsonl`;
     let offset = 0;
     try {
         offset = fs.statSync(file).size;

package/dist/commands/exec.d.ts

@@ -6,6 +6,7 @@
  * injection, and multi-agent fallback chains for rate-limit resilience.
  */
 import { type Command } from 'commander';
+import type { ExecEffort } from '../lib/exec.js';
 /**
  * Build the LoopConfig the driver consumes from CLI flags and/or a workflow's
  * `loop:` frontmatter block (issue #332). Returns undefined when neither source
@@ -26,5 +27,23 @@ export declare function buildLoopConfig(flags: {
 }, workflowLoop?: import('../lib/workflows.js').LoopConfigRaw): import('../lib/loop.js').LoopConfig | undefined;
 /** Map a loop stop reason to a process exit code. condition-met/max are clean exits. */
 export declare function loopExitCode(stoppedBy: import('../lib/loop.js').LoopStoppedBy): number;
+/**
+ * Drive a workflow's declarative `for_each:` fan-out end-to-end (issue #343).
+ *
+ * Runs the producer, expands one stage teammate per produced item (respecting
+ * `max_items` / `DEFAULT_FOR_EACH_CAP`, surfacing any truncation — never a
+ * silent cap), stages them into a fresh team via the existing `runForEach`
+ * bridge, then drives the teams supervisor until the DAG drains. When a verify
+ * panel is declared, tallies each item's `keep_if` gate from the skeptics'
+ * terminal status and logs which items survived.
+ *
+ * Reuses the teams substrate wholesale — no new orchestration engine. Returns
+ * the process exit code (0 on drain, 1 on producer failure / non-drain).
+ */
+export declare function runWorkflowForEach(spec: import('../lib/workflows.js').ForEachSpec, opts: {
+    workflowName: string;
+    cwd: string;
+    effort?: ExecEffort;
+}): Promise<number>;
 /** Register the `agents run <agent> [prompt]` command. */
 export declare function registerRunCommand(program: Command): void;

package/dist/commands/exec.js

@@ -10,9 +10,11 @@ import chalk from 'chalk';
 import { setHelpSections } from '../lib/help.js';
 import { parseLoopInterval } from '../lib/loop.js';
 import { AGENTS } from '../lib/agents.js';
+import { recordDispatchedRun } from '../lib/audit/log.js';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
+import { randomUUID } from 'crypto';
 /** Type guard that narrows a string to a known AgentId. */
 function isValidAgent(agent) {
     return agent in AGENTS;
@@ -101,6 +103,100 @@ export function loopExitCode(stoppedBy) {
             return 1;
     }
 }
+/**
+ * Drive a workflow's declarative `for_each:` fan-out end-to-end (issue #343).
+ *
+ * Runs the producer, expands one stage teammate per produced item (respecting
+ * `max_items` / `DEFAULT_FOR_EACH_CAP`, surfacing any truncation — never a
+ * silent cap), stages them into a fresh team via the existing `runForEach`
+ * bridge, then drives the teams supervisor until the DAG drains. When a verify
+ * panel is declared, tallies each item's `keep_if` gate from the skeptics'
+ * terminal status and logs which items survived.
+ *
+ * Reuses the teams substrate wholesale — no new orchestration engine. Returns
+ * the process exit code (0 on drain, 1 on producer failure / non-drain).
+ */
+export async function runWorkflowForEach(spec, opts) {
+    const [{ produceItems, runForEach, tallyForEach }, { expandForEach, DEFAULT_FOR_EACH_CAP }, { AgentManager }, { createTeam }, { runSupervisor }, { ALL_AGENT_IDS }] = await Promise.all([
+        import('../lib/teams/forEach.js'),
+        import('../lib/workflows.js'),
+        import('../lib/teams/agents.js'),
+        import('../lib/teams/registry.js'),
+        import('../lib/teams/supervisor.js'),
+        import('../lib/agents.js'),
+    ]);
+    // The teams substrate spawns teammates as a real harness. When `agent:` names
+    // a known harness id, honor it; otherwise fall back to claude (the workflow
+    // harness) so a subagent-style name in `agent:` still runs.
+    const isHarness = (a) => ALL_AGENT_IDS.includes(a);
+    const runSpec = {
+        ...spec,
+        agent: isHarness(spec.agent) ? spec.agent : 'claude',
+        ...(spec.verify
+            ? { verify: { ...spec.verify, agent: isHarness(spec.verify.agent) ? spec.verify.agent : 'claude' } }
+            : {}),
+    };
+    if (runSpec.agent !== spec.agent) {
+        process.stderr.write(chalk.gray(`[for_each] '${spec.agent}' is not a harness id — staging stage teammates as claude\n`));
+    }
+    // 1. Producer: run the shell command (or resolve itemsRef) into the item list.
+    let items;
+    try {
+        items = await produceItems(runSpec, { cwd: opts.cwd });
+    }
+    catch (err) {
+        console.error(chalk.red(`[for_each] producer failed: ${err.message}`));
+        return 1;
+    }
+    if (items.length === 0) {
+        process.stderr.write(chalk.yellow('[for_each] producer emitted no items — nothing to fan out.\n'));
+        return 0;
+    }
+    // 2. Cap accounting (surfaced, never silent — acceptance criterion in #343).
+    const cap = runSpec.max_items ?? DEFAULT_FOR_EACH_CAP;
+    const { truncated } = expandForEach(runSpec, items);
+    if (truncated > 0) {
+        process.stderr.write(chalk.yellow(`[for_each] producer emitted ${items.length} items; capping at ${cap} (${truncated} dropped). Raise \`max_items\` to fan out more.\n`));
+    }
+    process.stderr.write(chalk.gray(`[for_each] ${Math.min(items.length, cap)} stage teammate(s) from ${items.length} produced item(s)\n`));
+    // 3. Stage the expanded teammates into a fresh team via the existing bridge.
+    const team = `foreach-${opts.workflowName.replace(/[^a-zA-Z0-9_-]/g, '-')}-${Date.now().toString(36)}`;
+    await createTeam(team, { description: `for_each fan-out from workflow '${opts.workflowName}'` });
+    const mgr = new AgentManager();
+    const { teammates } = await runForEach(mgr, team, runSpec, items, {
+        cwd: opts.cwd,
+        effort: opts.effort,
+        concurrency: runSpec.concurrency,
+    });
+    // 4. Drive the supervisor until the DAG drains (the same loop `teams start
+    // --watch` uses; it absorbs the staged teammates via rescanFromDisk).
+    const result = await runSupervisor(mgr, {
+        team,
+        onWave: (s) => {
+            const ts = s.timestamp.slice(11, 19);
+            process.stderr.write(`[${ts}] [for_each] wave ${s.wave}  launched=${s.launched.length}  running=${s.running}  pending=${s.pending}  done=${s.completed}  failed=${s.failed}\n`);
+        },
+    });
+    // 5. keep_if tally: a skeptic that COMPLETED is a keep vote; a failed skeptic
+    // votes to drop. Gate each item and report which survived.
+    if (runSpec.verify) {
+        const loaded = await mgr.listByTask(team);
+        const statusByName = new Map(loaded.map((a) => [a.name, a.status]));
+        const verdicts = tallyForEach(teammates, (v) => statusByName.get(v.name) === 'completed');
+        const kept = verdicts.filter((v) => v.kept);
+        process.stderr.write(chalk.gray(`[for_each] keep_if=${runSpec.verify.keep_if}: kept ${kept.length}/${verdicts.length} item(s)\n`));
+        for (const v of verdicts) {
+            const tag = v.kept ? chalk.green('keep') : chalk.red('drop');
+            process.stderr.write(chalk.gray(`  [${tag}] ${v.item} (${v.votes.filter(Boolean).length}/${v.votes.length} votes)\n`));
+        }
+    }
+    if (result.stoppedBy === 'drained') {
+        process.stderr.write(chalk.green(`[for_each] drained in ${Math.floor(result.elapsed_ms / 1000)}s (${result.waves} waves). Team: ${team}\n`));
+        return 0;
+    }
+    process.stderr.write(chalk.yellow(`[for_each] stopped by ${result.stoppedBy} after ${result.waves} waves. Team: ${team}\n`));
+    return 1;
+}
 /** Register the `agents run <agent> [prompt]` command. */
 export function registerRunCommand(program) {
     const runCmd = program
@@ -112,6 +208,8 @@ export function registerRunCommand(program) {
         .option('--env <key=value>', 'Pass environment variable to the agent (repeatable, e.g., --env DEBUG=1 --env API_KEY=xyz)', (val, prev) => [...prev, val], [])
         .option('--secrets <bundle>', 'Inject a secrets bundle (repeatable). Values resolve from macOS Keychain at run time. See `agents secrets`.', (val, prev) => [...prev, val], [])
         .option('--no-auto-secrets', 'Skip auto-injection of secrets declared by a workflow\'s frontmatter `secrets:` field. Has no effect on bare-agent runs.')
+        .option('--secrets-keys <keys>', 'Inject only this comma-separated subset of keys from --secrets bundles (e.g. KEY1,KEY2). Missing keys are an error. Applies to all --secrets bundles on this run.')
+        .option('--allow-expired', 'Inject secrets even if their expiry date has passed (overrides the pre-run expiry abort).')
         .option('--cwd <dir>', 'Working directory for the agent (defaults to current directory)')
         .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)')
@@ -133,7 +231,8 @@ export function registerRunCommand(program) {
         .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.')
-        .option('--host <name>', 'Offload this run onto a registered agent host over SSH instead of running locally. See `agents hosts`.')
+        .option('--host <name>', 'Offload this run onto another machine over SSH instead of running locally — a device, a registered agent host, or user@host. See `agents devices` / `agents hosts`.')
+        .option('--device <name>', 'Alias of --host: offload this run onto a registered device (from `agents devices`).')
         .option('--remote-cwd <dir>', 'Working directory on the host for --host runs.')
         .option('--no-follow', 'With --host, dispatch detached and return immediately (track via `agents hosts ps/logs`).')
         .option('--any', 'With --host <cap> (a capability tag), pick any matching host instead of erroring when several match.')
@@ -248,10 +347,10 @@ export function registerRunCommand(program) {
         }
         // --host/--on/--computer: offload this run onto a registered agent host
         // over SSH instead of running locally. The three flags are aliases.
-        const hostGiven = [options.host, options.on, options.computer].filter((v) => !!v);
+        const hostGiven = [options.host, options.device, options.on, options.computer].filter((v) => !!v);
         if (hostGiven.length > 0) {
             if (new Set(hostGiven).size > 1) {
-                console.error(chalk.red('Conflicting --host/--on/--computer values — pass just one.'));
+                console.error(chalk.red('Conflicting --host/--device values — pass just one.'));
                 process.exit(1);
             }
             const hostName = hostGiven[0];
@@ -261,6 +360,10 @@ export function registerRunCommand(program) {
             }
             const { resolveHost, resolveHostByCap } = await import('../lib/hosts/registry.js');
             const { dispatchToHost } = await import('../lib/hosts/dispatch.js');
+            const { registerHostSession } = await import('../lib/hosts/session-index.js');
+            // A password-auth device throws DeviceOffloadUnsupportedError here; it's
+            // printed cleanly by the top-level catch in index.ts (covers every
+            // resolveHost caller), so it never falls through to capability routing.
             let host = await resolveHost(hostName);
             if (!host) {
                 // Not a host name — try capability routing (e.g. --host gpu). A
@@ -282,14 +385,31 @@ export function registerRunCommand(program) {
                 process.exit(1);
             }
             try {
-                const { exitCode } = await dispatchToHost(host, {
-                    agent: agentSpec.split('@')[0],
+                const runAgent = agentSpec.split('@')[0];
+                // `--resume [id]`: commander yields the string id, or `true` when the
+                // flag is passed bare. A bare resume needs the interactive picker,
+                // which can't run over a detached remote dispatch — only forward a
+                // concrete id.
+                const resumeId = typeof options.resume === 'string' ? options.resume : undefined;
+                // Mirror the local path (lib/exec.ts): only Claude accepts a forced
+                // `--session-id`. Generating it here lets us register the run in the
+                // local index and makes it resumable by that id. On resume the remote
+                // session keeps its existing id — don't mint a new one.
+                const hostSessionId = runAgent === 'claude' && !resumeId ? randomUUID() : undefined;
+                const { task, exitCode } = await dispatchToHost(host, {
+                    agent: runAgent,
                     prompt,
                     mode: options.mode,
                     model: options.model,
                     remoteCwd: options.remoteCwd,
+                    sessionId: hostSessionId,
+                    resume: resumeId,
                     follow: options.follow !== false,
                 });
+                // Register the dispatched run in the LOCAL session index so it shows
+                // up in `agents sessions` and resolves by id, even though its
+                // transcript lives on the host. No-op when no session id was captured.
+                registerHostSession(task, { cwd: process.cwd(), prompt });
                 if (options.follow === false) {
                     console.log(chalk.green(`Dispatched to ${host.name}.`) + chalk.gray(' Track: agents hosts ps · Follow: agents hosts logs <id> -f'));
                     process.exit(0);
@@ -382,9 +502,20 @@ export function registerRunCommand(program) {
                 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));
+            // Governance chokepoint (#347): --resume-checkpoint short-circuits normal
+            // dispatch and exits here — record its one audit entry with the agent,
+            // version, and cwd reconstructed from the checkpoint.
+            const resumeExit = loopExitCode(result.stoppedBy);
+            recordDispatchedRun({
+                agent: cp.agent,
+                version: cp.version ?? 'unknown',
+                mode: resumeExec.mode ?? 'auto',
+                cwd: resumeExec.cwd ?? process.cwd(),
+                exitCode: resumeExit,
+            });
+            process.exit(resumeExit);
         }
-        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode, defaultModeFor, headlessPlanStallCommand, nativeResume, resolveInteractive }, { ALL_AGENT_IDS }, { profileExists, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle }, { splitBundleRef, resolveSshTarget, remoteResolveEnv }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, RUN_STRATEGIES }, { getGlobalDefault, getVersionHomePath, resolveVersion, resolveVersionAlias }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef, resolveAllowedSubagents }, { resolveRunDefaults }, { getMcpServersByName, buildWorkflowMcpConfig }, { supports },] = await Promise.all([
+        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode, defaultModeFor, headlessPlanStallCommand, nativeResume, resolveInteractive }, { ALL_AGENT_IDS }, { profileExists, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle, assertRemoteBundleFlagsUnsupported }, { splitBundleRef, resolveSshTarget, remoteResolveEnv }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, rotationFailoverChain, shouldArmRotationFailover, RUN_STRATEGIES }, { getGlobalDefault, getVersionHomePath, resolveVersion, resolveVersionAlias }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef, resolveAllowedSubagents, pruneStaleWorkflowSubagents }, { resolveRunDefaults }, { getMcpServersByName, buildWorkflowMcpConfig }, { supports },] = await Promise.all([
             import('../lib/exec.js'),
             import('../lib/agents.js'),
             import('../lib/profiles.js'),
@@ -405,13 +536,23 @@ export function registerRunCommand(program) {
         let version = rawVersion || undefined;
         let profileEnv;
         let fromProfile = false;
+        let profileFallbackModel;
         let workflowModel;
         // WORKFLOW.md capability scoping, translated to Claude headless flags below.
         let workflowToolsRestrict;
         let workflowMcpConfigPath;
+        // Full paths of workflow subagent files THIS run copied into the shared
+        // per-agent agents dir. Torn down after the run to restore the shared dir
+        // (issue #401), mirroring cleanupWorkflowMcpConfig for the mcp-config.
+        const workflowSubagentTargets = [];
         // WORKFLOW.md `loop:` block (issue #332). When a workflow declares it,
         // `agents run <workflow>` honors the loop without a --loop flag.
         let workflowLoop;
+        // WORKFLOW.md `for_each:` block (issue #343). When a workflow declares it,
+        // `agents run <workflow>` runs the producer, expands one stage teammate per
+        // produced item, and drives the teams supervisor to drain — no `teams`
+        // subcommands needed.
+        let workflowForEach;
         const cwd = options.cwd ?? process.cwd();
         if (isValidAgent(rawAgent)) {
             agent = rawAgent;
@@ -427,6 +568,7 @@ export function registerRunCommand(program) {
                 if (!version)
                     version = resolved.version;
                 profileEnv = resolved.env;
+                profileFallbackModel = resolved.fallbackModel;
                 fromProfile = true;
                 process.stderr.write(chalk.gray(`Resolved profile '${resolved.profileName}' -> ${agent}${version ? `@${version}` : ''}\n`));
             }
@@ -448,6 +590,7 @@ export function registerRunCommand(program) {
                 workflowModel = workflowFrontmatter.model.trim();
             }
             workflowLoop = workflowFrontmatter?.loop;
+            workflowForEach = workflowFrontmatter?.forEach;
             const resolvedVersion = resolveVersionAlias('claude', version);
             const versionHome = getVersionHomePath('claude', resolvedVersion ?? getGlobalDefault('claude') ?? '');
             const claudeAgentsDir = path.join(versionHome, '.claude', 'agents');
@@ -469,6 +612,15 @@ export function registerRunCommand(program) {
                 const allFiles = fs.readdirSync(subagentsDir).filter(f => f.endsWith('.md'));
                 const { allowedStems, missing } = resolveAllowedSubagents(allFiles, allowedAgents);
                 const allowStemSet = new Set(allowedStems);
+                // Fail-closed prune (issue #401, follow-up to #324). A prior
+                // unrestricted run may have left workflow subagent files that THIS
+                // scoped run does not permit; they linger in the shared dir and stay
+                // dispatchable. Remove those no-longer-permitted workflow-managed
+                // files BEFORE writing the allowed set — never a user's own subagent.
+                const pruned = pruneStaleWorkflowSubagents(claudeAgentsDir, allFiles, allowedStems);
+                if (pruned.length > 0) {
+                    process.stderr.write(chalk.gray(`[workflow] pruned ${pruned.length} stale workflow subagent(s) from shared dir: ${pruned.join(', ')}\n`));
+                }
                 let copied = 0;
                 let skipped = 0;
                 for (const file of allFiles) {
@@ -477,7 +629,9 @@ export function registerRunCommand(program) {
                         skipped++;
                         continue;
                     }
-                    fs.copyFileSync(path.join(subagentsDir, file), path.join(claudeAgentsDir, file));
+                    const dest = path.join(claudeAgentsDir, file);
+                    fs.copyFileSync(path.join(subagentsDir, file), dest);
+                    workflowSubagentTargets.push(dest);
                     copied++;
                 }
                 if (allowedAgents !== undefined) {
@@ -722,6 +876,10 @@ export function registerRunCommand(program) {
         }
         const configuredStrategy = getConfiguredRunStrategy(agent, cwd);
         const explicitStrategy = options.strategy ? normalizeRunStrategy(options.strategy) : null;
+        // Captured from resolveRunVersion below so mid-run rate-limit failover can
+        // synthesize a same-agent fallback chain from the other healthy accounts
+        // (issue #348). Stays null unless a non-pinned strategy actually rotated.
+        let rotationResult = null;
         if (options.strategy && !explicitStrategy) {
             console.error(chalk.red(`Invalid strategy: ${options.strategy}. Use ${RUN_STRATEGIES.join(', ')}.`));
             process.exit(1);
@@ -748,6 +906,7 @@ export function registerRunCommand(program) {
                     const resolved = await resolveRunVersion(agent, strategy, cwd);
                     if (resolved.version) {
                         version = resolved.version;
+                        rotationResult = resolved.rotation;
                         if (resolved.rotation && !options.quiet) {
                             const banner = formatRotationBanner(resolved.rotation, strategy);
                             process.stderr.write(chalk.gray(banner + '\n'));
@@ -836,11 +995,19 @@ export function registerRunCommand(program) {
         // Resolve --secrets bundles in flag order. Later bundles override earlier
         // ones. Any resolution failure (missing keychain item, blocked exec ref)
         // aborts before spawn so the agent never sees a partial env.
+        const secretsKeysSubset = options.secretsKeys
+            ? options.secretsKeys.split(',').map((k) => k.trim()).filter(Boolean)
+            : undefined;
         let secretsEnv = {};
         for (const bundleRef of options.secrets) {
             try {
                 const { bundle: bundleName, host } = splitBundleRef(bundleRef);
                 if (host) {
+                    // Least-privilege flags (--secrets-keys / --allow-expired) do not
+                    // yet cross the SSH resolver — silently applying them would inject
+                    // the full remote env or an expired key. Fail loud so the user
+                    // can drop the flag or resolve locally instead.
+                    assertRemoteBundleFlagsUnsupported(bundleName, host, { keys: secretsKeysSubset, allowExpired: options.allowExpired }, { keysFlag: '--secrets-keys', allowExpiredFlag: '--allow-expired' });
                     // Remote bundle (`bundle@host`): resolve over SSH and inject
                     // ephemerally — values never touch this machine's keychain or disk.
                     const target = await resolveSshTarget(host);
@@ -849,7 +1016,11 @@ export function registerRunCommand(program) {
                     secretsEnv = { ...secretsEnv, ...bundleEnv };
                 }
                 else {
-                    const { bundle, env: bundleEnv } = readAndResolveBundleEnv(bundleName, { caller: `agent ${agent}` });
+                    const { bundle, env: bundleEnv } = readAndResolveBundleEnv(bundleName, {
+                        caller: `agent ${agent}`,
+                        keys: secretsKeysSubset,
+                        allowExpired: options.allowExpired,
+                    });
                     const entries = describeBundle(bundle);
                     const counts = {};
                     for (const e of entries) {
@@ -945,6 +1116,50 @@ export function registerRunCommand(program) {
                 fallback.push({ agent: fbAgent, version: resolveVersionAlias(fbAgent, fbVersion || undefined) });
             }
         }
+        // Profile-declared same-host model swap (issue #325). Inserted BEFORE any
+        // user --fallback entries so a rate limit first tries the cheaper/backup
+        // model on the same provider (auth + base URL preserved via envOverride);
+        // only if THAT still rate-limits do we cascade to a different agent CLI.
+        // Requires a prompt for the same reason --fallback does — headless-only.
+        if (fromProfile && profileFallbackModel && prompt !== undefined && !options.interactive) {
+            fallback.unshift({
+                agent,
+                version,
+                envOverride: { [profileFallbackModel.envKey]: profileFallbackModel.model },
+            });
+        }
+        // Mid-run rate-limit failover (issue #348). When a pre-flight rotation
+        // picked an account and there are OTHER healthy accounts for the same
+        // agent, synthesize a same-agent fallback chain from them so a 429 mid-run
+        // re-dispatches on the next healthy account via the SAME runWithFallback
+        // path (continuing the session via /continue). Because this injects into
+        // the same `fallback` array `--fallback` uses, it must only arm for run
+        // shapes that accept a fallback chain — shouldArmRotationFailover excludes
+        // acp/loop/resume-checkpoint (which reject a non-empty fallback below),
+        // interactive/no-prompt runs, and runs that already have an explicit or
+        // profile fallback. Pinned/single-account runs stay unchanged because
+        // rotationResult is null or rotationFailoverChain returns []. version is
+        // set here because rotationResult is only populated when resolveRunVersion
+        // picked one.
+        if (shouldArmRotationFailover({
+            hasRotation: !!rotationResult,
+            hasVersion: !!version,
+            hasPrompt: prompt !== undefined,
+            explicitFallback: fallback.length > 0,
+            interactive: !!options.interactive,
+            acp: !!options.acp,
+            loop: !!options.loop,
+            resumeCheckpoint: !!options.resumeCheckpoint,
+        })) {
+            const failover = rotationFailoverChain(rotationResult, version);
+            if (failover.length > 0) {
+                fallback.push(...failover);
+                if (!options.quiet) {
+                    const accounts = failover.map(f => `${f.agent}@${f.version}`).join(', ');
+                    process.stderr.write(chalk.gray(`[agents] rate-limit failover armed: ${accounts}\n`));
+                }
+            }
+        }
         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.'));
@@ -968,6 +1183,9 @@ export function registerRunCommand(program) {
                     mode,
                     json: options.json ?? false,
                 });
+                // Governance chokepoint (#347): the --acp path exits here, bypassing
+                // the normal finalize below — record its one audit entry.
+                recordDispatchedRun({ agent, version: defaultVersion ?? 'unknown', mode, cwd, exitCode });
                 process.exit(exitCode);
             }
             catch (err) {
@@ -1049,6 +1267,36 @@ export function registerRunCommand(program) {
                 // best-effort: nothing actionable if the temp dir is already gone.
             }
         };
+        // Restore the shared per-agent agents dir after the run (issue #401):
+        // remove the workflow subagent files THIS run copied in, so a scoped
+        // workflow never leaves definitions behind for the next, unrelated run to
+        // inherit. Mirrors cleanupWorkflowMcpConfig — tear down only what we made.
+        const cleanupWorkflowSubagents = () => {
+            for (const target of workflowSubagentTargets) {
+                try {
+                    fs.rmSync(target, { force: true });
+                }
+                catch {
+                    // best-effort: nothing actionable if the file is already gone.
+                }
+            }
+        };
+        // for_each dispatch (issue #343). A workflow that declares `for_each:` is a
+        // declarative dynamic fan-out, not a single-agent run: execute the producer,
+        // expand one stage teammate per produced item (+ optional verify panel),
+        // stage them into a team, then drive the supervisor until the DAG drains.
+        // This is mutually exclusive with the single-agent loop/fallback paths — the
+        // fan-out IS the run.
+        if (workflowForEach) {
+            cleanupWorkflowMcpConfig();
+            cleanupWorkflowSubagents();
+            const exitCode = await runWorkflowForEach(workflowForEach, {
+                workflowName: rawAgent,
+                cwd,
+                effort: options.effort,
+            });
+            process.exit(exitCode);
+        }
         // 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
@@ -1088,29 +1336,47 @@ export function registerRunCommand(program) {
                     version,
                 });
                 cleanupWorkflowMcpConfig();
+                cleanupWorkflowSubagents();
                 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));
+                // Governance chokepoint (#347): the --loop path exits here, bypassing
+                // the normal finalize below — record its one audit entry.
+                const loopExit = loopExitCode(result.stoppedBy);
+                recordDispatchedRun({ agent, version: defaultVersion ?? 'unknown', mode, cwd, exitCode: loopExit });
+                process.exit(loopExit);
             }
             catch (err) {
                 cleanupWorkflowMcpConfig();
+                cleanupWorkflowSubagents();
                 console.error(chalk.red(`Loop failed for ${agent}: ${err.message}`));
                 process.exit(1);
             }
         }
         try {
             let exitCode;
+            let ranAgent = agent;
+            let ranVersion = defaultVersion;
             if (fallback.length > 0) {
                 // fallback requires a prompt — enforced above, narrow the type here.
-                exitCode = await runWithFallback({ ...execOptions, prompt: prompt, fallback });
+                // The sink reports which chain entry actually executed (may differ from
+                // the primary after a rate-limit handoff) so the audit record is honest.
+                const sink = {};
+                exitCode = await runWithFallback({ ...execOptions, prompt: prompt, fallback, dispatchSink: sink });
+                ranAgent = sink.agent ?? agent;
+                ranVersion = sink.version ?? defaultVersion;
             }
             else {
                 exitCode = await execAgent(execOptions);
             }
             cleanupWorkflowMcpConfig();
+            cleanupWorkflowSubagents();
+            // Governance chokepoint (#347): every dispatched run finalizes here.
+            // ONE tamper-evident audit record per run — non-fatal by contract.
+            recordDispatchedRun({ agent: ranAgent, version: ranVersion ?? 'unknown', mode, cwd, exitCode });
             process.exit(exitCode);
         }
         catch (err) {
             cleanupWorkflowMcpConfig();
+            cleanupWorkflowSubagents();
             console.error(chalk.red(`Failed to execute ${agent}: ${err.message}`));
             process.exit(1);
         }