@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/commands/exec.js

@@ -1,10 +1,3 @@
-/**
- * Agent execution command.
- *
- * Registers the `agents run` command which spawns agent CLIs interactively
- * or headlessly. Supports profile resolution, version rotation, secrets
- * injection, and multi-agent fallback chains for rate-limit resilience.
- */
 import { InvalidArgumentError, Option } from 'commander';
 import chalk from 'chalk';
 import { isTierToken } from '../lib/model-tiers.js';
@@ -26,28 +19,17 @@ import * as path from 'path';
 import * as os from 'os';
 import { spawnSync } from 'child_process';
 import { randomUUID } from 'crypto';
-import { isSessionTrackedAgent } from '../lib/session/types.js';
+import { isSessionTrackedAgent } from '@phnx-labs/sessions-cli/reader';
 import { applyActiveRulesPresetAtRun } from '../lib/rules/run-sync.js';
 import { applySystemResourcesAtRun } from '../lib/system-run-sync.js';
 import { handleBroadcast } from './run-broadcast.js';
 import { bootMark } from '../lib/boot-profile.js';
-/** Validate a caller-supplied session id before it reaches tmux, paths, indexes, or remote dispatch. */
 export function parseExplicitSessionId(value) {
     if (!/^[A-Za-z0-9._-]+$/.test(value)) {
         throw new InvalidArgumentError('must contain only ASCII letters, digits, dots, underscores, or hyphens');
     }
     return value;
 }
-/**
- * Parse the trailing picker markers on an `agents run` agent spec. A terminal
- * run of `#`/`@` characters requests the account picker (`#`) and/or the
- * device picker (`@`) — each at most once, in either order (`claude#@`,
- * `claude@#`). Stripping them yields the normalized spec (`claude#work@` →
- * `claude#work`, version pins and `#label` account pins intact). A picker
- * cannot combine with an explicit pin of what it picks: `claude@2.1.218#`
- * (the account picker already chooses the version — the old `claude@2.1.218@`
- * rule), `claude#work#`, `claude@@`.
- */
 export function parseRunPickerMarkers(agentSpec) {
     let rest = agentSpec;
     let accountPicker = false;
@@ -80,24 +62,9 @@ export function parseRunPickerMarkers(agentSpec) {
     }
     return { accountPicker, devicePicker, normalizedAgentSpec: rest, valid: reason === undefined, reason };
 }
-/**
- * The `--device` alias family — the flags that mean "dispatch this run to another
- * machine over SSH". `--device` is canonical; `--on`/`--computer` are hidden
- * aliases. Returns the values actually given (so callers can both test presence
- * and read the target). Kept in ONE place because a guard that listed only a
- * subset silently let `--terminal --device` open a local tab and drop the remote
- * target — the drift this predicate exists to prevent.
- */
 export function hostTargetGiven(options) {
     return [options.host, options.device, options.on, options.computer].filter((v) => !!v);
 }
