@phnx-labs/agents-cli 1.20.34 → 1.20.36

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,19 +385,41 @@ 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);
                 }
-                process.exit(exitCode === undefined || exitCode === -1 ? 1 : exitCode);
+                // -1 = the follow window closed but the run continues on the host (the
+                // reattach hint is already printed). That's a detach, not a failure —
+                // exit 0. Any real remote code passes through.
+                if (exitCode === -1)
+                    process.exit(0);
+                process.exit(exitCode ?? 1);
             }
             catch (err) {
                 console.error(chalk.red(err.message));
@@ -377,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'),
@@ -400,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;
@@ -422,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`));
             }
@@ -443,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');
@@ -464,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) {
@@ -472,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) {
@@ -717,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);
@@ -743,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'));
@@ -831,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);
@@ -844,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) {
@@ -940,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.'));
@@ -963,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) {
@@ -1044,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
@@ -1083,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);
         }

package/dist/commands/hosts.js

@@ -7,15 +7,17 @@
  * hosts. Dispatch itself is `agents run --host <name>` (see commands/exec.ts).
  */
 import chalk from 'chalk';
+import { terminalWidth, truncateToWidth, stringWidth } from '../lib/session/width.js';
 import { checkbox, confirm } from '@inquirer/prompts';
 import { assertValidSshTarget } from '../lib/ssh-exec.js';
 import { getProvider, listAllHosts, resolveHost } from '../lib/hosts/registry.js';
 import { sshTargetFor } from '../lib/hosts/types.js';
 import { listSshConfigHosts, listKnownHosts, isSshConfigHost } from '../lib/hosts/ssh-config.js';
 import { probeHost, remoteAgentsVersion, bootstrapAgentsCli, localCliVersion, } from '../lib/hosts/ready.js';
-import { listTasks, loadTask, localLogPath } from '../lib/hosts/tasks.js';
-import { followHostTask } from '../lib/hosts/progress.js';
-import * as fs from 'fs';
+import { resolveRemoteOsSync } from '../lib/hosts/remote-os.js';
+import { listTasks } from '../lib/hosts/tasks.js';
+import { reconcileRunningTasks } from '../lib/hosts/reconcile.js';
+import { showHostTaskLog } from '../lib/hosts/logs.js';
 /** Parse `user@host` or `host` into its pieces. */
 function parseTarget(target) {
     const at = target.indexOf('@');
@@ -23,20 +25,25 @@ function parseTarget(target) {
         return { address: target };
     return { user: target.slice(0, at), address: target.slice(at + 1) };
 }
-/** Bootstrap/verify agents-cli on a freshly-enrolled host (best-effort, prompts). */
-async function maybeBootstrap(target, hostName) {
-    const probe = probeHost(target);
+/**
+ * Bootstrap/verify agents-cli on a freshly-enrolled host (best-effort, prompts).
+ * Callers that just probed the host pass the result through to avoid a second,
+ * redundant `uname` round-trip; otherwise we probe here.
+ */
+async function maybeBootstrap(target, hostName, probe = probeHost(target, resolveRemoteOsSync(hostName))) {
     if (!probe.reachable) {
         console.log(chalk.yellow(`  Not reachable over SSH yet — skipping bootstrap. Fix key auth, then: agents hosts check ${hostName}`));
         return;
     }
-    const remoteVer = remoteAgentsVersion(target);
+    // Prefer the OS the probe just observed; fall back to the registry hint.
+    const os = probe.os ?? resolveRemoteOsSync(hostName);
+    const remoteVer = remoteAgentsVersion(target, os);
     const localVer = localCliVersion();
     if (!remoteVer) {
         const ok = await confirm({ message: `  agents-cli not found on ${hostName}. Install ${localVer ? `v${localVer}` : 'latest'} now?`, default: true });
         if (ok) {
             console.log(chalk.gray('  Installing agents-cli on the host…'));
-            const r = bootstrapAgentsCli(target, localVer);
+            const r = bootstrapAgentsCli(target, localVer, os);
             console.log(r.ok ? chalk.green('  Installed.') : chalk.red(`  Install failed:\n${r.output}`));
         }
         return;
@@ -45,7 +52,7 @@ async function maybeBootstrap(target, hostName) {
     if (localVer && remoteClean !== localVer) {
         const ok = await confirm({ message: `  ${hostName} has agents-cli ${remoteClean}, you have ${localVer}. Upgrade to match?`, default: false });
         if (ok) {
-            const r = bootstrapAgentsCli(target, localVer);
+            const r = bootstrapAgentsCli(target, localVer, os);
             console.log(r.ok ? chalk.green('  Upgraded.') : chalk.red(`  Upgrade failed:\n${r.output}`));
         }
     }
@@ -75,7 +82,7 @@ async function doAdd(name, target, opts) {
             await registerHost({ name: c, provider: 'local', source, ...(source === 'inline' ? { address: c } : {}), os: probe.os, caps: opts.cap });
             console.log(chalk.green(`Enrolled ${c}`) + chalk.gray(` (${source}${probe.os ? `, ${probe.os}` : ''})`));
             if (opts.enroll !== false)
-                await maybeBootstrap(c, c);
+                await maybeBootstrap(c, c, probe);
         }
         return;
     }
@@ -107,7 +114,7 @@ async function doAdd(name, target, opts) {
     await registerHost(spec);
     console.log(chalk.green(`Enrolled ${name}`) + chalk.gray(` (${spec.source}${spec.os ? `, ${spec.os}` : ''}${spec.caps?.length ? `, caps: ${spec.caps.join(',')}` : ''})`));
     if (opts.enroll !== false)
-        await maybeBootstrap(sshTarget, name);
+        await maybeBootstrap(sshTarget, name, probe);
 }
 async function doList(json) {
     const hosts = await listAllHosts();
@@ -122,8 +129,11 @@ async function doList(json) {
     console.log(chalk.bold('NAME').padEnd(20) + chalk.bold('SOURCE').padEnd(13) + chalk.bold('TARGET').padEnd(28) + chalk.bold('CAPS'));
     for (const h of hosts) {
         const tgt = h.source === 'ssh-config' ? chalk.gray('(ssh-config)') : `${h.user ? h.user + '@' : ''}${h.address ?? ''}`;
+        // Cap TARGET at its column so a long user@host can't shove CAPS out of alignment.
+        const tgtW = stringWidth(tgt);
+        const tgtCol = tgtW > 28 ? truncateToWidth(tgt, 28) : tgt + ' '.repeat(28 - tgtW);
         const mark = h.enrolled ? '' : chalk.gray(' ·available');
-        console.log(h.name.padEnd(20) + h.source.padEnd(13) + tgt.padEnd(28) + (h.caps?.join(',') ?? '') + mark);
+        console.log(h.name.padEnd(20) + h.source.padEnd(13) + tgtCol + (h.caps?.join(',') ?? '') + mark);
     }
 }
 async function doCheck(name) {
@@ -134,15 +144,16 @@ async function doCheck(name) {
         return;
     }
     const target = sshTargetFor(host);
+    const os = host.os ?? resolveRemoteOsSync(name);
     process.stdout.write(`Probing ${chalk.cyan(name)} (${target})… `);
-    const probe = probeHost(target);
+    const probe = probeHost(target, os);
     if (!probe.reachable) {
         console.log(chalk.red('unreachable'));
         process.exitCode = 1;
         return;
     }
     console.log(chalk.green('reachable') + chalk.gray(probe.os ? ` · ${probe.os}` : ''));
-    const ver = remoteAgentsVersion(target);
+    const ver = remoteAgentsVersion(target, probe.os ?? os);
     console.log(`  agents-cli: ${ver ? chalk.green(ver) : chalk.yellow('not installed')}`);
 }
 async function doRemove(name) {
@@ -155,7 +166,10 @@ async function doRemove(name) {
     console.log(chalk.green(`Removed ${name}`));
 }
 async function doPs(json) {
-    const tasks = listTasks();
+    // Heal any 'running' record whose local follower died (dropped connection,
+    // laptop sleep) against the remote `.exit` before listing, so `ps` never shows
+    // a finished run stuck at 'running'.
+    const tasks = reconcileRunningTasks(listTasks());
     if (json) {
         console.log(JSON.stringify(tasks, null, 2));
         return;
@@ -164,30 +178,24 @@ async function doPs(json) {
         console.log(chalk.gray('No host tasks yet. Dispatch one: agents run <agent> "<task>" --host <name>'));
         return;
     }
+    const cols = terminalWidth();
     console.log(chalk.bold('ID').padEnd(11) + chalk.bold('HOST').padEnd(16) + chalk.bold('AGENT').padEnd(10) + chalk.bold('STATUS').padEnd(11) + chalk.bold('PROMPT'));
     for (const t of tasks) {
         const status = t.status === 'completed' ? chalk.green(t.status) : t.status === 'failed' ? chalk.red(t.status) : chalk.yellow(t.status);
-        console.log(t.id.padEnd(11) + t.host.padEnd(16) + t.agent.padEnd(10) + status.padEnd(11) + t.prompt.slice(0, 50));
+        // Prompt fills the remaining width instead of a fixed 50-char byte slice (98-char rows).
+        const promptCol = truncateToWidth(t.prompt, Math.max(12, cols - (11 + 16 + 10 + 11)));
+        console.log(t.id.padEnd(11) + t.host.padEnd(16) + t.agent.padEnd(10) + status.padEnd(11) + promptCol);
     }
 }
 async function doLogs(id, follow) {
-    const task = loadTask(id);
-    if (!task) {
+    const res = await showHostTaskLog(id, follow);
+    if (!res.found) {
         console.log(chalk.red(`Unknown task "${id}".`));
         process.exitCode = 1;
         return;
     }
-    if (follow && task.status === 'running') {
-        const code = await followHostTask(task.target, { remoteLog: task.remoteLog, remoteExit: task.remoteExit, taskId: id, echo: true });
-        process.exitCode = code === -1 ? 1 : code;
-        return;
-    }
-    try {
-        process.stdout.write(fs.readFileSync(localLogPath(id), 'utf-8'));
-    }
-    catch {
-        console.log(chalk.gray('(no local log captured for this task)'));
-    }
+    if (res.exitCode !== undefined)
+        process.exitCode = res.exitCode;
 }
 /** Register the `agents hosts` command tree. */
 export function registerHostsCommand(program) {