-/**
- * Turn a host target that names THIS machine into an explicit local pin: the
- * host-family flags are cleared and `local` is set, so no dispatch path
- * self-SSHes and the bare-interactive default (`bareInteractiveRunDefaultsToDeviceAuto`)
- * sees a decided placement. Returns true when the pin was applied. Pure over
- * the `isSelf` predicate so the rule is testable without a device registry.
- */
 export function pinLocalWhenTargetIsSelf(options, isSelf) {
     const targets = hostTargetGiven(options);
     if (targets.length === 0 || !targets.every(isSelf))
@@ -109,11 +76,6 @@ export function pinLocalWhenTargetIsSelf(options, isSelf) {
     options.local = true;
     return true;
 }
-/**
- * Return every option whose selection semantics conflict with an account
- * choice (`agent#`). Device routing is deliberately absent: the marker rides
- * the hop and the peer picks from ITS slots.
- */
 export function runAccountPickerConflicts(options) {
     const conflicts = [];
     if (options.resume !== undefined)
@@ -130,11 +92,6 @@ export function runAccountPickerConflicts(options) {
         conflicts.push(`--account ${options.account}`);
     return conflicts;
 }
-/**
- * Return every option that already decides where the run lands, so a device
- * choice (`agent@`) would be silently ignored: any explicit host flag, and the
- * lease/box paths, which own placement outright.
- */
 export function runDevicePickerConflicts(options) {
     const conflicts = hostTargetGiven(options).map((h) => `--device ${h}`);
     if (options.local)
@@ -145,30 +102,11 @@ export function runDevicePickerConflicts(options) {
         conflicts.push('--box');
     return conflicts;
 }
-/** Type guard that narrows a string to a known AgentId. */
 function isValidAgent(agent) {
     return agent in AGENTS;
 }
-// Reserved `<agent>` keyword for `agents run auto` — canonical definition in
-// lib/types.ts (shared with the host dispatch layer); re-exported here.
 export { RUN_AUTO_KEYWORD };
-/**
- * Whether `run auto` should default its host layer to the affinity pick (the
- * same machinery as `--device auto`). False when the caller pinned any host
- * flag, and false when this process was itself dispatched by a host run —
- * the dispatcher exports AGENTS_RUN_AUTO_HOST_RESOLVED=1 into the remote SHELL
- * (hosts/dispatch.ts remoteRunShellPrelude) because it already resolved the
- * host layer, and re-picking here would chain-hop the run across the fleet.
- * An INTERACTIVE dispatch of a named harness also reaches the remote as a bare
- * `agents run <harness>` (its argv forwards without the routing flag), so the
- * interactive prelude's AGENTS_REMOTE_INTERACTIVE=1 counts as "already placed"
- * too — without it the remote would re-place the run and ping-pong across the
- * fleet. Pure so the pinning matrix is unit-testable.
- */
 export function runAutoDefaultsToAffinity(options, env = process.env) {
-    // An explicit local pin (--local, --where local, --device <this machine>)
-    // is a decided host layer with an empty host set; read it here so the
-    // `run auto` and bare-interactive defaults share one rule.
     if (options.local)
         return false;
     if (hostTargetGiven(options).length > 0)
@@ -177,27 +115,6 @@ export function runAutoDefaultsToAffinity(options, env = process.env) {
         return false;
     return env.AGENTS_REMOTE_INTERACTIVE !== '1';
 }
-/**
- * Whether a bare human-facing `agents run <harness>` — no prompt, so an
- * interactive TUI run — defaults its placement to `--device auto` (PHNX-4083).
- * A marker left off is decided for you: no `#` means balanced rotation, and no
- * `@` (and no other placement flag) now means automatic device placement — the
- * same engine as `--device auto`, whose pool never contains a box marked
- * `personal`. ALL of these must hold:
- *
- * - no prompt (headless runs — teams, routines, hooks, `run <agent> "…"` —
- *   keep running in place, unchanged);
- * - a human-facing surface: a real TTY and no `--json`. This is the same
- *   two-condition gate `signInLaunchDecision` uses in run-account-picker.ts —
- *   reused here through isHumanFacingRun, not re-derived;
- * - no device-picker marker (`agent@` already chose the device; picking this
- *   machine there is a plain local run);
- * - no `--resume` / `--lease` / `--box` / `--cloud` (those own placement);
- * - the host layer is unpinned and this process is not itself a dispatched
- *   hop — delegated to runAutoDefaultsToAffinity, which encodes both.
- *
- * Pure so the default-placement matrix is unit-testable.
- */
 export function bareInteractiveRunDefaultsToDeviceAuto(options, run, surface, env = process.env) {
     if (run.prompt !== undefined)
         return false;
@@ -209,15 +126,6 @@ export function bareInteractiveRunDefaultsToDeviceAuto(options, run, surface, en
         return false;
     return runAutoDefaultsToAffinity(options, env);
 }
-/**
- * Whether an interactive host dispatch must mint a correlation launch id and
- * resolve the remote session via the launch-id join (RUSH-2034), rather than
- * trusting a pre-known session id. `run auto` ALWAYS joins: the harness is
- * picked on the remote, so an explicit --session-id is only adopted when the
- * pick lands on claude — pre-registering it would strand a stale session-index
- * entry naming an id a non-claude pick never used (RUSH-2132). Pure so the
- * decision matrix is unit-testable.
- */
 export function hostInteractiveNeedsCorrelationId(runAgent, hostSessionId, resumeId) {
     if (resumeId)
         return false;
@@ -225,70 +133,39 @@ export function hostInteractiveNeedsCorrelationId(runAgent, hostSessionId, resum
         return true;
     return !hostSessionId && isSessionTrackedAgent(runAgent);
 }
-/** Build a one-line banner describing which version the strategy picked. */
 function formatRotationBanner(result, verb = 'balanced') {
     const { picked, healthy, excluded } = result;
     const label = picked.email ? `${picked.email} · ${picked.agent}@${picked.version}` : `${picked.agent}@${picked.version}`;
     const ratio = `${healthy.length} of ${healthy.length + excluded.length} healthy`;
-    // Say it when the pick was a guess. A machine whose usage refresh is failing
-    // reports old percentages with total confidence, so a silent banner reads
-    // identical whether the router knew the account had headroom or merely hoped
-    // so — and the operator only finds out when the agent answers "you've hit
-    // your weekly limit".
     const caveat = result.usageUnverified ? ', usage unverified — no account could be refreshed' : '';
     return `[agents] ${verb} picked ${label} (${ratio}${caveat})`;
 }
-/**
- * Whether `cwd` is inside a git work tree.
- *
- * `--lease` / `--box` sync the working directory to the box through crabbox,
- * which enumerates the files to copy with `git ls-files`. Outside a git repo
- * that exits 128 (`fatal: not a git repository`) and the whole run dies at
- * "build sync file list: exit status 128" — AFTER the box is provisioned and
- * billed. Checking this up front lets the caller fail fast, before provisioning.
- */
 export function isInsideGitWorkTree(cwd) {
     const r = spawnSync('git', ['-C', cwd, 'rev-parse', '--is-inside-work-tree'], {
         encoding: 'utf-8',
     });
     return r.status === 0 && r.stdout.trim() === 'true';
 }
-/** Absolute git toplevel for `cwd`, or null when it is not a git repo. */
 export function gitToplevel(cwd) {
     const r = spawnSync('git', ['-C', cwd, 'rev-parse', '--show-toplevel'], { encoding: 'utf-8' });
     return r.status === 0 ? r.stdout.trim() : null;
 }
-/**
- * Network mode for a `--lease` run (F5, RUSH-1924). `--tailscale` forces the
- * tailnet, `--no-tailscale` forces public, and neither (undefined) defaults to
- * the tailnet ONLY in a reuse context (`--reuse`, `--box`, or a picked warm
- * box) — a one-shot solo `--lease` stays public. Pure so it is unit-testable;
- * the caller downgrades to `'public'` when no auth key is configured.
- */
 export function computeNetMode(opts) {
     if (opts.tailscale === false)
-        return 'public'; // --no-tailscale wins
+        return 'public';
     if (opts.tailscale === true)
-        return 'tailscale'; // explicit --tailscale
+        return 'tailscale';
     return opts.reuseContext ? 'tailscale' : 'public';
 }
-// ── "Always provision fresh" per-repo memory (F3, RUSH-1922) ─────────────────
-// The picker's "Always provision fresh (remember for this repo)" choice is
-// persisted as a list of git-toplevel paths in a small state file, so a repo
-// that opted out of the reuse picker is never prompted again.
-/** True when `repoRoot` is in the remembered always-fresh set. Pure. */
 export function isAlwaysFreshRepo(repos, repoRoot) {
     return repos.includes(repoRoot);
 }
-/** Add `repoRoot` to the always-fresh set (idempotent). Pure. */
 export function addAlwaysFreshRepo(repos, repoRoot) {
     return repos.includes(repoRoot) ? repos : [...repos, repoRoot];
 }
-/** Path to the always-fresh state file under the USER agents dir (CLI-written per-user preference, never the maintainer-owned `.system` repo). */
 export function leaseFreshReposPath() {
     return path.join(getUserAgentsDir(), 'lease-fresh-repos.json');
 }
-/** Read the remembered always-fresh repo roots (empty on any read/parse error). */
 export function readAlwaysFreshRepos() {
     try {
         const parsed = JSON.parse(fs.readFileSync(leaseFreshReposPath(), 'utf-8'));
@@ -298,7 +175,6 @@ export function readAlwaysFreshRepos() {
         return [];
     }
 }
-/** Persist the always-fresh repo roots. Best-effort — never throws. */
 export function writeAlwaysFreshRepos(repos) {
     try {
         const p = leaseFreshReposPath();
@@ -306,26 +182,13 @@ export function writeAlwaysFreshRepos(repos) {
         fs.writeFileSync(p, JSON.stringify(repos, null, 2));
     }
     catch {
-        /* best-effort — losing the preference just means the picker shows next time */
     }
 }
-/**
- * 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') {
@@ -333,7 +196,6 @@ export function buildLoopConfig(flags, workflowLoop) {
         }
         cfg.until = 'signal';
     }
-    // max_iterations: CLI > workflow.
     if (flags.maxIterations !== undefined) {
         const n = Number(flags.maxIterations);
         if (!Number.isInteger(n) || n <= 0) {
@@ -344,7 +206,6 @@ export function buildLoopConfig(flags, workflowLoop) {
     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) {
@@ -355,9 +216,6 @@ export function buildLoopConfig(flags, workflowLoop) {
     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 {
@@ -370,35 +228,21 @@ export function buildLoopConfig(flags, workflowLoop) {
     }
     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
+            return 7;
         case 'signal':
-            return 130; // 128 + SIGINT(2)
+            return 130;
         case 'stalled':
         case 'error':
         default:
             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'),
@@ -408,9 +252,6 @@ export async function runWorkflowForEach(spec, opts) {
         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,
@@ -422,7 +263,6 @@ export async function runWorkflowForEach(spec, opts) {
     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 });
@@ -435,14 +275,12 @@ export async function runWorkflowForEach(spec, opts) {
         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();
@@ -451,8 +289,6 @@ export async function runWorkflowForEach(spec, opts) {
         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) => {
@@ -460,8 +296,6 @@ export async function runWorkflowForEach(spec, opts) {
             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]));
@@ -480,19 +314,6 @@ export async function runWorkflowForEach(spec, opts) {
     process.stderr.write(chalk.yellow(`[for_each] stopped by ${result.stoppedBy} after ${result.waves} waves. Team: ${team}\n`));
     return 1;
 }
-/**
- * The run's working directory from `--cwd` / `--project`. `--project <slug>` owns
- * the directory and is mutually exclusive with `--cwd`/`--remote-cwd`; both the
- * main dispatch and the `--terminal` handoff need the same answer, so the rule
- * and its error live here once instead of in two places that can drift.
- *
- * A project that binds several directories also contributes the ones it is not
- * landing in as `--add-dir` grants, so an agent on a multi-repo project can
- * actually reach the sibling checkouts. Claude / Cursor / Kimi take the native
- * flag; Codex folds them into workspace_roots; Grok widens its sandbox profile
- * (and always injects a rules note). Other harnesses have no multi-root surface
- * and ignore the grants (cwd only).
- */
 export async function resolveRunCwd(options, opts) {
     if (!options.project) {
         if (!options.cwd || opts.forRemote)
@@ -509,8 +330,6 @@ export async function resolveRunCwd(options, opts) {
         const { cwd, extraDirs } = await resolveProjectDirs(options.project, {
             forRemote: opts.forRemote,
         });
-        // Explicit --add-dir values keep their position; a directory the project
-        // already contributes is not passed twice.
         if (extraDirs.length > 0) {
             const seen = new Set(options.addDir ?? []);
             options.addDir = [...(options.addDir ?? []), ...extraDirs.filter((d) => !seen.has(d))];
@@ -522,15 +341,6 @@ export async function resolveRunCwd(options, opts) {
         process.exit(1);
     }
 }
-/**
- * `--terminal`: hand this run to a real terminal tab and exit.
- *
- * The terminal is detected from the user's live sessions, so a run started from
- * a surface that cannot host a TUI (the menu bar's "New Session", a script) lands
- * in the terminal they actually work in instead of a hardcoded Terminal.app.
- * Exits non-zero when no terminal could be opened — the caller must not believe
- * a session started when none did.
- */
 async function handleTerminalHandoff(agentSpec, options, prompt) {
     const { parseTerminalFlag, openRunInTerminal, toHostSamples, currentContext } = await import('../lib/terminal/index.js');
     const parsed = parseTerminalFlag(options.terminal);
@@ -538,14 +348,6 @@ async function handleTerminalHandoff(agentSpec, options, prompt) {
         console.error(chalk.red(parsed.error));
         process.exit(1);
     }
-    // Reject an unrunnable target HERE, where the person can read it. The tab would
-    // otherwise open, print the same error, and close — the failure lands in a
-    // window that is gone before it can be read, which reads as "nothing happened".
-    //
-    // `agents run <thing>` takes an agent id, a PROFILE, or a WORKFLOW (see the
-    // isValidAgent / profileExists / resolveWorkflowRef chain below), so this must
-    // accept all three. Gating on the agent table alone rejected every profile —
-    // the whole Kimi/DeepSeek/Qwen/GLM path — for `--terminal` runs only.
     const rawTarget = parseRunPickerMarkers(agentSpec).normalizedAgentSpec.split('#')[0].split('@')[0];
     const knownAgent = resolveAgentName(rawTarget);
     const [{ profileExists }, { resolveWorkflowRef }] = await Promise.all([
@@ -564,30 +366,16 @@ async function handleTerminalHandoff(agentSpec, options, prompt) {
             process.exit(1);
         }
     }
-    // --device and its aliases (--on/--computer) all mean "dispatch this
-    // run to another machine over SSH", which is incompatible with opening a
-    // terminal tab on THIS machine — so reject the whole alias family, not just
-    // the canonical flag. The rule and its wording live once, in the --device
-    // forwarding table, so the classification a reviewer reads and the error a
-    // user sees can't drift.
     if (hostTargetGiven(options).length) {
         const { RUN_OPTION_REJECT_MESSAGES } = await import('../lib/hosts/remote-cmd.js');
         console.error(chalk.red(RUN_OPTION_REJECT_MESSAGES.terminal));
         process.exit(1);
     }
-    // Machine-readable output would land in the tab, where the caller that asked
-    // for it can never read it. Same class of failure as --device: refuse, don't
-    // hand back a stream that goes nowhere.
     const streamFlag = options.json ? '--json' : options.emitSessionId ? '--emit-session-id' : undefined;
     if (streamFlag) {
         console.error(chalk.red(`${streamFlag} streams to stdout, but --terminal moves the run into a tab where you cannot read it. Drop one.`));
         process.exit(1);
     }
-    // `--project` owns the working directory, but the main action resolves it far
-    // below this handoff — so without this the tab would open in THIS process's
-    // cwd (launchd's `/` for a menu-bar click) while the run inside it moved to
-    // the project. `forRemote: false` because --terminal is always local (--device
-    // is rejected above).
     const cwd = await resolveRunCwd(options, { forRemote: false });
     const { getActiveSessions } = await import('../lib/session/active.js');
     let sessions = [];
@@ -595,8 +383,6 @@ async function handleTerminalHandoff(agentSpec, options, prompt) {
         sessions = await toHostSamples(await getActiveSessions());
     }
     catch {
-        // Detection is best-effort — an unreadable session index must not block the
-        // launch; resolution falls through to the available-backend floor.
     }
     const result = await openRunInTerminal({
         argv: process.argv.slice(2),
@@ -615,7 +401,6 @@ async function handleTerminalHandoff(agentSpec, options, prompt) {
         console.log(chalk.gray(`Opened the ${what} in ${result.description}.`));
     }
 }
-/** Register the `agents run <agent> [prompt]` command. */
 export function registerRunCommand(program) {
     const runCmd = program
         .command('run [agent] [prompt]')
@@ -684,19 +469,9 @@ export function registerRunCommand(program) {
         .option('--repo <owner/repo>', 'With --cloud: GitHub repository. Repeatable for multi-repo dispatch (Rush Cloud only).', (val, prev) => [...prev, val], [])
         .option('--branch <name>', 'With --cloud: target git branch.')
         .option('--cloud-env <id>', 'With --cloud: Codex Cloud environment ID (run\'s --env is the KEY=VAL passthrough, so the cloud env id gets its own flag).');
-    // `--on` and `--computer` are hidden aliases of `--device` — same behavior.
     runCmd.addOption(new Option('--on <name>', 'Alias of --device.').hideHelp());
     runCmd.addOption(new Option('--computer <name>', 'Alias of --device.').hideHelp());
-    // Internal: the `--device` dispatch forwards this so the REMOTE run prints its
-    // resolved session id as a one-line stdout sentinel (hosts/session-marker.ts),
-    // letting the launcher relate the remote-created session back to itself for
-    // every agent — not just Claude, whose id it forces up front.
     runCmd.addOption(new Option('--emit-session-id', 'internal: print the resolved session id for a --device launcher to capture').hideHelp());
-    // Required for the documented `agents run <agent> [prompt] -- <native flags>`
-    // passthrough: commander >=13 rejects excess operands by default, so any
-    // post-`--` token died with "too many arguments" before the action ran. The
-    // action re-derives the `--` boundary from rawArgs and still errors on excess
-    // operands that are NOT behind `--`.
     runCmd.allowExcessArguments(true);
     setHelpSections(runCmd, {
         examples: `
@@ -841,12 +616,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
     });
     runCmd.action(async (agentSpec, prompt, options, command) => {
         bootMark('run-action:enter');
-        // Capture everything after -- as passthrough args forwarded verbatim to the
-        // underlying CLI. Commander strips the literal `--` and folds what follows
-        // into the positional operands (so `agents run codex -- --yolo` would parse
-        // `--yolo` as the PROMPT) — recover the boundary from rawArgs instead of
-        // operand counts. Excess operands not behind `--` are still an error (an
-        // unquoted prompt must not silently become agent flags).
         const rawArgs = process.argv;
         const separatorIdx = rawArgs.indexOf('--');
         const passthroughArgs = separatorIdx === -1 ? [] : rawArgs.slice(separatorIdx + 1);
@@ -856,12 +625,8 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             process.exit(1);
         }
         if (prompt !== undefined && operandsBeforeSeparator < 2) {
-            // The token commander assigned to [prompt] came from behind `--` — it is
-            // a native flag, not a prompt. Run interactively.
             prompt = undefined;
         }
-        // Broadcast matrix (formerly `agents bench`): list/results/run cells, then exit.
-        // --broadcast is local-only fan-out — it is mutually exclusive with --host/--device.
         if (options.broadcast || options.listTasks || options.results !== undefined) {
             const whereIsRemote = typeof options.where === 'string' && options.where.trim().toLowerCase() !== 'local';
             if (hostTargetGiven(options).length > 0 || whereIsRemote) {
@@ -891,9 +656,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             console.error(chalk.red("Missing required argument 'agent'. Example: agents run claude \"hello\"."));
             process.exit(1);
         }
-        // --cloud: vendor cloud placement. Validate BEFORE the terminal handoff
-        // and every local dispatch path — flags like --terminal/--loop/--resume
-        // belong to the local runner and must error, never ride along silently.
         if (options.cloud || (typeof options.where === 'string' && /^cloud(:|$)/i.test(options.where.trim()))) {
             const { runCloudConflicts } = await import('./run-cloud.js');
             const conflicts = runCloudConflicts(options);
@@ -902,25 +664,14 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 process.exit(1);
             }
         }
-        // --terminal: this process can't host the TUI (a menu-bar click, a script),
-        // so hand the run to a real terminal and exit. Resolved from the user's own
-        // live sessions, so it opens where they already work. Done before every
-        // other dispatch path because the tab re-runs this same argv without the
-        // flag — arming --notify or picking a version here would happen twice.
         if (options.terminal) {
             await handleTerminalHandoff(agentSpec, options, prompt);
             return;
         }
-        // Placement: --where expands into --device / --lease / --cloud before any
-        // dispatch. One door for "where does the body run?" — old flags remain
-        // aliases. See lib/placement.ts and docs/concepts.md#placement.
         {
             const { placementFromRunFlags, expandPlacementToRunFlags, PlacementError } = await import('../lib/placement.js');
             try {
                 const placement = placementFromRunFlags(options);
-                // An explicit local placement (--local, --where local) must outlive
-                // this block: expansion yields no host flag, and the bare-interactive
-                // default below reads an empty host set as "decide for me".
                 if (placement.kind === 'local' && placement.source !== 'default')
                     options.local = true;
                 if (options.where) {
@@ -937,8 +688,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                         options.cloud = expanded.cloud;
                     if (expanded.provider !== undefined)
                         options.provider = expanded.provider;
-                    // Clear the where flag so remote re-entry (host dispatch) does not
-                    // re-expand and conflict with the concrete host we just set.
                     options.where = undefined;
                 }
             }
@@ -950,17 +699,11 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 throw err;
             }
         }
-        // --device naming this machine (short id, MagicDNS name, loopback, or the
-        // `interactive` sentinel pinned here) is a local run, not a self-SSH: the
-        // hop probes its own login shell and times out under load. Pinned here,
-        // ahead of every placement gate, so the bare-interactive default sees an
-        // explicit local choice rather than an empty host set.
         {
             const { isSelfHost } = await import('../lib/devices/self-host.js');
             const { isDeviceInteractive, resolveInteractiveDevice } = await import('../lib/devices/interactive-host.js');
             pinLocalWhenTargetIsSelf(options, (name) => isSelfHost(isDeviceInteractive(name) ? resolveInteractiveDevice() ?? name : name));
         }
-        // Cloud refinement flags without the placement are a typo, not a no-op.
         if (!options.cloud) {
             const { cloudFlagsWithoutCloud } = await import('./run-cloud.js');
             const stray = cloudFlagsWithoutCloud(options);
@@ -969,17 +712,11 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 process.exit(1);
             }
         }
-        // --cloud: dispatch through the cloud provider registry and return — the
-        // run never touches the local/host/lease paths below.
         if (options.cloud) {
             const { handleRunCloud } = await import('./run-cloud.js');
             await handleRunCloud(agentSpec, prompt, options, command);
             return;
         }
-        // --notify: post a desktop notification when this run finishes. Armed on
-        // process exit so it covers EVERY dispatch path below (local, --device,
-        // --lease, the error path) instead of one branch. Only for headless runs
-        // — an interactive run ends in front of the person who started it.
         if (options.notify && prompt !== undefined) {
             const { armRunFinishNotification } = await import('../lib/run-notify.js');
             armRunFinishNotification({
@@ -990,11 +727,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 host: options.host,
             });
         }
-        // Trailing picker markers request an interactive choice: `#` picks the
-        // account (and the version it signs in with), `@` picks the device, and
-        // `#@`/`@#` ask both. Strip only those terminal markers; concrete
-        // agent@version pins and `#label` account pins retain their meaning in
-        // every dispatch path below.
         const pickerMarkers = parseRunPickerMarkers(agentSpec);
         const accountPickerRequested = pickerMarkers.accountPicker;
         const devicePickerRequested = pickerMarkers.devicePicker;
@@ -1005,10 +737,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 'Use agents run <agent># to pick an account, <agent>@ to pick a device, <agent>#@ for both.'));
             process.exit(1);
         }
-        // Peel `#name` off before --device dispatch so the selector rides the hop
-        // unchanged and the peer resolves ITS slot (PHNX-3940 T5). The later local
-        // parse is idempotent when the values match. A bare trailing `#` was the
-        // picker marker above, so it can never land here as an empty label.
         {
             const labelParts = normalizedAgentSpec.split('#');
             if (labelParts.length > 2 || labelParts[1] === '') {
@@ -1023,8 +751,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             if (specAccountLabel)
                 options.account = specAccountLabel;
         }
-        // Bare resume is a session selection request, before fresh-run defaults or placement.
-        // Concrete IDs re-enter the executor below, so this cannot recurse.
         if (options.resume === true || options.resume === '') {
             if (options.sessionId || options.loop || options.fallback || options.resumeCheckpoint || options.lease) {
                 throw new Error('--resume cannot be combined with --session-id, --loop, --fallback, --resume-checkpoint, or --lease.');
@@ -1046,7 +772,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             });
             return;
         }
-        // Hard-deprecated harnesses cannot be run — point the user at the successor.
         const runBaseAgentName = normalizedAgentSpec.split('#')[0].split('@')[0];
         const runBaseAgentId = resolveAgentName(runBaseAgentName);
         const { profileExists: runProfileExists } = await import('../lib/profiles.js');
@@ -1054,9 +779,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             console.error(chalk.red(hardDeprecationError(runBaseAgentId)));
             process.exit(1);
         }
-        // Picker conflict checks run BEFORE --resume/--device auto may place the
-        // run implicitly, so an implied placement never surfaces as a fake
-        // "cannot be combined with --device" when the user only typed a marker.
         if (accountPickerRequested) {
             const conflicts = runAccountPickerConflicts(options);
             if (conflicts.length > 0) {
@@ -1073,8 +795,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 process.exit(1);
             }
         }
-        // `agents run auto`: the reserved harness keyword — full-auto dispatch
-        // (host affinity → cross-harness balance → account balance, RUSH-2132).
         if (normalizedAgentSpec.split('#')[0].split('@')[0] === RUN_AUTO_KEYWORD && normalizedAgentSpec !== RUN_AUTO_KEYWORD) {
             console.error(chalk.red(`agents run auto picks the harness itself — a @version pin does not apply. ` +
                 `Pin a concrete harness instead: agents run <harness>@<version>.`));
@@ -1083,10 +803,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
         let autoHarnessRequested = normalizedAgentSpec === RUN_AUTO_KEYWORD;
         let resolvedResumeSource;
         let resolvedRecoveryTarget;
-        // Concrete resume ids resolve BEFORE placement. Full UUIDs take the local
-        // SQLite fast path; only a local miss fans out to the fleet. This lets a
-        // command entered on zion discover that the owning version-home is on a
-        // worker, while a command entered on that worker never pays for SSH.
         if (typeof options.resume === 'string' && options.resume.trim()) {
             const selector = options.resume.trim();
             const injectedSource = (() => {
@@ -1103,10 +819,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 ? { kind: 'resolved', session: injectedSource }
                 : await (await import('./sessions.js')).resolveSessionMetadataValue(selector, { agent: runBaseAgentId ?? undefined });
             if (outcome.kind === 'partial') {
-                // RUSH-2492: an unreachable peer is a warning, not a hard failure. The
-                // resolver already resolves an id found on the reachable fleet (SES-9a),
-                // so reaching here means the session was not found on any device we
-                // COULD reach — it may live on an unreachable peer we could not check.
                 const offline = outcome.failedPeers;
                 console.error(chalk.yellow(`Warning: ${offline.length} device(s) unreachable, not checked: ${offline.join(', ')}`));
                 console.error(chalk.red(`No session matching "${selector}" on any reachable device (${offline.length} unreachable, not checked).`));
@@ -1128,9 +840,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                     `Use: agents sessions resume ${resolvedResumeSource.id}`));
                 process.exit(1);
             }
-            // Omitted --mode inherits the effective source mode. Commander keeps
-            // the normal new-run default as a real value, so consult its provenance
-            // rather than mistaking the default for an explicit override.
             if (command.getOptionValueSource('mode') === 'default') {
                 if (resolvedResumeSource.mode) {
                     options.mode = resolvedResumeSource.mode;
@@ -1152,10 +861,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                     `the requested device was ${hostTargetGiven(options).join(', ') || 'this machine'}.`));
                 process.exit(1);
             }
-            // Recovery is resolved on the device that owns the transcript. A remote
-            // dispatch is pinned to the source HARNESS (not `run auto`'s cross-harness
-            // picker); the peer repeats this block with the injected SessionMeta and
-            // chooses its own healthy version. Locally, resolve it now.
             const sourceAgent = resolvedResumeSource.agent;
             if (!sourcePeer) {
                 try {
@@ -1177,8 +882,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             }
         }
         if (autoHarnessRequested) {
-            // `auto` is reserved. If a future harness registers that id, the
-            // keyword collides — fail loud rather than silently shadow the harness.
             if (RUN_AUTO_KEYWORD in AGENTS) {
                 console.error(chalk.red(`'${RUN_AUTO_KEYWORD}' is now a registered harness and collides with the reserved 'run auto' keyword. ` +
                     `Run the harness by name instead.`));
@@ -1192,21 +895,9 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 console.error(chalk.red(`agents run auto picks the harness and its placement itself — the trailing-@ device picker needs a concrete harness (agents run <harness>@).`));
                 process.exit(1);
             }
-            // Host layer: with no explicit --device, default to the
-            // affinity pick. Skipped on a device-dispatched run — its dispatcher
-            // already resolved this layer (see runAutoDefaultsToAffinity).
             if (!resolvedResumeSource && runAutoDefaultsToAffinity(options))
                 options.device = 'auto';
         }
-        // The picker menus run HERE — after every conflict check, before
-        // placement resolves — so the picked account labels the device rows and
-        // the picked device is concrete for every host branch below.
-        //   `#@`/`@#`: account first, against THIS machine's slots; the picked
-        //     account becomes options.account and the device menu shows its
-        //     ✓/– per-device mark. A remote device pick dispatches with
-        //     `<agent>#<label>` so the peer resolves its own slot.
-        //   `@`: just the device menu; picking this machine is a plain local run.
-        // Either menu cancelled (Esc/Ctrl-C) launches nothing and exits 0.
         let upFrontAccountPick = null;
         if (accountPickerRequested && devicePickerRequested) {
             const baseName = normalizedAgentSpec.split('#')[0].split('@')[0];
@@ -1227,7 +918,7 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             const { pickRunAccountCandidate } = await import('./run-account-picker.js');
             const selected = await pickRunAccountCandidate(baseAgentId);
             if (!selected)
-                return; // Esc/Ctrl-C: launch nothing.
+                return;
             if (selected.nativeAccount)
                 options.account = selected.nativeAccount;
             upFrontAccountPick = selected;
@@ -1237,8 +928,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             }
         }
         if (devicePickerRequested) {
-            // --resume above may have pinned the host implicitly (recovery to the
-            // source peer); a device menu against it would be a silent no-op.
             const impliedHost = hostTargetGiven(options);
             if (impliedHost.length > 0) {
                 console.error(chalk.red(`Device selection with ${agentSpec} cannot be combined with the placement --resume already chose (${impliedHost.join(', ')}). ` +
@@ -1252,39 +941,26 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 accountLabel: options.account,
             });
             if (pickedDevice === null)
-                return; // Esc/Ctrl-C: launch nothing.
+                return;
             const { isSelfHost } = await import('../lib/devices/self-host.js');
-            // Picking this machine is a plain local run — leave options.device unset.
             if (!isSelfHost(pickedDevice))
                 options.device = pickedDevice;
         }
-        // Default placement (PHNX-4083): a bare human-facing `agents run
-        // <harness>` (no prompt, real TTY, no placement flags, not a dispatched
-        // hop) places itself like `--device auto` — a marker left off is decided
-        // for you. Headless runs (a prompt, --json, teams/routines/hooks) keep
-        // running in place, unchanged.
         const defaultPlacement = bareInteractiveRunDefaultsToDeviceAuto(options, { prompt, devicePickerRequested }, { tty: isInteractiveTerminal(), json: options.json });
         if (defaultPlacement)
             options.device = 'auto';
-        // --device auto: live fleet pick.
-        // Harness is always the agent the user typed — never auto-picked.
-        // Placement failure propagates; an automatic request never becomes local.
         {
             const { applyDeviceAutoToOptions } = await import('../lib/smart-launch.js');
             let result;
             try {
                 result = await applyDeviceAutoToOptions(options, {
                     accountPickerRequested,
-                    // `run auto` selects its harness after placement, so do not filter
-                    // candidates against an arbitrary proxy harness at this stage.
                     agent: normalizedAgentSpec.split('#')[0].split('@')[0] === RUN_AUTO_KEYWORD
                         ? undefined
                         : (resolveAgentName(normalizedAgentSpec.split('#')[0].split('@')[0]) ?? undefined),
                 });
             }
             catch (err) {
-                // Placement the DEFAULT chose must fail loud AND name the local
-                // escape hatch — never silently fall back to a local launch.
                 if (!defaultPlacement)
                     throw err;
                 console.error(chalk.red(err.message));
@@ -1298,9 +974,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                     ` · ${acctNote}\n`));
             }
         }
-        // --lease: invent a disposable cloud box for this run (via crabbox), run
-        // the agent there, then tear it down. --box: reuse a named warm crabbox
-        // box, run the same bootstrap there, and leave the box running.
         if (options.lease || options.box) {
             if (prompt === undefined) {
                 console.error(chalk.red(`A prompt is required for crabbox runs: agents run <agent> "<task>" ${options.box ? '--box <slug>' : '--lease'}`));
@@ -1319,17 +992,12 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 process.exit(1);
             }
             const backend = typeof options.lease === 'string' ? options.lease : undefined;
-            // crabbox syncs this directory to the box via `git ls-files`; outside a
-            // git repo that fails with "build sync file list: exit status 128" — but
-            // only AFTER the box is provisioned and billed. Fail fast here instead.
             const leaseCwd = options.cwd ?? process.cwd();
             if (!isInsideGitWorkTree(leaseCwd)) {
                 console.error(chalk.red(`${options.box ? '--box' : '--lease'} syncs the working directory to the box, but ${leaseCwd} is not a git repository.`));
                 console.error(chalk.yellow(`Run from inside a git repo, or initialize one: (cd ${leaseCwd} && git init)`));
                 process.exit(1);
             }
-            // First-run: no provider credential resolves (no env var, no config, no
-            // detectable bundle) → guide the user through one-time setup, then continue.
             const { resolveLeaseBundle } = await import('../lib/crabbox/cli.js');
             if (options.lease && !resolveLeaseBundle()) {
                 const { runLeaseSetup } = await import('./lease.js');
@@ -1339,19 +1007,9 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                     process.exit(1);
                 }
             }
-            // ── F3 reuse (RUSH-1922) + F5 net-mode (RUSH-1924) ───────────────────
-            // Resolve which box this run targets and how it is networked BEFORE any
-            // provisioning. `--box` is an explicit reuse; otherwise, on an
-            // interactive tty, offer the warm boxes as a reuse picker. Headless runs
-            // never block: leaseAndRun itself is reuse-first against the profile
-            // pool (a ready pool box is reused; none ready → warm a fresh one).
-            // `--fresh` opts out of every reuse path.
             const leaseSecretsBundle = process.env.AGENTS_LEASE_SECRETS_BUNDLE;
             const nowSecs = Math.floor(Date.now() / 1000);
             let reuseSlug = options.box;
-            // Lease runs share one default warm pool across repositories. The generic
-            // `.crabbox.yaml profile:` remains available to repo sandbox/CI scripts;
-            // `leaseProfile:` is the explicit opt-in for a dedicated lease hot box.
             const repoRoot = gitToplevel(leaseCwd);
             const { readCrabboxLeaseProfile } = await import('../lib/crabbox/config.js');
             const poolProfile = repoRoot ? readCrabboxLeaseProfile(repoRoot) : 'default';
@@ -1366,12 +1024,12 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                     });
                 }
                 catch {
-                    warm = []; // crabbox unavailable / no creds → the pool check in leaseAndRun decides
+                    warm = [];
                 }
                 const alwaysFresh = repoRoot ? isAlwaysFreshRepo(readAlwaysFreshRepos(), repoRoot) : false;
                 if (warm.length > 0 && !alwaysFresh) {
                     if (options.reuse) {
-                        reuseSlug = warm[0].slug; // scriptable: most-recently-touched warm box
+                        reuseSlug = warm[0].slug;
                     }
                     else if (isInteractiveTerminal() && options.json !== true) {
                         const { select } = await import('@inquirer/prompts');
@@ -1400,21 +1058,14 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                             console.error(chalk.yellow('Selection cancelled — provisioning a fresh box.'));
                         }
                     }
-                    // Headless with no --reuse falls through here → leaseAndRun's
-                    // profile-pool check decides (reuse a ready pool box, else warm fresh).
                 }
                 else if (options.reuse && warm.length > 0) {
-                    // --reuse still honors a warm box even when the picker is suppressed.
                     reuseSlug = warm[0].slug;
                 }
             }
-            // reuseContext: an existing box (picked, --box, or --reuse) defaults the
-            // network to the tailnet; a solo one-shot --lease stays public.
             const reuseContext = !!reuseSlug || !!options.reuse;
             let netMode = computeNetMode({ tailscale: options.tailscale, reuseContext });
             const copySetup = !options.bare;
-            // Tailscale requested but no auth key configured → downgrade to public
-            // with an actionable hint instead of hard-failing the run (F5).
             if (netMode === 'tailscale') {
                 const { pickTailscaleBundleFromList } = await import('../lib/crabbox/cli.js');
                 const { listBundles } = await import('../lib/secrets-client.js');
@@ -1443,10 +1094,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             let runtime = null;
             let credentialRuntimes = [];
             let dispatchProfile;
-            // `--lease` requires a prompt (guarded above), so it is headless by
-            // contract — never block on an interactive picker. Provision exactly the
-            // one runtime this run needs, inferred from the agent, not every
-            // signed-in CLI (which would ship unrelated tokens to a throwaway box).
             if (profileExists(agentName)) {
                 try {
                     const profile = readProfile(agentName);
@@ -1484,14 +1131,7 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 console.error(chalk.yellow(`Profile '${agentName}' needs ${runtime} credentials, but ${runtime} is not signed in locally. Sign in locally, then retry.`));
                 process.exit(1);
             }
-            // Refuse before account selection, OAuth reads, box lookup, or lease
-            // provisioning. A provider-backed profile has no credentialRuntimes and
-            // proceeds with its portable provider environment instead.
             assertNoNativeOAuthTransfer(credentialRuntimes, detected);
-            // Headless-by-contract: don't prompt, but print exactly what ships and
-            // where — copying an auth token to a cloud box is a credential transfer.
-            // The box is destroyed after the run, so the credential's lifetime is
-            // bounded by the run.
             const whatShips = dispatchProfile
                 ? `profile '${dispatchProfile.name}'`
                 : `${runtime} runtime setup`;
@@ -1509,13 +1149,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                         : 'the shared-pool box is kept after the run';
             console.error(chalk.gray(`${boxLifecycle} · shipping ${whatShips}; ${boxAfterRun}.`));
             const claudeCredentialsJson = null;
-            // Progress UI (F2, RUSH-1921). A self-throttled spinner (NOT ora — see
-            // progress.ts) covers provisioning; the box-side bootstrap then streams a
-            // structured step stream (sync → install → runtime → creds → …) via the
-            // router's `onStep`, and each step renders as a checklist line through the
-            // lib's `renderStepLine` (✔ <Step> — <detail> (<elapsed>)). The agent's own
-            // output prints verbatim after the box-side marker. Rule: only ONE spinner
-            // phase is active at a time, so it can never storm.
             const { createLeaseOutputRouter, createSpinner, renderStepLine } = await import('../lib/crabbox/progress.js');
             const spinner = createSpinner({ stream: process.stderr });
             let warmupTimer;
@@ -1525,10 +1158,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             } };
             const jsonMode = options.json === true;
             const stepsTty = Boolean(process.stderr.isTTY) && !jsonMode;
-            // The step currently in flight (its label spins on a TTY). It is persisted
-            // as a ✔ line when the NEXT step arrives (whose elapsedMs measures how long
-            // THIS step's block took) — or, for the last step, when agent output or
-            // teardown begins.
             let activeStep = null;
             const flushStep = (elapsedMs) => {
                 if (!activeStep)
@@ -1544,18 +1173,15 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             };
             const router = createLeaseOutputRouter({
                 now: () => Date.now(),
-                // Raw setup lines stay captured for a failure dump (router.setupLines());
-                // the structured step stream drives the visible checklist, so plain lines
-                // are not shown (they would fight the step spinner).
                 onSetupLine: () => { },
                 onStep: (step) => {
-                    flushStep(step.elapsedMs); // persist the previous step, timed by this one
+                    flushStep(step.elapsedMs);
                     activeStep = step;
                     if (stepsTty)
                         spinner.start(renderStepLine(step));
                 },
                 onAgentChunk: (chunk) => {
-                    flushStep(); // last setup step done (no following sentinel to time it)
+                    flushStep();
                     if (spinner.active)
                         spinner.stop();
                     process.stdout.write(chunk);
@@ -1595,7 +1221,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                         else if (phase.kind === 'ready') {
                             stopTimer();
                             const addr = boxAddress(phase.box);
-                            // Steps drive the spinner from here — no generic "Setting up box…".
                             spinner.stopAndPersist('✔', `Box ${phase.box.slug} ready${addr ? ` (${addr})` : ''} · ${Math.round(phase.elapsedMs / 1000)}s`);
                         }
                         else if (phase.kind === 'teardown') {
@@ -1610,9 +1235,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 stopTimer();
                 if (spinner.active)
                     spinner.stop();
-                // Safety net: if setup failed before the agent ever ran, the setup log
-                // was only shown as transient spinner text — surface it so the error is
-                // diagnosable.
                 if (exitCode !== 0 && !router.sawAgent()) {
                     const log = router.setupLines();
                     if (log.length)
@@ -1634,19 +1256,7 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 process.exit(1);
             }
         }
-        // --device/--on/--computer: offload this run onto a registered agent host
-        // over SSH instead of running locally. The three flags are aliases.
         const hostGiven = hostTargetGiven(options);
-        // Auto-sync this run's redacted trajectory when it exits, so the console is
-        // never stale and a session link/QR resolves the moment the run finishes
-        // (PHNX-3628). Armed HERE — after hostGiven is finalized — so every
-        // remote-placement signal is already reflected in options: --device/--on/
-        // --computer and --where device: (expanded to options.host above), AND the
-        // --resume-to-peer redirect that sets options.host during resume
-        // resolution. A run that will dispatch remotely (hostGiven non-empty, or
-        // --lease/--box) has its trajectory on that box and never arms a local
-        // sync; --cloud returned earlier. The module additionally gates on opt-in
-        // (signed in + already synced once) and is best-effort.
         if (prompt !== undefined &&
             hostGiven.length === 0 &&
             !options.lease &&
@@ -1654,8 +1264,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             const { armRunFinishTraceSync } = await import('../lib/run-trace-sync.js');
             armRunFinishTraceSync({ disabled: options.traceSync === false });
         }
-        // Home anchors belong to the executing host; preserve them until a remote
-        // invocation reaches its local execution path.
         options.cwd = await resolveRunCwd(options, { forRemote: hostGiven.length > 0 });
         if (hostGiven.length > 0) {
             if (new Set(hostGiven).size > 1) {
@@ -1663,18 +1271,11 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 process.exit(1);
             }
             const hostName = hostGiven[0];
-            // Note: a `run auto` dispatch needs no marker forwarded from here — the
-            // dispatch layer (hosts/dispatch.ts remoteRunShellPrelude) exports the
-            // chain-hop guard into the remote shell for BOTH interactive and
-            // headless paths, keyed off the agent name being `auto`.
             const { resolveHostRunTarget, resolveHostSessionId, dispatchPromptToHost, HostResolutionError } = await import('../lib/hosts/run-target.js');
             const { runInteractiveOnHost } = await import('../lib/hosts/dispatch.js');
             const { registerInteractiveHostSession } = await import('../lib/hosts/session-index.js');
             const { RUN_OPTION_REJECT_MESSAGES } = await import('../lib/hosts/remote-cmd.js');
             const { normalizeRunStrategy, RUN_STRATEGIES } = await import('../lib/accounting/rotate.js');
-            // The forwarding contract (RUN_OPTION_FORWARDING): options that cannot
-            // cross the SSH boundary fail loud BEFORE dispatch — never a silent
-            // drop. Value-aware: only reject what was actually passed.
             const hostRejects = [];
             if (options.secrets.length > 0)
                 hostRejects.push(RUN_OPTION_REJECT_MESSAGES.secrets);
@@ -1695,10 +1296,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 process.exit(1);
                 return;
             }
-            // Shared resolution (name → capability tag → error). A password-auth
-            // device throws DeviceOffloadUnsupportedError inside the helper and
-            // propagates untouched — it's printed cleanly by the top-level catch in
-            // index.ts (covers every resolveHost caller).
             let host;
             try {
                 host = await resolveHostRunTarget(hostName, { any: options.any });
@@ -1712,13 +1309,7 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             }
             try {
                 const [runAgent, rawRunVersion] = normalizedAgentSpec.split('#')[0].split('@');
-                // Forward the explicit @version pin verbatim. Resolving aliases like
-                // @latest locally would check local installs, but the remote host may
-                // have versions the laptop does not. The remote agents CLI resolves
-                // aliases against its own installed versions.
                 const runVersion = rawRunVersion || undefined;
-                // Normalize the effective strategy exactly like the local path so we
-                // fail fast on invalid input and can forward --balanced/--strategy.
                 const explicitStrategy = options.strategy ? normalizeRunStrategy(options.strategy) : null;
                 if (options.strategy && !explicitStrategy) {
                     console.error(chalk.red(`Invalid strategy: ${options.strategy}. Use ${RUN_STRATEGIES.join(', ')}.`));
@@ -1729,73 +1320,34 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                     process.exit(1);
                 }
                 const runStrategy = options.balanced ? 'balanced' : explicitStrategy ?? undefined;
-                // Working directory on the host: an explicit --remote-cwd is used
-                // verbatim; --cwd/--project are made portable (a local-home absolute
-                // becomes `~/…` so the remote shell re-roots it at ITS home).
-                //
-                // With neither flag, mirror the LOCAL cwd's home-relative path onto
-                // the host (deriveMirroredCwd). Otherwise every host run starts in the
-                // remote `$HOME` — launch an agent from a repo and it opens with no
-                // project, and you `cd` by hand every time. The same checkout at the
-                // same home-relative path on both boxes is the normal fleet layout, so
-                // the mirror usually hits; when the host lacks that directory the run
-                // falls back to the remote home rather than failing.
                 const { toRemotePortable } = await import('../lib/project-root.js');
                 const { deriveMirroredCwd } = await import('../lib/hosts/dispatch.js');
                 const explicitHostCwd = options.remoteCwd ?? (options.cwd ? toRemotePortable(options.cwd) : undefined);
                 const hostCwd = explicitHostCwd ?? deriveMirroredCwd(process.cwd());
                 const mirrorHostCwd = explicitHostCwd === undefined;
                 const hostAddDirs = options.addDir.length > 0 ? options.addDir.map(toRemotePortable) : undefined;
-                // `--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;
                 let hostCopyCreds;
-                // Decide whether this host run is interactive. No prompt always means
-                // interactive (matching local resolveInteractive); --interactive forces
-                // interactive even when a prompt is provided; --headless forces headless
-                // and therefore requires a prompt.
                 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).'));
                     process.exit(1);
                 }
                 const interactiveHost = options.interactive === true || (prompt === undefined && options.headless !== true);
-                // When the account was already picked up front (`#@`), the dispatch
-                // forwards `#label` and the peer needs no interactive picker.
                 if (accountPickerRequested && !upFrontAccountPick && !interactiveHost) {
                     console.error(chalk.red(`Account selection with ${agentSpec} requires an interactive host run. ` +
                         `Use agents run ${runAgent}# --device ${host.name} --interactive.`));
                     process.exit(1);
                 }
                 if (interactiveHost) {
-                    // Interactive host run: forward the local TTY over SSH and let the
-                    // remote agent start its normal interactive UI (tmux on the host).
                     if (options.follow === false) {
                         console.error(chalk.red('--no-follow is not compatible with interactive host runs. Interactive runs are attached by definition.'));
                         process.exit(1);
                     }
-                    // Mirror the local path (lib/exec.ts): only Claude accepts a forced
-                    // `--session-id`. Adopt the caller's id when present; otherwise mint
-                    // one here. Registering that same id keeps the local index aligned
-                    // with the remote agent. On resume, don't mint a new one.
                     const hostSessionId = resolveHostSessionId(runAgent, resumeId, options.sessionId);
-                    // For every OTHER agent the remote coins its own id, which we can't
-                    // know up front. Forward a launch id we control as AGENT_LAUNCH_ID:
-                    // the remote `agents run` adopts it (exec.ts resolveLaunchId) and its
-                    // SessionStart hook records the real id under that exact key, so after
-                    // the stream we resolve the id by one ssh read of the remote hook
-                    // record — the same launch-id join used locally (RUSH-2034). Not
-                    // needed for Claude (id forced) or resume (id already known).
-                    // `run auto` ALWAYS joins: the remote picks the harness, so an
-                    // explicit --session-id is only adopted by a claude pick.
                     const correlationLaunchId = hostInteractiveNeedsCorrelationId(runAgent, hostSessionId, resumeId) ? randomUUID() : undefined;
                     const hostEnv = correlationLaunchId
                         ? [...options.env, `AGENT_LAUNCH_ID=${correlationLaunchId}`]
                         : options.env;
-                    // `run auto` never pre-registers: the explicit id is only real when
-                    // the remote pick lands on claude. The launch-id join below records
-                    // the id the remote ACTUALLY used, whatever the pick.
                     if (hostSessionId && runAgent !== RUN_AUTO_KEYWORD) {
                         registerInteractiveHostSession({
                             cwd: process.cwd(),
@@ -1852,13 +1404,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                         forceInteractive: options.interactive,
                         copyCreds: hostCopyCreds,
                     });
-                    // Resolve a non-Claude agent's REAL remote session id now the run has
-                    // booted (its hook has fired on the peer): one ssh read of the remote
-                    // hook record, keyed by the launch id we forwarded. Register it so the
-                    // run shows in `agents sessions` and can be reconnected/focused —
-                    // closing the non-Claude gap RUSH-2033 left. Best-effort: an
-                    // unreachable host or a not-yet-landed record leaves the run un-mapped
-                    // rather than mis-mapped.
                     let resolvedRemoteId;
                     if (correlationLaunchId) {
                         const { resolveRemoteSessionId } = await import('../lib/hosts/remote-session-id.js');
@@ -1867,7 +1412,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                             resolvedRemoteId = resolveRemoteSessionId(sshTargetFor(host), correlationLaunchId);
                         }
                         catch {
-                            /* ssh read is best-effort — keep the run un-mapped, never guess */
                         }
                         if (resolvedRemoteId) {
                             registerInteractiveHostSession({
@@ -1879,19 +1423,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                             });
                         }
                     }
-                    // A network drop kills the local ssh client (exit 255). What the
-                    // remote agent does next depends on the peer's tmux.enabled
-                    // (PHNX-3316): wrapped, it survives in its detached pane and the
-                    // reconnect rejoins it; bare (the default), the drop SIGHUPs it and
-                    // the reconnect resumes the session in place from disk. Either way,
-                    // with a known session id (Claude's forced id, a resumed run, or a
-                    // non-Claude id we just resolved from the remote hook record) we
-                    // reconnect automatically instead of exiting — the user never has
-                    // to notice the drop and `agents sessions focus` by hand.
-                    // `raw` runs opted out of all of this, so there is nothing to
-                    // reconnect to. For `run auto` prefer the join-resolved id (the
-                    // harness the remote ACTUALLY picked) over the explicit
-                    // --session-id only claude adopts.
                     const { pickReconnectTarget, reconnectInteractiveSession, afterInteractiveRemoteExit, SSH_CONN_FAILURE } = await import('../lib/hosts/reconnect.js');
                     const reconnectTarget = pickReconnectTarget({
                         agent: runAgent,
@@ -1900,9 +1431,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                         resumeId,
                         launchId: correlationLaunchId,
                     });
-                    // Raw is not tmux-wrapped, so it never auto-reconnects — but it
-                    // still prints the session id (EXEC-55). Bundling the notice
-                    // behind `!isRaw` left a dropped `--raw` tab as a bare shell.
                     const next = afterInteractiveRemoteExit({
                         target: reconnectTarget,
                         host: host.name,
@@ -1920,14 +1448,10 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                         process.stderr.write(next.notice);
                     process.exit(exitCode);
                 }
-                // Headless host run: launch detached, tail the remote log, and follow
-                // until the remote process exits.
                 if (prompt === undefined) {
                     console.error(chalk.red('A prompt is required for headless host runs: agents run <agent> "<task>" --device <name>'));
                     process.exit(1);
                 }
-                // Session-id mint, detached dispatch, and local session-index
-                // registration all live in the shared helper (lib/hosts/run-target.ts).
                 const { modeForRemoteDispatch } = await import('../lib/codex-policy.js');
                 const forwardedMode = modeForRemoteDispatch(options.mode, command.getOptionValueSource('mode'));
                 if (process.env.AGENTS_DISPATCH_DEBUG || options.verbose) {
@@ -1966,18 +1490,12 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                     copyCreds: hostCopyCreds,
                 });
                 if (options.follow === false) {
-                    // The handle the caller uses to check on the run: the name if given,
-                    // else the real host-task id (never the old literal `<id>`). Steer
-                    // to the compact `agents sessions` digest over the raw log first.
                     const handle = task.name ?? task.id;
                     console.log(chalk.green(`Dispatched to ${host.name}${task.name ? ` as "${task.name}"` : ''}.`) + '\n' +
                         chalk.gray(`  Status:  agents sessions ${handle}`) + chalk.gray('   (compact digest — use this)') + '\n' +
                         chalk.gray(`  Raw log: agents logs ${handle} -f`) + chalk.gray('   (heavy, only if needed)'));
                     process.exit(0);
                 }
-                // -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);
@@ -1987,11 +1505,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 process.exit(1);
             }
         }
-        // --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');
@@ -2014,10 +1527,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 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);
@@ -2063,9 +1572,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 sessionId: cp.sessionId,
             });
             process.stderr.write(chalk.gray(`[loop] stopped: ${result.stoppedBy} after ${result.iterations} iteration(s), ${result.tokens} tokens\n`));
-            // 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,
@@ -2074,8 +1580,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 cwd: resumeExec.cwd ?? process.cwd(),
                 exitCode: resumeExit,
             });
-            // A resumed loop is always headless; surface any commits it left unpushed
-            // and any open PR it left unattended (RUSH-2394).
             if (shouldWarnUnpushed(resumeExec.mode ?? 'auto', false)) {
                 const resumeCwd = resumeExec.cwd ?? process.cwd();
                 await warnUnpushedWork(resumeCwd);
@@ -2083,10 +1587,7 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             }
             process.exit(resumeExit);
         }
-        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode, implicitModeFor, headlessPlanStallCommand, nativeResume, resolveInteractive, inferredInteractiveWithoutTty }, { ALL_AGENT_IDS, ACCOUNT_INSPECTION_AGENT_IDS, agentLabel, supportsAccountInspection }, { profileExists, readProfile, resolveProfileForRun }, 
-        // Engine DATA ops resolve through the standalone `secrets` process client
-        // (PHNX-3989); the agents-owned `bundle@host` policy helpers stay in agents-cli.
-        { readAndResolveBundleEnv, describeBundle, remoteResolveEnv }, { assertRemoteBundleFlagsUnsupported, splitBundleRef, resolveSecretsContextForRun }, { resolveHostSshTarget }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, rotationFailoverChain, DEFAULT_ROTATION_FAILOVER_LIMIT, shouldArmRotationFailover, preflightFallbackHandoff, preflightHandoffEligible, RUN_STRATEGIES, collectHarnessCandidates, pickHarnessWeighted, classifyHarnessCandidates, formatHarnessPickBanner, formatNoHealthyHarnessError, formatNoHealthyAccountError, formatNoVerifiedUsageError, signInRecoverableCandidates }, { getGlobalDefault, getVersionHomePath, resolveVersion, resolveVersionAlias, ensureAgentRunnable }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef, resolveAllowedSubagents, pruneStaleWorkflowSubagents, ensureSubagentDispatchTool }, { resolveRunDefaults }, { getMcpServersByName, buildWorkflowMcpConfig }, { supports, capableAgents }, { shareRuntimeEnv },] = await Promise.all([
+        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode, implicitModeFor, headlessPlanStallCommand, nativeResume, resolveInteractive, inferredInteractiveWithoutTty }, { ALL_AGENT_IDS, ACCOUNT_INSPECTION_AGENT_IDS, agentLabel, supportsAccountInspection }, { profileExists, readProfile, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle, remoteResolveEnv }, { assertRemoteBundleFlagsUnsupported, splitBundleRef, resolveSecretsContextForRun }, { resolveHostSshTarget }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, rotationFailoverChain, DEFAULT_ROTATION_FAILOVER_LIMIT, shouldArmRotationFailover, preflightFallbackHandoff, preflightHandoffEligible, RUN_STRATEGIES, collectHarnessCandidates, pickHarnessWeighted, classifyHarnessCandidates, formatHarnessPickBanner, formatNoHealthyHarnessError, formatNoHealthyAccountError, formatNoVerifiedUsageError, signInRecoverableCandidates }, { getGlobalDefault, getVersionHomePath, resolveVersion, resolveVersionAlias, ensureAgentRunnable }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef, resolveAllowedSubagents, pruneStaleWorkflowSubagents, ensureSubagentDispatchTool }, { resolveRunDefaults }, { getMcpServersByName, buildWorkflowMcpConfig }, { supports, capableAgents }, { shareRuntimeEnv },] = await Promise.all([
             import('../lib/exec.js'),
             import('../lib/agents.js'),
             import('../lib/profiles.js'),
@@ -2104,8 +1605,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
         ]);
         bootMark('run-deps:imported');
         const isValidAgent = (agent) => ALL_AGENT_IDS.includes(agent);
-        // Parse agent@version#label. The label selects native auth without pinning
-        // the binary version; --account remains the equivalent flag form.
         const labelParts = normalizedAgentSpec.split('#');
         if (labelParts.length > 2 || labelParts[1] === '') {
             console.error(chalk.red(`Invalid account label in '${normalizedAgentSpec}'.`));
@@ -2137,25 +1636,11 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
         let profileName;
         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;
-        // True once this run copies ≥1 dispatchable subagent into the shared agents
-        // dir. Used below to keep the `Task` tool in a `tools:`-restricted workflow —
-        // an orchestrator handed subagents but denied `Task` cannot reach them and
-        // degenerates to a no-op ("I'll wait for the completion notification").
         let workflowHasSubagents = false;
         const cwd = options.cwd ?? process.cwd();
         if (accountPickerRequested && profileExists(rawAgent)) {
@@ -2169,15 +1654,7 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             }
         }
         if (autoHarnessRequested) {
-            // Harness layer (RUSH-2132): weighted pick across installed harnesses
-            // by best-account headroom. Zero healthy accounts anywhere fails loud
-            // — launching a default "because it's there" is how a rotate loop
-            // hammers an exhausted account.
             const byHarness = await collectHarnessCandidates();
-            // F1 (RUSH-2185 / EXEC-23a): a prompt-less run is interactive; only
-            // harnesses that can open a REPL with no argv are valid candidates.
-            // cursor-agent and similar exit immediately without a prompt, which
-            // leaves a silent [detached] pane and an orphan session.
             const interactive = prompt === undefined && options.headless !== true;
             const replCapable = interactive ? new Set(capableAgents('interactiveRepl')) : null;
             const candidateHarness = replCapable
@@ -2198,17 +1675,11 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             if (!options.quiet) {
                 process.stderr.write(chalk.gray(formatHarnessPickBanner(harnessPick) + '\n'));
             }
-            // --session-id keeps its claude-only semantics: honored when auto
-            // picks claude, ignored (loudly) otherwise.
             if (options.sessionId && agent !== 'claude' && !options.quiet) {
                 process.stderr.write(chalk.yellow(`[agents] --session-id ignored: auto picked ${agent} (only claude accepts a forced session id)\n`));
             }
         }
         else if (profileExists(rawAgent)) {
-            // A profile by this exact name exists. Profiles bind (host agent,
-            // version, env overrides, keychain-backed auth) so Chinese models
-            // (Kimi, DeepSeek, Qwen, GLM) can run inside Claude Code without a
-            // local proxy, including when the profile name matches a native id.
             try {
                 const resolved = resolveProfileForRun(rawAgent, options.model);
                 agent = resolved.agent;
@@ -2223,16 +1694,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 if (resolved.tierNote) {
                     process.stderr.write(chalk.gray(`[agents] ${resolved.tierNote}\n`));
                 }
-                // A tier token (cheap/default/best/ultra) already resolved against
-                // this PROFILE's own `models:` map above, when the profile opts in.
-                // Replace the raw --model value here so the tier never reaches the
-                // native, HOST-catalog tier block below. When the profile has no
-                // `models:` opt-in at all, resolvedModel stays undefined and
-                // options.model is left as the raw tier token on purpose — the
-                // "cost tiers don't apply to custom harness ..." discard guard further
-                // down this function is the canonical fallback for that case, and
-                // this block must not race it with a second, differently-worded
-                // message.
                 if (resolved.resolvedModel !== undefined) {
                     options.model = resolved.resolvedModel;
                 }
@@ -2246,11 +1707,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             agent = rawAgent;
         }
         else if (resolveWorkflowRef(rawAgent, cwd)) {
-            // Workflow: explicit directory, project .agents/workflows/<name>, user, system, or extra repo.
-            // Resolution follows resource precedence: direct path, then project > user > system > extras.
-            // Structure:
-            //   WORKFLOW.md        ← orchestrator instructions fed to claude as system prompt
-            //   subagents/*.md     ← flat .md files copied to ~/.claude/agents/ for Agent tool discovery
             const workflowDir = resolveWorkflowRef(rawAgent, cwd);
             agent = 'claude';
             const workflowFrontmatter = parseWorkflowFrontmatter(workflowDir);
@@ -2262,29 +1718,14 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             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. 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.)
+            // allowedAgents copies only named definitions; an explicit empty list means none, and pruning touches only managed copies.
             const subagentsDir = path.join(workflowDir, 'subagents');
             const allowedAgents = workflowFrontmatter?.allowedAgents;
             if (fs.existsSync(subagentsDir)) {
                 fs.mkdirSync(claudeAgentsDir, { recursive: true });
-                // 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);
-                // 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`));
@@ -2305,15 +1746,12 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 if (copied > 0)
                     workflowHasSubagents = true;
                 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.
             const workflowMd = path.join(workflowDir, 'WORKFLOW.md');
             const orchestratorBody = fs.existsSync(workflowMd)
                 ? fs.readFileSync(workflowMd, 'utf-8').replace(/^---[\s\S]*?---\n/, '').trim()
@@ -2321,7 +1759,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             if (orchestratorBody && prompt !== undefined) {
                 prompt = `${orchestratorBody}\n\n---\n\n${prompt}`;
             }
-            // Sync workflow-scoped skills into the version home's skills dir.
             const workflowSkillsDir = path.join(workflowDir, 'skills');
             if (fs.existsSync(workflowSkillsDir)) {
                 const skillsTarget = path.join(claudeAgentsDir, '..', 'skills');
@@ -2332,7 +1769,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                     fs.cpSync(path.join(workflowSkillsDir, entry.name), path.join(skillsTarget, entry.name), { recursive: true });
                 }
             }
-            // Sync workflow-scoped plugins into the version home.
             const workflowPluginsDir = path.join(workflowDir, 'plugins');
             if (fs.existsSync(workflowPluginsDir)) {
                 for (const entry of fs.readdirSync(workflowPluginsDir, { withFileTypes: true })) {
@@ -2345,10 +1781,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                     syncPluginToVersion(buildDiscoveredPlugin(pluginRoot, manifest), 'claude', versionHome);
                 }
             }
-            // Auto-inject secrets bundles declared in the workflow's frontmatter `secrets:` field.
-            // Union with any --secrets flags the user passed; dedupe. Skip when --no-auto-secrets is set.
-            // (Commander stores the negated flag as `autoSecrets: false` — the old
-            // `noAutoSecrets` read was never populated, making the flag a no-op.)
             if (options.autoSecrets !== false) {
                 const declared = workflowFrontmatter?.secrets ?? [];
                 if (declared.length > 0) {
@@ -2366,14 +1798,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                     }
                 }
             }
-            // 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;
@@ -2386,15 +1810,13 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             }
             else if (hasScoping) {
                 if (tools && tools.length > 0) {
-                    // An orchestrator with dispatchable subagents MUST retain the `Task`
-                    // tool, or it can't reach the subagents this run just installed for it
-                    // — the run silently no-ops ("I'll wait for the completion notification").
                     workflowToolsRestrict = ensureSubagentDispatchTool(tools, workflowHasSubagents);
                     process.stderr.write(chalk.gray(`[workflow] restricting available tools to: ${workflowToolsRestrict.join(', ')} (Write/Bash/Edit unavailable unless listed)\n`));
                     if (workflowToolsRestrict.length !== tools.length) {
                         process.stderr.write(chalk.gray(`[workflow] kept Task tool: workflow ships subagents to dispatch\n`));
                     }
                 }
+                // Named MCP scope always writes strict config, even when no name resolves, so ambient servers cannot leak into the workflow.
                 if (mcpServerNames && mcpServerNames.length > 0) {
                     const servers = getMcpServersByName(mcpServerNames, { cwd });
                     const found = new Set(servers.map(s => s.name));
@@ -2402,16 +1824,9 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                     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`));
@@ -2421,17 +1836,12 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                     }
                 }
             }
-            // 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)
                 ? resolveAllowedSubagents(fs.readdirSync(subagentsDir).filter(f => f.endsWith('.md')), allowedAgents).allowedStems.length
                 : 0;
             process.stderr.write(chalk.gray(`Workflow '${rawAgent}' → claude (${subagentCount} subagents)\n`));
         }
         else {
-            // Smart pick: auto-correct a single typo (insertion/deletion/substitution/transposition)
-            // against the known agent ids before giving up. Example: `cladue` -> `claude`, `grk` -> `grok`.
             const { fuzzyMatch, FUZZY_PRESETS } = await import('../lib/fuzzy.js');
             const suggested = fuzzyMatch(rawAgent, ALL_AGENT_IDS, FUZZY_PRESETS.agents);
             if (suggested && isValidAgent(suggested)) {
@@ -2445,9 +1855,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 process.exit(1);
             }
         }
-        // `#@` already asked the account up front (before the device menu) — a
-        // remote device pick never reaches here, so apply the local pick's
-        // version/home and skip the on-the-spot menu.
         if (accountPickerRequested && !upFrontAccountPick) {
             if (!supportsAccountInspection(agent)) {
                 console.error(chalk.red(`${agentLabel(agent)} does not expose local account state, so agents-cli cannot safely select an account.`));
@@ -2496,8 +1903,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             accountEnv = { ...accountEnv, ...launchAccount.env };
         }
         else {
-            // Binding key: a custom harness keys on its own profile name; a native /
-            // global run keys on the exact `agent@version` (default when unpinned).
             const bindingTarget = fromProfile ? rawAgent : (version ? `${agent}@${version}` : `${agent}@${getGlobalDefault(agent) ?? ''}`);
             try {
                 spawnAccount = resolveSpawnAccount(options.account, agent, version, readMeta(), { useDefault: !fromProfile, provider: profileProvider, target: bindingTarget });
@@ -2506,15 +1911,12 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 console.error(chalk.red(err.message));
                 process.exit(1);
             }
-            // Downstream rotation gating asks only "was an account selected?".
             if (spawnAccount) {
                 if (options.cloud || options.provider || options.lease) {
                     console.error(chalk.red('--account selects a device-local credential and cannot be combined with cloud or lease placement.'));
                     process.exit(1);
                 }
                 if (spawnAccount.kind === 'native') {
-                    // `#name` / `--account` on a --device run is forwarded unchanged at
-                    // dispatch time; the peer resolves ITS slot. This block is local-only.
                     const remoteTarget = options.host || options.device;
                     if (!remoteTarget) {
                         const { adoptedConfigPointsAtHome, adoptedSymlinkMismatchError, durableSlotEnv, isSymlinkAdoptedHarness, resolveNativeSpawnHome, symlinkAdoptedAccountError, } = await import('../lib/exec-account-home.js');
@@ -2534,16 +1936,11 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                                 process.exit(1);
                             }
                             execHome = resolved.execHome;
-                            // A worker's durable api-key slot holds no file: the pushed key
-                            // rides the harness env var (CURSOR_API_KEY, …) on this launch.
                             const durable = durableSlotEnv(agent, spawnAccount, resolved, meta);
                             if (Object.keys(durable).length > 0)
                                 accountEnv = { ...accountEnv, ...durable };
                             if (resolved.source === 'legacy-home') {
                                 accountConfigVersion = resolved.label;
-                                // A leftover version-labeled home is both the spawn HOME and
-                                // the account's installation — the pre-T5 `resolveAccountVersion`
-                                // behavior. An explicit `@<label>` still controls the binary.
                                 if (!version && !fromProfile && resolved.label)
                                     version = resolved.label;
                             }
@@ -2552,7 +1949,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                             console.error(chalk.red(err.message));
                             process.exit(1);
                         }
-                        // Slot / provisioned: binary comes from the one managed install unless `@<label>` pins it.
                         if (!version && !fromProfile) {
                             const { ensureHarnessInstallation } = await import('../lib/installations/store.js');
                             const { installation } = await ensureHarnessInstallation(agent);
@@ -2568,7 +1964,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             }
         }
         const configuredAccount = launchAccount?.account?.name ?? spawnAccount?.name;
-        // The account and native context were resolved before launch defaults.
         let resumeNative = false;
         let resumeSessionId;
         let forceInteractive = false;
@@ -2600,10 +1995,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             if (resolvedRecoveryTarget.mode === 'native') {
                 resumeNative = true;
                 resumeSessionId = session.id;
-                // The centralized recovery decision proves the transcript belongs to
-                // this exact isolated home and resolves any harness-specific launch cwd.
-                // Claude's indexed `session.cwd` is the first user-turn cwd, which may
-                // differ from the earlier cwd that selected projects/<cwd-key>.
                 if (!options.cwd && resolvedRecoveryTarget.cwd)
                     options.cwd = resolvedRecoveryTarget.cwd;
                 if (!options.quiet)
@@ -2627,39 +2018,10 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
         }
         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;
-        /**
-         * The PRIMARY harness's configured run-default mode/effort, carried across a
-         * preflight alternate-harness handoff (PHNX-3999 F19).
-         *
-         * Run defaults are resolved after the harness is known, so without this a
-         * handoff would silently adopt the ALTERNATE's configured defaults — a
-         * primary configured `mode: plan` becoming the alternate's `mode: skip`
-         * escalates a read-only intent into an unattended writable run. The
-         * canonical mid-run cascade keeps the primary's resolved mode for the same
-         * reason (`runWithFallback` forwards `options.mode` and only re-derives the
-         * mode that was never configured at all). An IMPLICIT mode is deliberately
-         * not carried: it is the harness's own safe default, so the alternate's
-         * applies (identical to `modeWasImplicit ? implicitModeFor(agent)`).
-         */
         let handoffRunDefaults;
-        // Precomputed launchable-signed-in verdict for the ACTUAL launched
-        // candidate, fed to the pre-launch `run.launch` event so it need not
-        // re-probe. Sourced per resolution branch from the candidate that WON, not
-        // the original auto-pick: the interactive picker (RUSH-2334 / PHNX-2526)
-        // deliberately lets the user launch a LOGGED-OUT account, which is a
-        // different candidate than `rotationResult.picked` — reading the verdict off
-        // the auto-pick there would report `launchedLoggedOut:false` for a version
-        // that is actually logged out, the exact false-negative this event exists to
-        // prevent. Left undefined for pinned-default / explicit-pin so emitRunLaunch
-        // falls back to probing the version home itself.
         let launchSignedIn;
         let launchEmail;
-        // Set when the zero-healthy path already announced a deliberate
-        // launch-to-sign-in, so the login preflight below does not repeat it.
         let signInLaunch = false;
         if (options.strategy && !explicitStrategy) {
             console.error(chalk.red(`Invalid strategy: ${options.strategy}. Use ${RUN_STRATEGIES.join(', ')}.`));
@@ -2670,26 +2032,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             process.exit(1);
         }
         const strategy = options.balanced ? 'balanced' : explicitStrategy ?? configuredStrategy;
-        // Strategy applies to bare (unpinned) invocations. Explicit @version and
-        // profiles already name the target. A --fallback chain does NOT pin the
-        // primary: it only names where to cascade on a rate limit, so the bare
-        // primary still resolves through the strategy — otherwise every
-        // `agents run claude --fallback codex` run lands on the pinned default
-        // account and account rotation silently stops (the gh-monitor heal bug).
-        // `pinned` still resolves so a logged-out default can yield to a signed-in
-        // sibling on this device (PHNX-2685); an explicit @version pin is unchanged.
-        // Bounded handoff loop: each iteration resolves an account for `agent`, and
-        // the only `continue` is the preflight exhaustion handoff below, which
-        // consumes one entry of the `--fallback` spec before retrying as that
-        // alternate. The spec is finite, so this terminates (PHNX-3999 F19).
-        // A balanced pick or the no-fresh-usage picker returns a CANDIDATE. Since
-        // PHNX-3940 a native candidate is a registered account SLOT, not the
-        // version home the executable lives in, so the spawn must resolve that
-        // slot (home + durable env) through the canonical local launch resolver.
-        // Without this the run launched the version home and whichever login it
-        // held: on yosemite-m0 (2026-09-23) the picker chose trp and Claude
-        // started as a different account in its first-run wizard. A remote run
-        // re-resolves on the peer, which runs this same code locally.
         const applyPickedCandidate = async (candidate) => {
             if (!candidate.nativeAccount || options.host || options.device)
                 return;
@@ -2723,11 +2065,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 }
                 else {
                     try {
-                        // Account-centric candidate list: native version-home logins PLUS
-                        // provider accounts (setup-token / API-key) that can auth this agent,
-                        // so `--strategy balanced` spreads across ALL accounts, not just the
-                        // ones sitting in a version home (RUSH-3182). Run-path only — the
-                        // picker's other callers keep the native-only collector.
                         const { collectRunCandidatesForRun } = await import('../lib/accounting/account-pool-collect.js');
                         bootMark('resolve-version:start');
                         const routingModel = options.model ?? resolvedResumeSource?.model ?? workflowModel
@@ -2735,20 +2072,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                         const resolved = await resolveRunVersion(agent, strategy, cwd, collectRunCandidatesForRun, routingModel);
                         bootMark('resolve-version:done');
                         if (resolved.exhausted) {
-                            // Zero healthy accounts splits two ways, and conflating them is what
-                            // stranded a logged-out harness with no way in at all (RUSH-2334):
-                            //
-                            // - THROTTLED (rate_limited / out_of_credits) -> fail loud (RUSH-2132).
-                            //   The old behavior warned "found no usable version; falling back to
-                            //   defaults" and launched the pinned default anyway — the exact move
-                            //   that loops a rotate into an exhausted account. Only a window reset
-                            //   clears it. The message text is a contract the Factory watchdog
-                            //   tail-detects; do not reword it.
-                            // - NEEDS A SIGN-IN (signed_out / revoked) -> launching IS the fix,
-                            //   because the harness's own TUI is the login surface. So on a TTY we
-                            //   carry the user into that login instead of erroring. Exiting here
-                            //   made `agents run <agent>`, `agents run <agent>#`, and `agents use`
-                            //   all dead-end with no reachable way to authenticate.
                             const recoverable = signInRecoverableCandidates(resolved.exhausted);
                             const { signInLaunchDecision } = await import('./run-account-picker.js');
                             const decision = signInLaunchDecision({
@@ -2759,33 +2082,12 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                             if (decision === 'launch') {
                                 const { pickSignInLaunchVersion } = await import('./run-account-picker.js');
                                 const signInVersion = await pickSignInLaunchVersion(agent, recoverable, !!options.quiet);
-                                // A cancelled prompt launches nothing — same contract as the
-                                // trailing-# account picker above.
                                 if (!signInVersion)
                                     return;
                                 version = signInVersion;
-                                // We just told the user this account is logged out and why we're
-                                // launching it, so suppress the downstream login preflight — it
-                                // would print a second, near-identical "looks logged out" warning.
                                 signInLaunch = true;
                             }
                             else {
-                                // Every account of this harness is throttled. A configured
-                                // alternate exists for exactly this case, so hand off to it here
-                                // rather than exiting — `runWithFallback` would only reach it
-                                // after a run that can no longer start (PHNX-3999 F19). The
-                                // alternate becomes the primary and is dropped from the spec, so
-                                // the chain that remains never lists the agent now running.
-                                //
-                                // ONLY for a run shape `--fallback` is valid on. The handoff
-                                // consumes the entry it uses, and the canonical --fallback
-                                // validation runs later (it rejects interactive/--acp/--loop/
-                                // --resume-checkpoint chains and requires a prompt) — so
-                                // switching first on an ineligible shape would empty the spec,
-                                // leave that guard nothing to reject, and start the alternate
-                                // harness on a run the CLI refuses today. An ineligible shape
-                                // never switches, so the spec survives and still fails there
-                                // with its own message. See preflightHandoffEligible.
                                 const handoff = preflightHandoffEligible({
                                     hasPrompt: prompt !== undefined,
                                     interactive: options.interactive === true,
@@ -2799,12 +2101,8 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                                     : null;
                                 if (handoff) {
                                     process.stderr.write(chalk.yellow(`[agents] every ${agent} account is exhausted — handing off to ${handoff.agent}${handoff.version ? `@${handoff.version}` : ''}\n`));
-                                    // Snapshot the PRIMARY's configured defaults BEFORE the switch —
-                                    // this is the operator's intent for this run, not the alternate's.
                                     handoffRunDefaults ??= fromProfile ? undefined : resolveRunDefaults(agent, version ?? resolveVersion(agent, cwd), cwd);
                                     agent = handoff.agent;
-                                    // Alias-resolve against the NEW harness's installs, exactly as
-                                    // the canonical --fallback parse does for its own entries.
                                     version = resolveVersionAlias(agent, handoff.version);
                                     options.fallback = handoff.remainingSpec;
                                     rotationResult = null;
@@ -2812,9 +2110,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                                 }
                                 console.error(chalk.red(formatNoHealthyAccountError(agent, strategy, resolved.exhausted)));
                                 if (recoverable.length > 0) {
-                                    // Off a TTY nobody can complete a login, so we still exit — but
-                                    // name the actual fix rather than only offering --strategy pinned,
-                                    // which would just pin the same unauthenticated account.
                                     const { loginHint } = await import('../lib/signin-badge.js');
                                     console.error(chalk.gray(`To sign in: ${loginHint(agent)} — or run \`agents run ${agent}\` from a terminal.`));
                                 }
@@ -2822,13 +2117,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                             }
                         }
                         else if (resolved.noVerifiedUsage) {
-                            // Entirely stale usage (PHNX-2526): every eligible account carries
-                            // a stale-but-present usage number and none is verified, so the
-                            // route would be a guess. NEVER auto-pick it. Interactive: show the
-                            // account picker so a human chooses with the (stale) numbers in
-                            // view. Unattended: fail loud with NO_VERIFIED_USAGE. The stale
-                            // pool survives ONLY as `resolved.rotation.healthy` for bounded
-                            // post-rejection failover, never as the initial pick.
                             const { noVerifiedUsageDecision, pickRunAccountCandidate } = await import('./run-account-picker.js');
                             const decision = noVerifiedUsageDecision({
                                 tty: isInteractiveTerminal(),
@@ -2837,18 +2125,11 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                             });
                             if (decision === 'picker') {
                                 const selected = await pickRunAccountCandidate(agent);
-                                // A cancelled picker launches nothing — same contract as the
-                                // trailing-# account picker and the sign-in launch above.
                                 if (!selected)
                                     return;
                                 version = selected.version;
-                                // Source the run.launch verdict from the account the user ACTUALLY
-                                // picked — the picker may deliberately return a logged-out one
-                                // (RUSH-2334), so it can differ from rotationResult.picked.
                                 launchSignedIn = selected.signedIn;
                                 launchEmail = selected.email;
-                                // Keep the rotation so mid-run failover can still cascade across
-                                // the other (stale) healthy accounts after a real rejection.
                                 rotationResult = resolved.rotation;
                                 await applyPickedCandidate(selected);
                                 if (!options.quiet) {
@@ -2864,18 +2145,11 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                         else if (resolved.version) {
                             version = resolved.version;
                             rotationResult = resolved.rotation;
-                            // The auto-pick already computed the launchable-signed-in verdict for
-                            // this exact version via the same gate — reuse it for run.launch.
                             if (resolved.rotation) {
                                 launchSignedIn = resolved.rotation.picked.signedIn;
                                 launchEmail = resolved.rotation.picked.email;
                                 await applyPickedCandidate(resolved.rotation.picked);
                             }
-                            // A balanced/available pick of a PROVIDER account (setup-token /
-                            // API-key) carries `providerAccount`. Resolve its env through the
-                            // same `resolveSpawnAccount` path an explicit `--account` uses, so
-                            // exec injects the credential; a native pick has no providerAccount
-                            // and resolved its slot home in applyPickedCandidate above.
                             const pickedProviderAccount = resolved.rotation?.picked.providerAccount;
                             if (pickedProviderAccount) {
                                 try {
@@ -2894,8 +2168,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                             }
                         }
                         else if (!options.quiet) {
-                            // No installed version at all (not "accounts exhausted" — that
-                            // fails loud above): keep the pre-existing default resolution.
                             process.stderr.write(chalk.yellow(`[agents] strategy ${strategy} found no usable ${agent} version; falling back to defaults\n`));
                         }
                     }
@@ -2908,21 +2180,11 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             }
             break;
         }
-        // Self-heal the launch target. A gutted install (JS wrapper present,
-        // native binary missing — a partial/raced npm extraction of the optional
-        // per-arch dependency) would otherwise spawn and die with a raw ENOENT
-        // inside the agent's own wrapper. Repair it in place (or fall back to a
-        // runnable version, re-pinning it) BEFORE we build the launch command.
-        // Skipped for headless resume-native/acp/loop paths only if it errored;
-        // here it runs for every normal dispatch. Best-effort log to stderr.
         {
             const launchTarget = version ?? resolveVersion(agent, cwd) ?? undefined;
             if (launchTarget) {
                 const healed = await ensureAgentRunnable(agent, launchTarget, options.quiet ? undefined : (m) => process.stderr.write(chalk.yellow(`[agents] ${m}\n`)));
                 if (healed === null) {
-                    // An isolated copy is never repaired by adopting another version, so
-                    // `add <agent>@latest` would build an unrelated NORMAL install rather
-                    // than fix what the user asked to run. Point at the isolated re-add.
                     const { isVersionIsolated } = await import('../lib/installations/versions.js');
                     const hint = isVersionIsolated(agent, launchTarget)
                         ? `agents add ${agent}@${launchTarget} --isolated`
@@ -2934,22 +2196,8 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             }
         }
         bootMark('ensure-runnable:done');
-        // The harness may simply not be on this machine. The self-heal above only
-        // runs when a managed version resolved, so with nothing installed we used
-        // to fall through and spawn the bare `cliCommand`, which dies as
-        // `exec: cursor-agent: not found` (exit 127) after a misleading
-        // "looks logged out" banner (RUSH-2339). Probe the executable
-        // buildExecCommand will actually spawn and fail loud instead.
-        //
-        // This is an EXISTENCE probe, not "does agents-cli manage a version". A
-        // harness the user installed themselves (Homebrew, a vendor `curl | sh`, a
-        // distro package) has no version home and MUST still launch — the PATH
-        // branch of resolveLaunchBinary is what keeps that working.
         {
             const { resolveLaunchBinary } = await import('../lib/exec.js');
-            // `version` already carries the self-heal's resolution above (it assigns
-            // `version = healed` whenever a version resolved at all), so re-deriving
-            // it with resolveVersion here would be dead.
             if (!resolveLaunchBinary(agent, version)) {
                 const target = version ? `${agent}@${version}` : agent;
                 console.error(chalk.red(`agents: ${target} is not installed on this machine.`));
@@ -2958,43 +2206,21 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             }
         }
         const defaultVersion = version ?? resolveVersion(agent, cwd);
-        // Re-apply the active rules preset before every launch (issue: preset
-        // changes via `setActiveRulesPreset` only took effect after an explicit
-        // `agents rules switch` / `agents sync`). Version-scoped, skip-fast when
-        // nothing changed — see lib/rules/run-sync.ts. Placed here (immediately
-        // after the resolved version is known, before ACP/loop/fallback branch
-        // off) so every downstream dispatch path for this agent+version sees a
-        // fresh rules file, not just the plain execAgent path. `defaultVersion`
-        // is null when nothing is installed yet — execAgent handles that error
-        // path itself; there's no version home to sync into.
         if (defaultVersion) {
             applyActiveRulesPresetAtRun(agent, defaultVersion, getVersionHomePath(agent, defaultVersion));
             applySystemResourcesAtRun(agent, defaultVersion, getVersionHomePath(agent, defaultVersion));
         }
         bootMark('rules-sync:done');
-        // Login preflight (advisory, warn + continue). On a local INTERACTIVE
-        // launch, probe whether this agent's account has a credential and print a
-        // one-line warning if it looks logged out — so you find out BEFORE the TUI
-        // opens, not after typing a prompt and getting "/login" back. Inspect the
-        // selected account home, not an unrelated global login. This file-based
-        // read makes no Keychain ACL prompt. It can still false-negative for opaque
-        // credentials, so this NEVER blocks — it warns and launches anyway. Skipped
-        // for --json/--quiet, when a rotation already picked a signed-in account,
-        // and via --no-auth-check / AGENTS_NO_AUTH_CHECK=1. (--device/--lease return
-        // earlier.)
         {
             const { shouldCheckLoginBeforeLaunch, loginHint } = await import('../lib/signin-badge.js');
             const preflight = shouldCheckLoginBeforeLaunch({
                 interactive: options.interactive,
-                forceInteractive, // a resumed interactive session (e.g. `run kimi --resume`) opens the TUI too
+                forceInteractive,
                 headless: options.headless,
                 hasPrompt: prompt !== undefined,
                 json: options.json,
                 quiet: options.quiet,
                 authCheckDisabled: options.authCheck === false || process.env.AGENTS_NO_AUTH_CHECK === '1',
-                // `signInLaunch` means the zero-healthy path already reported this exact
-                // account as logged out and named the login command, so re-probing here
-                // only prints a second, near-identical warning.
                 rotated: !!rotationResult || accountPickerRequested || signInLaunch || (launchAccount?.account?.kind ?? spawnAccount?.kind) === 'provider',
             });
             if (preflight) {
@@ -3002,11 +2228,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                     const { getAccountInfo } = await import('../lib/agents.js');
                     const authVersion = accountConfigVersion ?? version;
                     const info = await getAccountInfo(agent, execHome ?? (authVersion ? getVersionHomePath(agent, authVersion) : undefined));
-                    // Claude authenticates interactively from a per-version setup-token on a
-                    // keychain-less worker (the shim's .oauth_token fallback), which the
-                    // native-credential probe above can't see — so don't warn "logged out" when
-                    // a setup-token resolves for this version. No-op on macOS, where the
-                    // credential lives in the keychain and resolveClaudeSetupToken returns null.
                     let authedViaSetupToken = false;
                     if (!info.signedIn && agent === 'claude' && version) {
                         const { resolveClaudeSetupToken } = await import('../lib/claude-account-token.js');
@@ -3024,19 +2245,14 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                     }
                 }
                 catch {
-                    // Advisory only — a probe failure must never block a launch.
                 }
             }
         }
         const runDefaults = fromProfile
             ? { sources: {} }
             : resolveRunDefaults(agent, defaultVersion, cwd);
-        // Accept the four canonical modes plus 'full' as a permanent silent
-        // alias for 'skip' (rewritten downstream by normalizeMode in exec.ts).
         let mode = options.mode;
         const modeSource = runCmd.getOptionValueSource('mode');
-        // A configured mode carried across a preflight handoff wins over the
-        // alternate harness's own configured default (see handoffRunDefaults).
         const configuredMode = handoffRunDefaults?.mode ?? runDefaults.mode;
         const modeFromRunDefault = modeSource === 'default' && !!configuredMode;
         if (modeFromRunDefault) {
@@ -3046,20 +2262,8 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             console.error(chalk.red(`Invalid mode: ${mode}. Use plan, edit, auto, or skip ('full' accepted as alias for skip).`));
             process.exit(1);
         }
-        // Default CLI mode is the generic 'plan'. Agents without a read-only
-        // mode (antigravity, …) degrade via resolveMode to their
-        // safest native mode (modes[0], typically edit). That covers both the
-        // implicit default and an explicit `--mode plan`, so multi-agent
-        // scripts can pass a uniform plan flag without per-agent branching.
-        // Mode degradation is never silent: buildExecCommand emits one stderr
-        // warning for the requested-to-resolved transition unless --quiet is set.
-        // `skip` still hard-fails when unsupported — pretending we bypassed
-        // permissions would be unsafe.
         const modeIsDefault = modeSource === 'default';
         let requestedMode = normalizeMode(mode);
-        // Codex's intrinsic omitted-mode default is safe writable: workspace plus
-        // common caches, network enabled, approvals on request. An explicit
-        // --mode plan and a configured run default remain read-only.
         const { modeWasImplicit } = await import('../lib/codex-policy.js');
         const wasModeImplicit = modeWasImplicit(modeSource, modeFromRunDefault);
         if (wasModeImplicit)
@@ -3073,11 +2277,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             process.exit(1);
         }
         mode = resolvedMode;
-        // Fail fast on the headless-plan stall footgun: a slash command run
-        // headless under the implicit default 'plan' mode hangs forever at
-        // ExitPlanMode (no TTY to approve the plan). Tell the user how to fix it
-        // instead of leaving them staring at a frozen process. Explicit
-        // `--mode plan` is respected for genuine read-only command runs.
         const stallCmd = headlessPlanStallCommand({
             prompt,
             interactive: resolveInteractive({ prompt, headless: options.headless, interactive: options.interactive || forceInteractive }),
@@ -3105,29 +2304,16 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             console.error(chalk.red(err.message));
             process.exit(1);
         }
-        // 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 = {};
-        // Resource-profile scoping (CTX-1): agents-cli computes which bundle
-        // names the active profile allows and forwards it as the client's
-        // `allowedBundles` on every local resolution — the standalone has no
-        // concept of a profile. undefined (no active profile) is full trust.
         const secretsContext = await resolveSecretsContextForRun(agent);
         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 resolveHostSshTarget(host);
                     const bundleEnv = await remoteResolveEnv(target, bundleName, { osLookupName: host });
                     console.log(chalk.gray(`[secrets] Resolved ${bundleName}@${host}: ${Object.keys(bundleEnv).length} keys (remote, ephemeral)`));
@@ -3139,12 +2325,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                         agent,
                         keys: secretsKeysSubset,
                         allowExpired: options.allowExpired,
-                        // The harness identity scopes any cached grant. An agent launch
-                        // resolves broker-only and fails fast naming
-                        // `agents secrets unlock <bundle>` (bundles.ts:interactiveUnlock) — it
-                        // MUST NOT raise a Touch ID sheet regardless of tty (SEC-13). Gating on
-                        // isHeadlessSecretsContext() left `--interactive` launches (the watchdog's
-                        // `agents run auto --interactive`) able to prompt, piling up helper sheets.
                         agentOnly: true,
                     }, secretsContext);
                     const entries = await describeBundle(bundle, secretsContext);
@@ -3165,11 +2345,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
         const autoShareEnv = options.autoSecrets !== false
             ? shareRuntimeEnv()
             : undefined;
-        // Merge order (later wins): profile env < selected account < auto share token < secrets bundles < --env K=V.
-        // Profile carries provider auth; secrets bundles carry user-defined
-        // values; --env is the per-invocation override. The share token is
-        // best-effort: if it is not already in env or an unlocked bundle, unrelated
-        // runs keep working, and `agents artifacts share` itself still fails loudly on use.
         const hasOverrides = profileEnv || accountEnv || autoShareEnv || options.secrets.length > 0 || userEnv;
         const env = hasOverrides
             ? { ...(profileEnv ?? {}), ...(accountEnv ?? {}), ...(autoShareEnv ?? {}), ...secretsEnv, ...(userEnv ?? {}) }
@@ -3180,10 +2355,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             ?? (!fromProfile && modelSource === undefined
                 ? (workflowModel ?? (options.fallback ? undefined : runDefaults.model))
                 : undefined);
-        // Cost tiers (cheap|default|best|ultra) resolve against a harness's own model
-        // catalog. A custom harness's model comes from its endpoint, not the host
-        // harness, so a tier here would forward an incompatible host-harness model to a
-        // different API. Discard it loudly and let the custom harness's own model stand.
         if (fromProfile && model && isTierToken(model)) {
             process.stderr.write(chalk.yellow(`[agents] --model ${model}: cost tiers don't apply to custom harness '${rawAgent}' ` +
                 `(its model comes from the endpoint) — ignoring the tier, using the custom harness's configured model\n`));
@@ -3211,34 +2382,19 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             resume: resumeNative,
             verbose: options.verbose,
             modeWarningState: { quiet: options.quiet },
-            // --raw, --no-tmux (commander negation → options.tmux === false), and
-            // --disable-tmux all bypass the interactive tmux wrapper. AGENTS_NO_TMUX=1
-            // does the same via the env check in exec.ts.
             raw: options.raw || options.tmux === false || options.disableTmux === true,
             timeout: options.timeout,
             env,
             toolsRestrict: workflowToolsRestrict,
             mcpConfigPath: workflowMcpConfigPath,
             passthroughArgs,
-            // Set only on the REMOTE side of a `--device` dispatch (the launcher
-            // forwards `--emit-session-id`): print the resolved session id as a
-            // stdout sentinel so the launcher captures the id this run coined.
             emitSessionId: options.emitSessionId === true,
-            // Observability-only: carried onto the pre-launch `run.launch` event so
-            // the stream records HOW this version was chosen. Neither affects the
-            // spawn. `resolvedVia` attributes the version source cheaply — an
-            // explicit @version pin, a strategy rotation, or the pinned default.
             strategy,
             resolvedVia: rawVersion
                 ? 'explicit-pin'
                 : rotationResult
                     ? 'rotated'
                     : 'pinned-default',
-            // Launchable-signed-in verdict for the ACTUAL launched candidate, set per
-            // resolution branch above (auto-pick from rotation.picked; interactive
-            // picker from the user's `selected`, which may be logged out). Undefined
-            // for a pinned-default / explicit-pin launch, where spawnAgent probes the
-            // version home itself.
             launchSignedIn,
             launchEmail,
         };
@@ -3289,11 +2445,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 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,
@@ -3301,26 +2452,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 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)
-        // and interactive/no-prompt runs. 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.
-        //
-        // Composes with an explicit --fallback chain: the same-agent accounts are
-        // UNSHIFTED ahead of the user's cross-agent entries, so a rate limit
-        // first tries the other accounts of the same agent (cheapest recovery —
-        // same CLI, session continues) and only then cascades to codex/gemini/etc.
-        // Profiles never compose: strategy is skipped for them, rotationResult
-        // stays null. (fromProfile's model-swap unshift above is therefore never
-        // displaced by this one.)
         if (shouldArmRotationFailover({
             hasRotation: !!rotationResult,
             hasVersion: !!version,
@@ -3330,11 +2461,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             loop: !!options.loop,
             resumeCheckpoint: !!options.resumeCheckpoint,
         })) {
-            // With an explicit alternate harness configured, "use the alternate once
-            // the primary's accounts are exhausted" is the policy — so EVERY healthy
-            // same-agent account has to be tried first, not the default cap of three
-            // (PHNX-3999 F19). Without one, the cap stands: it bounds how long a
-            // rate-limited run keeps retrying itself.
             const failover = rotationFailoverChain(rotationResult, version, fallback.length > 0 ? (rotationResult.healthy.length || DEFAULT_ROTATION_FAILOVER_LIMIT) : undefined);
             if (failover.length > 0) {
                 fallback.unshift(...failover);
@@ -3367,11 +2493,7 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                     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 });
-                // ACP headless run always has a prompt; surface any unpushed commits
-                // and any open PR left unattended (RUSH-2394).
                 if (shouldWarnUnpushed(mode, false)) {
                     await warnUnpushedWork(cwd);
                     await warnOrphanedOpenPr(cwd);
@@ -3383,21 +2505,9 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 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,
@@ -3412,14 +2522,12 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                     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);
@@ -3435,7 +2543,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                     }
                 }
                 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`));
                 }
             }
@@ -3444,9 +2551,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
         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;
@@ -3454,29 +2558,17 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 fs.rmSync(path.dirname(workflowMcpConfigPath), { recursive: true, force: true });
             }
             catch {
-                // 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();
@@ -3487,10 +2579,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             });
             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
-        // guard, not a replacement. Composable, not bypassing.
         let loopConfig;
         try {
             loopConfig = buildLoopConfig(options, workflowLoop);
@@ -3528,12 +2616,8 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 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`));
-                // 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 });
-                // A loop is always headless; surface any commits it left unpushed
-                // and any open PR left without a durable lander (RUSH-2394).
                 if (shouldWarnUnpushed(mode, false)) {
                     await warnUnpushedWork(cwd);
                     await warnOrphanedOpenPr(cwd);
@@ -3547,15 +2631,7 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 process.exit(1);
             }
         }
-        // Agent footgun (RUSH-1829): a run with no prompt and no explicit
-        // --interactive resolves to interactive intent, but in a non-TTY shell
-        // (a headless agent, a pipe, CI) there is no terminal to host the REPL —
-        // the TUI attaches to dead stdin and hangs forever. Fail fast with the
-        // headless alternatives instead of launching a doomed interactive session.
         if (inferredInteractiveWithoutTty(execOptions, isInteractiveTerminal())) {
-            // Tear down the workflow MCP config + subagents staged above before we
-            // exit — same as every sibling exit path; requireInteractiveSelection
-            // process.exits, so cleanup must happen first or it leaks.
             cleanupWorkflowMcpConfig();
             cleanupWorkflowSubagents();
             requireInteractiveSelection(`Launching ${agent} interactively`, [
@@ -3568,10 +2644,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             let ranAgent = agent;
             let ranVersion = defaultVersion;
             if (fallback.length > 0 || (rotationResult !== null && prompt !== undefined && !options.interactive)) {
-                // Fallback and balanced runs need captured output so a clean-exit
-                // session-limit refusal can update account availability.
-                // 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;
@@ -3582,28 +2654,11 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             }
             cleanupWorkflowMcpConfig();
             cleanupWorkflowSubagents();
-            // Surface committed-but-unpushed work a headless writable run left
-            // behind, so it isn't silently stranded in a worktree. Also warn when
-            // the branch still has an OPEN PR (RUSH-2394) — a background
-            // `gh pr checks --watch` dies with the agent. Advisory only,
-            // never throws; skipped for interactive runs (the human sees the shell)
-            // and read-only plan mode (can't commit).
             if (shouldWarnUnpushed(mode, resolveInteractive(execOptions))) {
                 await warnUnpushedWork(cwd);
                 await warnOrphanedOpenPr(cwd);
             }
-            // 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 });
-            // A clean headless exit is real auth evidence — the account authenticated
-            // and produced a result. Record it as the per-account FACT `agents view`
-            // renders (`last used ok`), keyed to the slot the run used so it lands on
-            // the right row and clears any stale failure fact (PHNX-4116). A non-zero
-            // exit is NOT recorded as an auth failure: the exit code alone does not
-            // prove the token was rejected (a task can fail for a hundred reasons), and
-            // a lying "auth failure" fact is worse than none. Real auth failures are
-            // recorded where they are actually detected (the routine runner's
-            // isAuthFailureFromLog sites) and by the daemon probe.
             if (exitCode === 0) {
                 recordRunAuthOutcome({
                     agent: ranAgent,
@@ -3613,8 +2668,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                     outcome: { ok: true },
                 });
             }
-            // First-successful-run star nudge (one-time, non-nagging). Only on a
-            // clean run, and never when output is machine-readable/quiet.
             if (exitCode === 0)
                 maybeShowStarNudge({ quiet: options.json || options.quiet });
             process.exit(exitCode);
@@ -3622,8 +2675,6 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
         catch (err) {
             cleanupWorkflowMcpConfig();
             cleanupWorkflowSubagents();
-            // An agent that committed then crashed is the case where stranded work
-            // matters most — warn before exiting the error path too.
             if (shouldWarnUnpushed(mode, resolveInteractive(execOptions))) {
                 await warnUnpushedWork(cwd);
                 await warnOrphanedOpenPr(cwd);