@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/exec.js

@@ -1,10 +1,4 @@
 import { captureLaunchBinding, recordCompletedLaunch } from './session/hook-sessions.js';
-/**
- * Agent execution -- command building, process spawning, and rate-limit fallback.
- *
- * Translates high-level ExecOptions into CLI invocations for each supported agent,
- * manages environment isolation per agent, and chains fallback agents on rate limits.
- */
 import { spawn } from 'child_process';
 import { randomUUID } from 'crypto';
 import * as fs from 'fs';
@@ -49,13 +43,6 @@ import { getAccountInfo } from './agents.js';
 import { getUsageLookupKey, noteClaudeSessionLimit, noteClaudeOutOfCredits, clearClaudeAccountRefusal, parseClaudeSessionLimitReset, noteClaudeModelRefusal, clearClaudeModelRefusal, parseClaudeModelRefusal, claudeModelRefusalKey, } from './accounting/usage.js';
 import { claudeProjectDirName } from './project-key.js';
 import { bootMark, flushBootProfile } from './boot-profile.js';
-/**
- * Map a raw mode string (CLI flag, YAML field, env var) to the canonical Mode.
- *
- * Accepts the historical `full` spelling and rewrites it to `skip`. Throws on
- * anything outside the four canonical values so bad input fails loud at the
- * boundary rather than silently picking a wrong code path.
- */
 export function normalizeMode(input) {
     if (!input) {
         throw new Error(`Mode is required. Use one of: ${ALL_MODES.join(', ')}.`);
@@ -67,23 +54,6 @@ export function normalizeMode(input) {
         return v;
     throw new Error(`Invalid mode '${input}'. Use one of: ${ALL_MODES.join(', ')} (or 'full' as a deprecated alias for 'skip').`);
 }
-/**
- * Detect the headless-plan stall footgun.
- *
- * A slash command (e.g. `/code:commit`) run headless under the IMPLICIT default
- * `plan` mode hangs forever: plan is read-only, so the agent calls ExitPlanMode
- * to start working, and in a headless run there is no TTY to approve it. The
- * process just sits there. Callers use this to fail fast with a fix instead.
- *
- * Returns the offending command token (e.g. `/code:commit`) when the run should
- * be blocked, else null. Guards are deliberately narrow:
- *   - interactive runs / no prompt        -> not headless, never blocks
- *   - explicit --mode (modeIsDefault false) -> respected; `--mode plan` is a
- *     legitimate read-only command run and must not be blocked
- *   - resolved mode is not `plan`          -> only plan stalls at ExitPlanMode
- *   - prompt is not a slash command        -> natural-language read-only prompts
- *     ("summarize commits") are a valid default-plan use and must not be blocked
- */
 export function headlessPlanStallCommand(args) {
     const { prompt, interactive, mode, modeIsDefault } = args;
     if (interactive === true || prompt === undefined)
@@ -97,35 +67,14 @@ export function headlessPlanStallCommand(args) {
         return null;
     return trimmed.split(/\s+/)[0];
 }
-/**
- * Resolve a requested mode against an agent's capability table.
- *
- * - `auto` on an agent without auto support silently degrades to `edit`
- *   (every agent supports edit-like behavior as its default).
- * - `plan` on an agent without a read-only mode degrades to the agent's
- *   safest native mode (`capabilities.modes[0]`, typically `edit`). Agents
- *   like antigravity have no plan flag; hard-failing made
- *   multi-agent scripts (`--mode plan` for everyone) unusable and diverged
- *   from `agents teams add`, which already defaults to `edit`. Callers that
- *   care (the `agents run` CLI) must surface a warning when requested ≠
- *   resolved so the elevation is not silent.
- * - `skip` on an agent without skip support throws with a clear message
- *   naming the agent's supported modes. No silent fallback — the user
- *   explicitly asked to bypass permissions; pretending we did is unsafe.
- */
 export function resolveMode(agent, requested) {
     const supported = AGENTS[agent].capabilities.modes;
     if (supported.includes(requested))
         return requested;
     if (requested === 'auto') {
-        // Fall back to edit — guaranteed to exist on every agent (every agent has
-        // at least 'edit' in its modes table, since that's the default behavior).
         return 'edit';
     }
     if (requested === 'plan') {
-        // No read-only mode on this agent. modes[0] is the declared safest mode
-        // (edit for antigravity/…). Prefer that over hard-fail so
-        // uniform multi-agent `--mode plan` dispatches still run.
         return supported[0];
     }
     throw new Error(`${agent} does not support '${requested}' mode. Supported modes: ${supported.join(', ')}.`);
@@ -173,21 +122,9 @@ export function resolveHeadlessMode(agent, requested, interactive, warningContex
     }
     return mode;
 }
-/**
- * The mode an agent should run in when the caller has no preference.
- *
- * Returns the first entry in the agent's `capabilities.modes` table — the
- * declaration order is the source of truth for "the safest mode this agent
- * supports." Agents that include `plan` list it first; agents like
- * antigravity that have no read-only mode list `edit` first.
- *
- * Prefer this over a hard-coded `'plan'` when the agent is known. `resolveMode`
- * also maps an unsupported `'plan'` request onto this same value.
- */
 export function defaultModeFor(agent) {
     return AGENTS[agent].capabilities.modes[0];
 }
-/** Safe mode used when the user did not provide --mode or a configured default. */
 export function implicitModeFor(agent) {
     return agent === 'codex' ? 'edit' : 'plan';
 }
@@ -234,32 +171,16 @@ export function codexSandboxPreflight(args) {
         `\n` +
         `Or run codex WITHOUT a filesystem sandbox instead: add --mode skip.`);
 }
-/**
- * Identity a custom-harness run stamps on env / pid-registry / sidecars.
- * `agent` is the host CLI; `harnessName` is the profile the user launched.
- * Empty/whitespace harness names fall back to the host so a blank stamp
- * never hides a real agent.
- */
 export function stampedAgentName(options) {
     const harness = options.harnessName?.trim();
     return harness || options.agent;
 }
-/**
- * Profile name when it differs from the host agent. Undefined for a native
- * run, so pid-registry / sidecar records stay sparse.
- */
 export function customHarnessName(options) {
     const harness = options.harnessName?.trim();
     if (!harness || harness === options.agent)
         return undefined;
     return harness;
 }
-/**
- * Resolve interactive vs headless. Explicit flags are definitive and win over
- * inference: `--interactive` forces interactive, `--headless` forces headless.
- * With neither flag, prompt presence decides (prompt -> headless, none -> interactive).
- * `--interactive` takes precedence over `--headless`; the CLI layer rejects passing both.
- */
 export function resolveInteractive(options) {
     if (options.interactive === true)
         return true;
@@ -267,48 +188,17 @@ export function resolveInteractive(options) {
         return false;
     return options.prompt === undefined;
 }
-/**
- * True when a run resolved to *inferred* interactive intent — no prompt and no
- * explicit `--interactive` — but there is no terminal to host the REPL. Launching
- * would attach a TUI to a dead stdin and hang forever, so the caller should fail
- * fast with the headless alternatives instead (RUSH-1829).
- *
- * An explicit `--interactive` is the caller's deliberate choice and is never
- * blocked (they may be driving a PTY we can't detect). Pure — the TTY state is a
- * parameter so this is unit-testable without touching `process.std*`.
- */
 export function inferredInteractiveWithoutTty(options, isTty) {
     if (options.interactive === true)
         return false;
     return resolveInteractive(options) && !isTty;
 }
-/**
- * Decide whether spawnAgent must capture (PIPE + tee) the child's stdout so the
- * live budget watcher can parse it (issue #346, FIX 3).
- *
- * The bug this fixes: stdout used to be PIPED only when downstream output was
- * piped (`piped = !isTTY`). For a normal headless run AT A TERMINAL, stdout was
- * 'inherit', so `child.stdout` was null and the watcher — hence the mid-run
- * hard-cap kill — was silently skipped. We now tap stdout for ALL
- * non-interactive runs when caps are active, regardless of TTY, and tee it back
- * so the user still sees output. Interactive REPLs are never tapped (the human
- * owns the TTY; they rely on the pre-flight gate).
- *
- * @param interactive  resolveInteractive() result for the run
- * @param piped        true when the parent's stdout is NOT a TTY (output piped)
- * @param capsActive   true when a budget watcher is attached (caps configured)
- */
 export function shouldTapStdout(interactive, piped, capsActive, captureTail = false) {
     if (interactive)
         return false;
-    // Always pipe when the caller pipes us downstream (preserve composability),
-    // when caps are active so the watcher can read the stream at a TTY, or when
-    // a fallback chain needs a stdout tail for rate-limit detection.
     return piped || capsActive || captureTail;
 }
-/** Pattern for valid environment variable names (C identifier rules). */
 const EXEC_ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
-/** Parse a single KEY=VALUE string into a tuple, validating the key name. */
 function parseExecEnvEntry(entry) {
     const separatorIndex = entry.indexOf('=');
     if (separatorIndex <= 0) {
@@ -321,52 +211,21 @@ function parseExecEnvEntry(entry) {
     }
     return [key, value];
 }
-/** Parse an array of KEY=VALUE strings into an env record. Returns undefined for empty input. */
 export function parseExecEnv(entries) {
     if (entries.length === 0) {
         return undefined;
     }
     return Object.fromEntries(entries.map(parseExecEnvEntry));
 }
-/**
- * Resolve the launch id a run exports as `AGENT_LAUNCH_ID`.
- *
- * The launch id is the stable correlation key the SessionStart hook records
- * alongside the agent's real session id (terminals/sessions/<pid>.json), so it
- * is what maps a launch to its exact session even when the hook runs under a
- * different pid (tmux pane leaf / cmd.exe wrapper) — and, across an SSH hop, what
- * lets a `--device` launcher resolve the remote-coined id for agents that never
- * accept a forced `--session-id`.
- *
- * ADOPT a caller-supplied `AGENT_LAUNCH_ID` (a `--device` launcher forwards one via
- * `--env` so it controls the key end-to-end); MINT a fresh one otherwise (every
- * local run, which passes none). A malformed inbound value is ignored in favour
- * of a fresh mint — the key must be a real correlation id, never an empty string.
- */
 export function resolveLaunchId(envLaunchId) {
     const inbound = envLaunchId?.trim();
     return inbound ? inbound : randomUUID();
 }
-/**
- * Build the process environment for an agent invocation.
- * Pins CLAUDE_CONFIG_DIR for Claude, CODEX_HOME for Codex, and COPILOT_HOME
- * for GitHub Copilot; strips the other agents' env vars so they don't leak
- * into unrelated invocations.
- */
+// Child runs shed parent session/mailbox/account/exec-home identity; lineage is reintroduced only through explicit parent fields.
 export function buildExecEnv(options) {
     const result = { ...sanitizeProcessEnv(process.env) };
-    // Config-dir env vars are agent-specific. When the caller is running inside
-    // an agent-managed shell, process.env already carries one; spreading into a
-    // different agent's env would leak a config pointer the target CLI doesn't
-    // understand. Each harness adapter pins its own config-dir var to the versioned
-    // home and strips the foreign ones; a harness with no config-dir env (the old
-    // `else`) has no adapter override, so all four are stripped here.
     const configAdapter = resolveHarnessAdapter(options.agent);
     if (configAdapter.applyExecConfigEnv) {
-        // Resolve version/versionHome here (this module already imports
-        // installations/versions); the adapters must not import it themselves or they
-        // close a versions -> shims -> harness -> adapter import cycle. execHome is
-        // the account slot (PHNX-3940 T5) and wins over a legacy configVersion label.
         const { version, versionHome } = resolveExecConfigHome(options);
         configAdapter.applyExecConfigEnv(result, {
             agent: options.agent,
@@ -380,108 +239,59 @@ export function buildExecEnv(options) {
     else {
         stripForeignConfigDir(result);
     }
-    // A new harness must not inherit its spawner's own session/mailbox or editor
-    // ownership. Keep those relationships as lineage, including across SSH.
     delete result.AGENT_SESSION_ID;
     delete result.AGENTS_SESSION_ID;
     delete result.AGENTS_MAILBOX_DIR;
     delete result.AGENT_TERMINAL_ID;
     const launchIdentity = launchIdentityEnv();
     Object.assign(result, launchIdentity);
-    // Point the agent at its own mailbox so the PreToolUse `mailbox-inject` hook
-    // knows which box to drain and inject mid-run. Keyed by the session id — the
-    // same id the writer resolves via mailboxIdForActiveSession(). A loop run
-    // overrides this to its run-level box via options.env (spread below), so all
-    // iterations share one inbox.
     if (options.sessionId && isValidMailboxId(options.sessionId)) {
         result.AGENTS_MAILBOX_DIR = mailboxDir(options.sessionId);
-        // Full session id for agent-callable tools (`agents feed post`, etc.).
         result.AGENT_SESSION_ID = options.sessionId;
         result.AGENTS_SESSION_ID = options.sessionId;
     }
-    // Lineage edge: the child's parent is THIS process's session (the spawner), so a
-    // sub-agent's events carry a walkable edge back to who spawned it. The event floor
-    // (events.ts::resolveProvenance) reads AGENTS_PARENT_SESSION_ID and stamps it on
-    // every event the child emits. `options.sessionId` is the CHILD's id, so read the
-    // spawner from the live env; guard a same-session resume from naming itself parent.
-    // An SSH continuation has no runtime marker; keep its forwarded parent edge.
     delete result.AGENTS_PARENT_SESSION_ID;
     const spawnerSessionId = launchIdentity.AGENTS_PARENT_SESSION_ID;
     if (spawnerSessionId && spawnerSessionId !== options.sessionId) {
         result.AGENTS_PARENT_SESSION_ID = spawnerSessionId;
     }
     result.AGENTS_RUNTIME = resolveInteractive(options) ? 'terminal' : 'headless';
-    // The agent's own `secrets …` calls must hit the same store agents-cli reads
-    // for it: the process client points the standalone at the user agents dir
-    // (buildServeEnv, MIG-1), while a bare `secrets` defaults to ~/.secrets. Left
-    // unset, an agent's `secrets exec` ran against a second broker and a second
-    // event log, and an unlock in one was invisible in the other. An explicit
-    // SECRETS_HOME in the launching environment wins, matching buildServeEnv.
+    // Bind the standalone secrets client to the same store agents-cli resolved.
     result.SECRETS_HOME = result.SECRETS_HOME ?? getUserAgentsDir();
-    // Durable SessionStart metadata. The hook joins these launch facts to the
-    // harness-provided real session id and writes them under the shared history
-    // directory, so a later resume can restore the permission boundary without
-    // re-parsing harness-specific transcripts.
     result.AGENTS_RUN_MODE = resolveHeadlessMode(options.agent, normalizeMode(options.mode), resolveInteractive(options), options.modeWarningContext, options.modeWarningState);
     result.AGENTS_HISTORY_DIR = getHistoryDir();
-    // Durable origin version for a later native resume. The SessionStart hook joins
-    // this to the harness's real session id (like AGENTS_RUN_MODE), so recovery can
-    // pin the exact origin version even when the transcript carries no derivable one
-    // (codex's `.codex-homes/<version>/` home) — the "version not recorded" fallback
-    // to `/continue` this closes (PHNX-3626). Resolve the concrete version-home id
-    // the same way the spawn path does; only stamp a real one.
     if (options.agent) {
         const runVersion = options.version ?? resolveVersion(options.agent, options.cwd || process.cwd());
         if (runVersion)
             result.AGENTS_RUN_VERSION = runVersion;
     }
-    // So activity / feed posts stamp the right harness without re-detecting.
-    // A custom-harness run (`agents run deepseek`) must stamp the PROFILE name,
-    // not the host CLI (`claude`) — otherwise sessions and feed posts cannot
-    // tell the two apart (PHNX-2935).
     if (options.agent) {
         result.AGENTS_AGENT_NAME = stampedAgentName(options);
     }
     if (options.cwd) {
         result.AGENTS_CWD = options.cwd;
     }
-    // An account-slot launch (PHNX-3940 T5) tells the versioned alias which
-    // HOME-shaped dir owns this run's config, so the alias's version-home pin
-    // (claude: CLAUDE_CONFIG_DIR) yields to the slot instead of overriding the
-    // adapter's pin above. Set only for a slot launch and cleared otherwise, so a
-    // run spawned from inside a slot session never inherits its parent's slot.
     if (options.execHome) {
         result.AGENTS_EXEC_HOME = options.execHome;
     }
     else {
         delete result.AGENTS_EXEC_HOME;
     }
-    // Durable account identity for this run (PHNX-3940 model-refusal tracking).
-    // Cleared when absent so a run spawned from inside an account-scoped session
-    // never inherits its parent's account id.
     if (options.accountId) {
         result.AGENTS_RUN_ACCOUNT_ID = options.accountId;
     }
     else {
         delete result.AGENTS_RUN_ACCOUNT_ID;
     }
-    // Export the run's durable name (companion to AGENT_SESSION_ID) so a
-    // SessionStart hook / the agent can associate its transcript with the handle
-    // the user gave the run. Only set when --name was passed.
     if (options.name) {
         result.AGENT_SESSION_NAME = options.name;
     }
-    // Actor provenance -- who initiated this run. Rides the env so the whole spawn
-    // tree shares one actor, and (for a resolved human) so the agent's own git
-    // commits are credited to the person instead of the shared account. options.env
-    // (spread last) overrides any of these keys a caller sets explicitly.
     Object.assign(result, actorEnv(resolveActor()));
     return {
         ...result,
         ...options.env,
     };
 }
-/** Materialize config roots for vendor CLIs that do not create parents recursively. */
 export function ensureVendorHomeDir(agent, versionHome) {
     if (agent !== 'cursor' && agent !== 'grok' && agent !== 'copilot')
         return null;
@@ -502,12 +312,6 @@ function ensureVendorHomeForSpawn(options) {
     if (versionHome)
         ensureVendorHomeDir(options.agent, versionHome);
 }
-/**
- * CLI command templates for every supported agent.
- *
- * Each agent's `modeFlags` keys MUST match the modes listed in
- * AGENTS[agent].capabilities.modes. A test in exec.test.ts asserts this.
- */
 export const AGENT_COMMANDS = {
     claude: {
         base: ['claude'],
@@ -529,13 +333,9 @@ export const AGENT_COMMANDS = {
         promptFlag: 'positional',
         resume: { subcommand: 'resume' },
         modeFlags: {
-            // Native Codex modes are assembled by codexPolicyArgs below. Named
-            // permission profiles keep filesystem access and network access
-            // independent; legacy --sandbox flags cannot express that combination.
             plan: [],
             edit: [],
             auto: [],
-            // skip = codex --yolo: drops the sandbox entirely and approves anything.
             skip: ['--dangerously-bypass-approvals-and-sandbox'],
         },
         jsonFlags: ['--json'],
@@ -556,9 +356,6 @@ export const AGENT_COMMANDS = {
     opencode: {
         base: ['opencode', 'run'],
         promptFlag: 'positional',
-        // opencode's native resume is `opencode --session <id>` (NOT under `run`), so
-        // it does not compose with this headless `run` base. Until that's verified on
-        // a box with opencode installed, opencode resumes via Tier-2 `/continue`.
         modeFlags: {
             plan: ['--agent', 'plan'],
             edit: ['--agent', 'build'],
@@ -577,17 +374,6 @@ export const AGENT_COMMANDS = {
         jsonFlags: ['--output-format', 'stream-json'],
         modelFlag: '--model',
     },
-    // GitHub Copilot CLI (`@github/copilot`, GA 2026-02-25). Flags verified
-    // against `copilot --help` from v0.0.413+:
-    //   -p, --prompt <text>          non-interactive one-shot
-    //   --mode <interactive|plan|autopilot>
-    //   --autopilot                  start in autopilot (smart-classifier) mode
-    //   --allow-all-tools            required for non-interactive tool exec
-    //   --allow-all (alias --yolo)   tools + paths + URLs
-    //   --output-format <text|json>  json => JSONL, one object per line
-    //   --model <model>
-    // Plan mode is read-only so it does not need an allow-tools grant; edit
-    // needs --allow-all-tools so headless runs don't stall on prompts.
     copilot: {
         base: ['copilot'],
         promptFlag: '-p',
@@ -613,20 +399,14 @@ export const AGENT_COMMANDS = {
         base: ['goose', 'run'],
         promptFlag: 'positional',
         modeFlags: {
-            // goose has no permission flags — edit is the default behavior.
             edit: [],
         },
     },
     // TODO: --output-format json is documented but currently broken upstream
-    // ("flags provided but not defined: -output-format"). Track resolution at
-    // https://github.com/google-antigravity/antigravity-cli/issues/7 before
-    // adding `jsonFlags` here.
     antigravity: {
         base: ['agy'],
         promptFlag: 'positional',
         modeFlags: {
-            // agy --help shows no plan/edit flags; default behavior is edit-like
-            // (prompts on tool use). Only skip has an explicit flag.
             edit: [],
             skip: ['--dangerously-skip-permissions'],
         },
@@ -637,7 +417,6 @@ export const AGENT_COMMANDS = {
         base: ['grok'],
         promptFlag: '-p',
         modeFlags: {
-            // grok --help lists `--permission-mode plan`; the TUI defaults to ask.
             plan: ['--permission-mode', 'plan'],
             edit: [],
             skip: ['--always-approve'],
@@ -659,18 +438,13 @@ export const AGENT_COMMANDS = {
         modelFlag: '--model',
         resume: { flag: '--session', since: '0.19.2' },
     },
-    // Factory AI Droid (`droid exec` for headless, `droid` for TUI). Flags from
-    // docs.factory.ai CLI reference: prompt is positional; --auto low|medium|high
-    // escalates autonomy (default is read-only); --skip-permissions-unsafe drops
-    // all guardrails; -o stream-json streams JSONL events; -m selects the model.
-    // The `exec` subcommand is dropped for interactive runs (see buildExecCommand).
     droid: {
         base: ['droid', 'exec'],
         promptFlag: 'positional',
         modeFlags: {
-            plan: [], // droid's default exec mode is read-only
-            edit: ['--auto', 'low'], // create/edit files, non-destructive
-            auto: ['--auto', 'high'], // full autonomy
+            plan: [],
+            edit: ['--auto', 'low'],
+            auto: ['--auto', 'high'],
             skip: ['--skip-permissions-unsafe'],
         },
         jsonFlags: ['-o', 'stream-json'],
@@ -685,14 +459,6 @@ export const AGENT_COMMANDS = {
         },
         modelFlag: '--model',
     },
-    // Meta Muse Code (`muse exec` headless, `muse` TUI). Flags from
-    // `muse --help` / `muse exec --help` (v0.1.0): prompt is positional;
-    // --model selects muse-spark-*; --reasoning-effort is the effort dial;
-    // --disable-write approximates plan (no non-shell writes); --disable-approval
-    // keeps the sandbox (auto); --yolo drops approval+sandbox and trusts the
-    // workspace (skip). --json emits JSONL on stdout. Interactive resume is
-    // `muse resume <id>`; headless resume is `muse exec --session-id <id>` —
-    // see the muse resume branch in buildExecCommand.
     muse: {
         base: ['muse', 'exec'],
         promptFlag: 'positional',
@@ -704,20 +470,8 @@ export const AGENT_COMMANDS = {
         },
         jsonFlags: ['--json'],
         modelFlag: '--model',
-        // Flag form covers headless (`--session-id`). Interactive uses the
-        // `resume` subcommand — special-cased in buildExecCommand.
         resume: { flag: '--session-id' },
     },
-    // Warp Agent CLI (`warp`) — the interactive TUI. It has NO headless one-shot
-    // form: the documented flags are --api-key/--auto-approve/--resume <token>/
-    // --set-provider-api-key/--clear-provider-api-key/--version/--help — no
-    // -p/--prompt, no --model (model is the `/model` picker), no JSON output. So
-    // bare `warp` opens the TUI and the single `edit` mode maps to no flags
-    // (mirrors hermes); there are no jsonFlags/modelFlag to declare. No `resume`:
-    // `warp --resume <token>` reopens a SERVER-SIDE conversation by token, but
-    // warp is not session-tracked (absent from SESSION_AGENTS) so agents-cli has
-    // no local id to feed — declaring it would make nativeResume(warp) true
-    // against an unreachable path.
     warp: {
         base: ['warp'],
         promptFlag: 'positional',
@@ -726,11 +480,6 @@ export const AGENT_COMMANDS = {
         },
     },
 };
-/**
- * Whether `agent` has a native resume form (Tier 1). Derived solely from the
- * command template's `resume` field — the single source of truth. Agents that
- * return false resume via the universal Tier-2 `/continue` replay instead.
- */
 export function nativeResume(agent, version) {
     const resume = AGENT_COMMANDS[agent]?.resume;
     if (!resume)
@@ -739,41 +488,9 @@ export function nativeResume(agent, version) {
         return true;
     return !!version && compareVersions(installedReleaseFor(agent, version), resume.since) >= 0;
 }
-/**
- * Build the `-c` value that adds `dir` to codex's workspace-write writable
- * roots. Codex parses the value as TOML, so it's a single-element TOML array of
- * one quoted string. Used on codex resume forms, which reject `--add-dir` and
- * only accept `-c` config overrides.
- */
 export function codexWritableRootsConfig(dir) {
     return `sandbox_workspace_write.writable_roots=[${JSON.stringify(dir)}]`;
 }
-/**
- * Resolve the executable `buildExecCommand` will put in `cmd[0]`, or null when
- * that resolution finds nothing on disk.
- *
- * This is an EXISTENCE probe, not an "is it managed by us" check. A harness the
- * user installed themselves (Homebrew, a vendor `curl | sh`, a distro package)
- * has no version home at all, and running it is a supported state — so with no
- * version pinned we answer with a PATH lookup of the bare launch command, the
- * same thing `spawnAgent` would resolve.
- *
- * `findInPath` deliberately excludes our own shims dir, because a shim is a
- * dispatcher rather than an install. That exclusion alone is too strong here:
- * the shim DOES launch whenever agents-cli owns at least one version of the
- * agent — it resolves the version itself, and when no default is pinned it
- * prints its own accurate `no default set … agents use <agent> <version>`
- * guidance. Pre-empting that with "not installed" would name the wrong fix
- * (`agents add`) for a machine that already has the harness. So the shim counts
- * only when a managed version exists; with zero managed versions it is the dead
- * end this probe was written to catch (RUSH-2339).
- *
- * The version-pinned branch mirrors buildExecCommand exactly: versioned shim
- * first, then the version home's real binary. It deliberately does NOT fall back
- * to PATH — with a version pinned, buildExecCommand spawns the literal
- * `<cli>@<version>`, which is not on PATH, so a PATH hit here would be a lie
- * that still exits 127.
- */
 export function resolveLaunchBinary(agent, version) {
     const command = AGENT_COMMANDS[agent].base[0];
     if (version) {
@@ -791,19 +508,12 @@ export function resolveLaunchBinary(agent, version) {
         return native;
     if (listInstalledVersions(agent).length === 0)
         return null;
-    // Re-scan PATH accepting the shim: point findInPath's exclusion at a path that
-    // matches nothing, so the real shims dir participates like any other PATH entry.
     return findInPath(command, { shimsDir: path.join(getShimsDir(), '.no-such-dir') });
 }
-/** Assemble the full CLI argument array for an agent invocation. */
 export function buildExecCommand(options) {
     const template = AGENT_COMMANDS[options.agent];
     const cmd = [...template.base];
     const interactive = resolveInteractive(options);
-    // For Codex, Droid, and Muse, 'exec' is the headless subcommand; for OpenCode,
-    // 'run' is. Drop it for interactive mode so we launch the TUI (`codex` /
-    // `droid` / `muse` / `opencode`) instead of the one-shot headless subcommand
-    // ('codex exec' / 'droid exec' / 'muse exec' / 'opencode run').
     if (interactive) {
         if ((options.agent === 'codex' || options.agent === 'droid' || options.agent === 'muse') &&
             cmd[1] === 'exec') {
@@ -813,16 +523,6 @@ export function buildExecCommand(options) {
             cmd.splice(1, 1);
         }
     }
-    // Native resume with a `{ subcommand }` shape (codex) appends the resume verb
-    // to the base: `codex exec` -> `codex exec resume` (headless) and, after the
-    // interactive drop above, `codex` -> `codex resume` (TUI). The session id is
-    // pushed later as the first positional (before any prompt). `{ flag }` agents
-    // (claude) need no base change — the flag is appended with the id below.
-    //
-    // Muse interactive resume is also a subcommand (`muse resume <id>`), but the
-    // session id MUST sit immediately after the verb — mode/model flags come
-    // after. So for interactive muse we push both `resume` and the id here, and
-    // skip the later generic resume flag path.
     const resumeSpec = options.resume ? template.resume : undefined;
     let museInteractiveResumeDone = false;
     if (options.agent === 'muse' && options.resume && interactive && options.sessionId) {
@@ -832,17 +532,6 @@ export function buildExecCommand(options) {
     else if (resumeSpec && 'subcommand' in resumeSpec) {
         cmd.push(resumeSpec.subcommand);
     }
-    // Use versioned alias if a specific version was requested (e.g., claude@2.1.98).
-    // Resolve to the absolute path of the shim so spawn doesn't depend on PATH —
-    // on Linux installs where the shims dir isn't on PATH, spawning the bare
-    // versioned name fails with ENOENT even though `agents view` shows the agent.
-    //
-    // On Windows the alias is materialized as a `.cmd` only (see
-    // createVersionedAlias — a bash alias next to it would shadow the `.cmd` in
-    // cmd.exe/PowerShell name resolution); the extensionless existsSync branch
-    // below still matches a legacy install's bash alias. When no shim exists on
-    // disk we fall back to the bare versioned name, which spawnAgent() resolves
-    // via PATH (+ PATHEXT/shell on Windows).
     if (options.version && cmd.length > 0) {
         const versionedName = `${cmd[0]}@${options.version}`;
         const absPath = path.join(getShimsDir(), versionedName);
@@ -853,23 +542,10 @@ export function buildExecCommand(options) {
             cmd[0] = absPath;
         }
         else {
-            // No versioned shim on disk. Prefer the version's REAL launch binary
-            // (node_modules/.bin/<cli>) over the bare `<cli>@<version>` name — that
-            // literal is not on PATH and spawns as ENOENT (the `kimi@0.19.2` failure).
-            // Fall back to the literal only if the binary is absent (the run path's
-            // ensureAgentRunnable normally repairs/creates the alias before we reach here).
             const realBinary = options.agent ? getBinaryPath(options.agent, options.version) : undefined;
             cmd[0] = realBinary && fs.existsSync(realBinary) ? realBinary : versionedName;
         }
     }
-    // Resolve the model up front so the reasoning-flag block can honor a cost tier
-    // that maps to reasoning effort on a single-model harness (e.g. Grok, where the
-    // tier IS the effort dial). `modelVersion` is null when no version resolves;
-    // `tierModel` is the concrete model a tier resolved to (null => drop the flag).
-    // Prefer the user's explicit --model. Codex falls back to ~/.codex/config.toml
-    // (per-version CODEX_HOME may not carry that setting). OpenCode has no model
-    // env var — a custom-harness pin lives in OPENCODE_MODEL and must become
-    // `--model` here, or the host silently uses its configured default (PHNX-2577).
     const effectiveModel = options.model
         ?? (options.agent === 'codex' ? readCodexConfiguredModel() : undefined)
         ?? (options.agent === 'opencode' ? options.env?.OPENCODE_MODEL : undefined);
@@ -879,41 +555,23 @@ export function buildExecCommand(options) {
     const tierResolved = effectiveModel && modelVersion && isTierToken(effectiveModel)
         ? resolveTier(options.agent, modelVersion, effectiveModel)
         : null;
-    // An explicit --effort wins; otherwise a single-model tier's effort applies.
     const effortLevel = options.effort !== 'auto' ? options.effort : (tierResolved?.effort ?? options.effort);
-    // Add reasoning effort flags (before mode flags for codex -c positioning)
-    // For codex, -c must come before 'exec' subcommand, so we insert at position 1
     if (effortLevel !== 'auto') {
         const reasoningFlags = buildReasoningFlags(options.agent, effortLevel);
         if (reasoningFlags.length > 0) {
             if (options.agent === 'codex') {
-                // Insert after 'codex' (or 'codex@version') but before 'exec'
                 cmd.splice(1, 0, ...reasoningFlags);
             }
             else {
-                // For other agents, append after base
                 cmd.push(...reasoningFlags);
             }
         }
     }
-    // Resolve the requested mode against the agent's capability table.
-    // - `auto` on an agent without auto support → silently degrades to `edit`
-    // - `plan` on an agent without a read-only mode → degrades to modes[0]
-    // - headless `plan` on an agent with headlessPlan:false (kimi, grok) →
-    //   degrades to `auto` with a stderr warning (see resolveHeadlessMode)
-    // - `skip` on an unsupported agent → throws a clear error
-    // After resolution, the chosen mode is guaranteed to be in template.modeFlags.
     const resolvedMode = resolveHeadlessMode(options.agent, normalizeMode(options.mode), interactive, options.modeWarningContext, options.modeWarningState);
     const modeFlags = template.modeFlags[resolvedMode];
     if (!modeFlags) {
-        // Defense in depth: would only fire if AGENTS.capabilities.modes and
-        // AGENT_COMMANDS.modeFlags drifted apart. Tests assert they agree.
         throw new Error(`Internal error: ${options.agent} declares '${resolvedMode}' in capabilities.modes but has no entry in AGENT_COMMANDS.modeFlags.${resolvedMode}.`);
     }
-    // Launch-arg quirks (the harness axis of Move 3): cursor's additive `--trust`
-    // and the codex/kimi mode-flag overrides move to the harness adapter, so the
-    // per-agent name-chain collapses to one dispatch. The generic resume-subcommand
-    // and modeFlags paths stay here — they are not per-harness.
     const launchAdapter = resolveHarnessAdapter(options.agent);
     const launchArgsCtx = {
         resolvedMode,
@@ -931,41 +589,21 @@ export function buildExecCommand(options) {
     }
     else if (resumeSpec && 'subcommand' in resumeSpec) {
         if (resolvedMode === 'skip') {
-            // skip = yolo on resume too; both `codex resume` (TUI) and
-            // `codex exec resume` accept the bypass flag.
             cmd.push('--dangerously-bypass-approvals-and-sandbox');
         }
         else if (interactive) {
             cmd.push(...modeFlags);
         }
         else {
-            // `codex exec resume` rejects `--sandbox <mode>` (verified against
-            // `codex exec resume --help` on 0.142.5), but takes -c config overrides —
-            // map the mode through sandbox_mode so a non-skip resume never gets the
-            // approval/sandbox bypass.
             cmd.push(...modeFlags);
         }
     }
     else {
         cmd.push(...modeFlags);
     }
-    // Add print/headless flags whenever the run RESOLVED headless -- gate on the
-    // resolved state (`!interactive`), not the raw `--headless` flag. Headless is
-    // inferred from prompt presence (resolveInteractive), and `--headless` defaults
-    // to `false` at the CLI layer, so gating on `options.headless` skipped these
-    // flags for a bare `agents run <agent> "prompt"`. For antigravity that meant
-    // `agy <prompt>` with no `--print`, launching the TUI and dying on `/dev/tty`
-    // in any non-terminal shell. `!interactive` is true for both an explicit
-    // `--headless` and a prompt-inferred headless run; an interactive run (no
-    // prompt, or `--interactive`) still skips them so the CLI opens its REPL.
     if (!interactive && template.printFlags) {
         cmd.push(...template.printFlags);
     }
-    // Resume vs. create. With `resume`, emit the agent's NATIVE resume reference:
-    // `{ flag }` agents append `<flag> <id>` (claude `--resume <id>`); `{ subcommand }`
-    // agents (codex) already pushed the verb above, so the id is the first
-    // positional here — placed before the prompt positional appended later. Without
-    // `resume`, the legacy claude-only `--session-id` CREATES a session with that id.
     if (options.resume && options.sessionId && resumeSpec && !museInteractiveResumeDone) {
         if ('flag' in resumeSpec) {
             const flag = interactive
@@ -980,14 +618,8 @@ export function buildExecCommand(options) {
     else if (options.sessionId && options.agent === 'claude') {
         cmd.push('--session-id', options.sessionId);
     }
-    // Add model. `effectiveModel` already preferred --model, then Codex's
-    // configured default, then an OpenCode custom-harness pin (OPENCODE_MODEL).
     if (effectiveModel && template.modelFlag) {
         if (tierResolved) {
-            // Cost tier (cheap|default|best|ultra) -> a concrete model this harness+
-            // version actually ships. Covers `agents run` and `agents teams` (both
-            // funnel here). A null model means nothing resolved -> drop the flag and
-            // let the harness pick its default.
             if (tierResolved.model) {
                 cmd.push(template.modelFlag, tierResolved.model);
                 if (tierResolved.note)
@@ -1008,35 +640,22 @@ export function buildExecCommand(options) {
             cmd.push(template.modelFlag, effectiveModel);
         }
         else {
-            // Tier token but no version resolved -> forwarding the literal "best"/etc.
-            // would be rejected by the CLI, so drop the flag (harness default).
             process.stderr.write(`[agents] cannot resolve tier "${effectiveModel}" without a version; using harness default\n`);
         }
     }
-    // Add JSON output flags if requested
     if (options.json && template.jsonFlags) {
         cmd.push(...template.jsonFlags);
     }
-    // Add verbose flag independently of JSON
     if (options.verbose && template.verboseFlag) {
-        // Avoid duplicate if jsonFlags already included --verbose
         if (!(options.json && template.jsonFlags?.includes(template.verboseFlag))) {
             cmd.push(template.verboseFlag);
         }
     }
-    // Add prompt when provided. In pure interactive mode (no prompt) we skip this
-    // so the CLI launches its TUI. When --interactive is passed alongside a prompt
-    // we still forward the prompt so the agent receives it as the first message.
     if (options.prompt !== undefined) {
         if (interactive && options.agent === 'opencode') {
-            // The OpenCode TUI takes an initial prompt via --prompt; a bare positional
-            // on the default command is parsed as a project path, not a message.
             cmd.push('--prompt', options.prompt);
         }
         else if (interactive && options.agent === 'claude') {
-            // Claude's -p is --print, not a prompt-value flag. In an interactive run
-            // the initial prompt is positional; emitting `-p /continue <id>` turns a
-            // focus recovery into a one-shot print process that immediately exits.
             cmd.push(options.prompt);
         }
         else if (template.promptFlag === 'positional') {
@@ -1046,45 +665,9 @@ export function buildExecCommand(options) {
             cmd.push(template.promptFlag, options.prompt);
         }
     }
-    // Project / --add-dir grants. Codex folds them into the named edit profile
-    // above (workspace_roots); resume rejects the native --add-dir flag.
-    // Everything else is strategy-driven in applyAddDirs:
-    //   native-flag  — claude, kimi, cursor (`--add-dir`)
-    //   grok-sandbox — rules + project sandbox profile when sandboxed
-    //   none         — ignored (no multi-root surface)
-    //
-    // `~` is expanded in normalizeAddDirs (via expandLocalHome), because no shell
-    // does it for us: a forwarded grant crosses the SSH boundary single-quoted
-    // (`shellQuote` in ssh-exec.ts), so the remote login shell leaves `~/…`
-    // literal and the harness resolves it as a directory actually named `~`.
-    // Expanding on the side that runs the harness is what lets one home-relative
-    // grant re-root per machine.
     applyAddDirs(options.agent, cmd, options.addDirs, {
         cwd: options.cwd ?? process.cwd(),
     });
-    // Claude-specific: workflow capability scoping. WORKFLOW.md frontmatter
-    // `tools:` / `mcpServers:` is translated to the headless flags that ACTUALLY
-    // restrict the run (verified against `claude --help` on the installed CLI):
-    //
-    //   tools:       -> `--tools <names...>` — restricts the AVAILABLE built-in
-    //                   tool set. This is the security boundary: tools NOT named
-    //                   here (e.g. Write, Bash, Edit) are unavailable for the whole
-    //                   run. `--allowedTools` would only auto-approve without
-    //                   restricting, so it is the WRONG flag for sandboxing.
-    //                   We also emit `--allowedTools <names...>` for the same set so
-    //                   the permitted tools don't prompt in headless `-p` mode.
-    //   mcpServers:  -> `--mcp-config <path>` PLUS `--strict-mcp-config`. The
-    //                   config flag alone ADDS servers to the existing set; only
-    //                   `--strict-mcp-config` makes the run use *only* the named
-    //                   servers, which is what scoping means.
-    //
-    // The command layer gates this behind the `allowlist` capability and assembles
-    // the mcp-config file; buildExecCommand stays a pure string-builder.
-    //
-    // `<tools...>` is variadic. Emit the names as separate argv tokens. The flags
-    // here are appended AFTER the positional prompt (added above), so the variadic
-    // never swallows the prompt; the trailing `--allowedTools` / `--strict-mcp-config`
-    // tokens also terminate the `--tools` variadic cleanly.
     if (options.agent === 'claude') {
         if (options.toolsRestrict && options.toolsRestrict.length > 0) {
             cmd.push('--tools', ...options.toolsRestrict);
@@ -1095,52 +678,25 @@ export function buildExecCommand(options) {
             cmd.push('--strict-mcp-config');
         }
     }
-    // Forward arbitrary native flags supplied after `--` verbatim. Appended last
-    // so they cannot be misinterpreted as values for earlier flags or as the prompt.
     if (options.passthroughArgs && options.passthroughArgs.length > 0) {
         cmd.push(...options.passthroughArgs);
     }
     return cmd;
 }
-/** Spawn an agent and return its exit code. Convenience wrapper over spawnAgent. */
 export async function execAgent(options) {
     const { exitCode } = await spawnAgent(options);
     return exitCode;
 }
-/**
- * Resolve how to spawn a shim target for a platform. Pure — testable on any host.
- *
- * POSIX always execs the binary directly (no shell). On Windows a bare
- * (non-absolute) name or a `.cmd` companion goes through the shell so cmd.exe
- * resolves it via PATHEXT — the common, `.cmd`-present path; an absolute `.cmd`
- * or extensionless path is exec'd through the shell / directly. npm always ships
- * a `<cmd>.cmd` companion on Windows, so the runnable target `execShimPassthrough`
- * hands us is the `.cmd` (never a bare `.ps1`).
- */
 export function resolveShimSpawn(platform, binary, extraArgs) {
     if (platform === 'win32') {
-        // Use win32 path semantics regardless of the host running this (the platform
-        // is the parameter, not process.platform) so `C:\...` reads as absolute.
         const useShell = !path.win32.isAbsolute(binary) || binary.endsWith('.cmd');
         if (useShell) {
-            // DEP0190-safe: hand cmd.exe ONE fully-quoted command line with an EMPTY
-            // args array, so Node never concatenates `extraArgs` (which carry the
-            // user's raw prompt/flags) into the shell line unescaped — that concat is
-            // both the deprecation and a command-injection surface.
             return { command: composeWin32CommandLine(binary, extraArgs), args: [], shell: true };
         }
         return { command: binary, args: extraArgs, shell: false };
     }
     return { command: binary, args: extraArgs, shell: false };
 }
-/**
- * Transparent passthrough exec for generated shims — the node-side delegate that
- * Windows `.cmd` shims call. Resolves the active version (explicit pin, else
- * project/default) and execs the real binary with the user's RAW args and the
- * per-version env isolation, WITHOUT injecting mode/model/reasoning flags. This
- * mirrors what the POSIX bash shim does inline (`exec $BINARY $launchArgs "$@"`),
- * keeping version resolution in one place instead of reimplementing it in batch.
- */
 export async function execShimPassthrough(agent, rawArgs, cwd, pinnedVersion) {
     const version = pinnedVersion ?? resolveVersion(agent, cwd) ?? undefined;
     if (!version || !isVersionInstalled(agent, version))
@@ -1155,50 +711,20 @@ async function execShimPassthroughLeased(agent, rawArgs, cwd, pinnedVersion) {
     }
     let binary = getBinaryPath(agent, version);
     if (process.platform === 'win32') {
-        // npm ships <cmd>.cmd alongside the bare script on Windows; that's the runnable form.
         const cmdPath = binary + '.cmd';
         if (fs.existsSync(cmdPath))
             binary = cmdPath;
     }
-    // Match the POSIX shim: direct Codex launches default to the safe writable
-    // profile, while later user arguments can still override native settings.
     const launchArgs = agent === 'codex'
         ? ['-c', 'check_for_update_on_startup=false', ...codexPolicyArgs('edit', codexEditWritableRoots(cwd))]
         : [];
-    // Mint a launch id and export it as AGENT_LAUNCH_ID so the agent's SessionStart
-    // hook records the same id — the join key that maps this launch to its exact
-    // session even though the recorded pid here is the cmd.exe wrapper (Windows) or
-    // a shell, while the hook runs under the agent descendant. This is the primary
-    // attribution path on Windows (no lsof), so the launchId join matters most here.
     const launchId = randomUUID();
-    // mode/effort are required by ExecOptions but do not affect the env buildExecEnv
-    // derives; pass the agent's default to satisfy the type. Passing no prompt makes
-    // this resolve INTERACTIVE, so the launch authenticates from the per-version
-    // login rather than the headless `auth` setup-token (EXEC-2a) — right for the
-    // common case, someone invoking the harness binary directly. Known limit: we do
-    // not parse `rawArgs`, so a `-p "task"` passthrough is headless in fact and
-    // interactive by this classification, and loses the token. Windows-only in
-    // practice (POSIX uses the bash shim, which execs the binary and never reaches
-    // buildExecEnv — `installations/shims.ts` generateShimScript).
     const env = buildExecEnv({ agent, version, cwd, mode: defaultModeFor(agent), effort: 'auto', env: { AGENT_LAUNCH_ID: launchId } });
     ensureVendorHomeDir(agent, getVersionHomePath(agent, version));
     const { command, args, shell } = resolveShimSpawn(process.platform, binary, [...launchArgs, ...rawArgs]);
-    // Pre-launch marker for the SECOND live launch path: the Windows generated
-    // `.cmd` shim delegates here and spawns the harness directly, so without this
-    // a pinned, logged-out version launched via the shim would be invisible —
-    // exactly the blind spot this event closes. Best-effort; re-derives the
-    // signed-in verdict from the pinned version home (no rotated pick here).
     await emitRunLaunch({ agent, version, resolvedVia: 'shim' });
     return new Promise((resolve) => {
-        // Register listeners in the same synchronous turn as spawn: awaiting a lock
-        // release after spawn can miss a fast child's exit/error event.
         const child = spawn(command, args, { cwd, stdio: 'inherit', env, shell });
-        // Record the launch so `ag sessions --active` can attribute the agent
-        // process to its cwd (and exact session when the caller passed
-        // --session-id). Vital on Windows, where there is no lsof to recover a
-        // foreign process's cwd. On the shell path this pid is the cmd.exe
-        // wrapper, not the agent binary — the active scan resolves that by
-        // walking the candidate's ancestors (readAncestorSessionEntry).
         if (child.pid) {
             const passthroughSessionId = extractSessionIdArg(rawArgs);
             writePidSessionEntry({
@@ -1212,8 +738,6 @@ async function execShimPassthroughLeased(agent, rawArgs, cwd, pinnedVersion) {
                 terminalId: launchIdentityEnv().AGENT_TERMINAL_ID,
                 startedAtMs: Date.now(),
             });
-            // Durable sessionId -> actor record (RUSH-2019) so the scanner can attribute
-            // this session to a person after the pid dies. Best-effort; no-ops without id.
             if (passthroughSessionId) {
                 writeSessionActorRecord({
                     sessionId: passthroughSessionId,
@@ -1231,37 +755,9 @@ async function execShimPassthroughLeased(agent, rawArgs, cwd, pinnedVersion) {
         });
     });
 }
-/**
- * Whether a dead pane's failure should be recapped to stderr (RUSH-2185 / EXEC-23a).
- *
- * For headless runs only a nonzero exit is a failure worth surfacing — a
- * clean 0 means the agent finished the task before we could attach.
- * For interactive runs ANY exit (including 0) is a failure: an instant clean
- * exit means the harness has no bare REPL and the user would see only a mute
- * `[detached]` with no explanation.
- */
 export function shouldRecapDeadPane(status, interactive) {
     return (status ?? 0) !== 0 || interactive;
 }
-/**
- * The exit code a tmux-wrapped run resolves with (RUSH-2185 / EXEC-23b).
- *
- * Three inputs, one rule: report success ONLY for an outcome tmux actually told
- * us about. A clean user detach (`knownAlive`) is 0; a dead pane reports the
- * status tmux read off it; everything else — pane unreadable because the server
- * or session went away, or dead with no status — is UNKNOWN and resolves to
- * {@link UNKNOWN_OUTCOME_EXIT_CODE}, never 0.
- *
- * Why this is not `status ?? 0`: an interactive run whose tmux server died mid-
- * work landed on exactly those unknown branches and returned 0, so `agents run`
- * printed a failure banner while handing its caller a success code. The same
- * "1 if unknown" rule already governs the `--device` follow path
- * (`docs/specifications.md` §Agent execution, exit-code table).
- *
- * @param pane       What `paneExitStatus` read back for the agent pane.
- * @param knownAlive Positive proof the pane is still alive (see
- *                   {@link isPaneKnownAliveFromQueryResult}) — a clean detach.
- */
 export function tmuxRunExitCode(pane, knownAlive) {
     if (knownAlive)
         return 0;
@@ -1269,70 +765,28 @@ export function tmuxRunExitCode(pane, knownAlive) {
         return pane.status;
     return UNKNOWN_OUTCOME_EXIT_CODE;
 }
-/**
- * True only when a `display-message #{pane_dead}` tmux query explicitly returned
- * "0" (pane alive). Used to distinguish "pane alive" from "query failed" in
- * situations where `paneExitStatus` conservatively returns `{dead: false}` for
- * both (RUSH-2185 / EXEC-23a / F3).
- *
- * @param code   The exit code of the `tmux display-message` command.
- * @param stdout Its stdout (expected to be "0" when the pane is alive).
- */
 export function isPaneKnownAliveFromQueryResult(code, stdout) {
     return code === 0 && stdout.trim() === '0';
 }
-/**
- * Tmux is opt-in except when a TTY-less remote launch would otherwise have no
- * interface. Explicit per-run opt-outs always win.
- */
 export function resolveTmuxWrap(ctx) {
-    // A headless `-p` run has no TTY to attach, Windows has no tmux path, and
-    // nesting tmux-in-tmux is pointless.
     if (!ctx.interactive)
         return { kind: 'bare' };
     if (ctx.platform === 'win32')
         return { kind: 'bare' };
     if (ctx.inTmux)
         return { kind: 'bare' };
-    // Explicit opt-outs win over every other rule: `--raw` exists precisely to
-    // get the unwrapped process.
     if (ctx.raw)
         return { kind: 'bare' };
     if (ctx.noTmuxEnv)
         return { kind: 'bare' };
-    // Local interactive with no TTY cannot attach. Wrapping anyway creates a
-    // detached pane, attach returns immediately, and resolveAfterAttach treats
-    // the still-alive pane as Ctrl-b d — the session-tracker test leak.
     if (!ctx.hasTty && !ctx.remoteDispatch)
         return { kind: 'bare' };
-    // tmux.enabled gates the wrap for local AND followed remote runs. The one
-    // exception: a followed remote run whose launcher has no TTY (CI, scripts)
-    // gives the peer nothing to attach to — the detached pane is its only
-    // interface, infrastructure rather than ergonomics.
     if (!ctx.configEnabled && !(ctx.remoteDispatch && !ctx.hasTty))
         return { kind: 'bare' };
-    // Fail loud rather than launch a remote agent that a blink would kill: the
-    // caller refuses the run instead of starting work that cannot be recovered.
     if (!ctx.tmuxAvailable)
         return ctx.remoteDispatch ? { kind: 'undurable' } : { kind: 'bare' };
     return { kind: 'wrap' };
 }
-/**
- * True when `options.sessionId` is an id the HARNESS actually received, and so a
- * real, resumable handle — rather than one the launcher generated for its own
- * bookkeeping and the agent never saw.
- *
- * Mirrors exactly the two branches in buildExecCommand that put the id on the
- * command line: a native resume (any harness with a `resume` spec) and claude's
- * create-with-`--session-id`. Everything else — `agents run codex --session-id X`
- * without `--resume`, or a fresh non-claude launch whose real id only shows up
- * later via the SessionStart hook — leaves the agent with an id of its own
- * choosing, so `options.sessionId` must not be published as if it were that id.
- *
- * Keep in lockstep with buildExecCommand's resume/create branches: a harness
- * that gains a forced-session-id flag must be reflected here in the SAME change,
- * or this reports a genuine id as fabricated.
- */
 export function isHarnessKnownSessionId(agent, sessionId, resume) {
     if (!sessionId)
         return false;
@@ -1340,27 +794,12 @@ export function isHarnessKnownSessionId(agent, sessionId, resume) {
         return true;
     return agent === 'claude';
 }
-/**
- * Build the pane command without inheriting stale tmux-server env. Redacted
- * copies keep secret values out of persisted SessionMeta commands.
- */
+// Resolved env values never enter tmux argv/metadata; source an exclusive 0600 file, unlink it, and abort if sourcing fails.
 export function buildTmuxAgentCommand(executable, args, env, opts = {}) {
     const agentCmd = [executable, ...args].map(shellQuote).join(' ');
     const absentIdentity = LAUNCH_IDENTITY_KEYS.filter(key => env[key] === undefined);
-    // envFile: source the values instead of inlining them, so no VALUE ever lands
-    // in the pane's argv. `exec env K=V …` put every resolved secret into the
-    // process table, readable by any process of this user — on one fleet box six
-    // live processes carried the secrets-store master passphrase, which decrypts
-    // every file-backed bundle including the Claude OAuth tokens (RUSH-2100).
-    // `set -a` exports what the file assigns; the file is unlinked before `exec`,
-    // so it exists only for the sourcing itself. A missing file aborts the pane
-    // rather than silently launching with a half-built env.
     if (opts.envFile) {
         const f = shellQuote(opts.envFile);
-        // Remove the file whether or not sourcing succeeds — a bare `. f || exit 1`
-        // strands the plaintext env (incl. the secrets-store master passphrase) on
-        // disk on any source failure, worse than the argv leak this replaces
-        // (RUSH-2100). Capture the source rc, unlink, then honor it.
         return `${absentIdentity.length ? `unset ${absentIdentity.join(' ')}; ` : ''}set -a; . ${f}; __agents_rc=$?; set +a; rm -f ${f}; [ "$__agents_rc" -eq 0 ] || exit 1; exec ${agentCmd}`;
     }
     const envPrefix = Object.entries(env)
@@ -1369,16 +808,6 @@ export function buildTmuxAgentCommand(executable, args, env, opts = {}) {
         .join(' ');
     return `exec env ${absentIdentity.map(key => `-u ${key}`).join(' ')} ${envPrefix} ${agentCmd}`;
 }
-/**
- * Serialize the pane env to a shell-sourceable file, created 0600 and exclusively
- * (`wx`) so it can never adopt a pre-existing file's mode or content.
- *
- * EVERY key goes in the file, not a curated "secret-bearing" subset: a denylist
- * has to be updated for each new credential and is wrong the moment someone
- * forgets, whereas routing all of it through the file makes the guarantee hold by
- * construction. Keys are filtered to valid shell identifiers for the same reason
- * `env` needed it — an exported function (`BASH_FUNC_x%%`) is not assignable.
- */
 export function writeTmuxEnvFile(env, filePath) {
     const body = Object.entries(env)
         .filter(([k, v]) => v !== undefined && EXEC_ENV_KEY_PATTERN.test(k))
@@ -1393,13 +822,6 @@ export function writeTmuxEnvFile(env, filePath) {
         fs.closeSync(fd);
     }
 }
-/**
- * Trim a raw `tmux capture-pane` dump to its last `maxLines` non-empty lines
- * (right-stripping each). Used by runInTmux to recap a fast-failed agent's
- * output into the caller's shell so a launch crash (e.g. a gutted install that
- * dies with ENOENT the instant it spawns) isn't swallowed by the bare
- * `[detached]` the pane-died hook otherwise leaves behind.
- */
 export function formatPaneTail(raw, maxLines = 30) {
     return raw
         .split('\n')
@@ -1408,28 +830,6 @@ export function formatPaneTail(raw, maxLines = 30) {
         .slice(-maxLines)
         .join('\n');
 }
-/**
- * Run an interactive agent inside a detached tmux session on the shared socket,
- * attach the current TTY, and propagate the wrapped agent's exit code.
- *
- * Lifecycle:
- *   1. createSession() launches `sh -c 'exec env … agent'` detached, remain-on-exit
- *      on (global), and returns the pane id.
- *   2. A per-session `pane-died` hook tears the session down the instant the AGENT
- *      pane exits: with a client attached it `detach-client`s so attach returns
- *      instead of parking on a dead pane (then resolveAfterAttach reads the status
- *      and kills); with no client attached it `kill-session`s outright, so a
- *      wrapped agent that exits unattended can't leave a dead husk lingering on the
- *      socket. The hook is guarded on `#{hook_pane}` so it fires ONLY for the agent
- *      pane — user-created splits (Ctrl-b " / %) that the user exits are closed in
- *      place (`kill-pane`) instead of tearing down the whole client, so exiting one
- *      split leaves the agent running full-window rather than kicking you out.
- *   3. We record the agent pane's pid → session mapping (WITH the tmux pane) so the
- *      headless active-scan attributes it, then attach the TTY (blocking).
- *   4. On return: if the pane is dead the agent exited — read its status, tear the
- *      session down, return that code. If the pane is still alive the user detached
- *      (Ctrl-b d) — return 0 and LEAVE the session for `agents focus` to re-attach.
- */
 async function runInTmux(options, executable, args) {
     const { createSession, killSession, paneExitStatus, prepareSessionForResume, setSessionHook, slugifyName, agentPaneDiedHook, markSessionHookSchema } = await import('./tmux/session.js');
     const { getDefaultSocketPath } = await import('./tmux/paths.js');
@@ -1440,13 +840,6 @@ async function runInTmux(options, executable, args) {
     const name = slugifyName(`ag-${options.agent}-${idSeed}`);
     const RED = '\x1b[31m', GRAY = '\x1b[90m', OFF = '\x1b[0m';
     const NO_TMUX_TIP = `${GRAY}  This run used the opt-in tmux wrap. Re-run with --no-tmux for a direct launch, or turn the wrap off: agents config set devices.${machineId()}.tmux off${OFF}\n\n`;
-    // Read a dead pane's scrollback. Must run BEFORE killSession — capture-pane
-    // needs the session still alive (remain-on-exit keeps the dead pane readable
-    // until we tear it down). Best-effort: a missing/gone pane just yields ''.
-    // Callers thread this into SpawnResult.stdout for a GENUINELY dead pane only
-    // (positive proof from paneExitStatus) — never for the "still alive, user
-    // detached" or "outcome unknown" paths below, so an interactive detach or an
-    // unresolved tmux race can never masquerade as refusal evidence.
     const capturePaneTail = async (pane) => {
         if (!pane)
             return '';
@@ -1458,10 +851,6 @@ async function runInTmux(options, executable, args) {
             return '';
         }
     };
-    // Recap a dead pane's tail into THIS shell's stderr. The pane-died hook
-    // detaches the client the instant the agent exits, so a fast failure (a
-    // gutted install that dies with ENOENT, a bad flag, a crash on startup) would
-    // otherwise leave only a bare `[detached]` with no clue why.
     const surfacePaneFailure = async (pane, status, headline, tail) => {
         if (!pane)
             return;
@@ -1473,10 +862,6 @@ async function runInTmux(options, executable, args) {
         }
         process.stderr.write(NO_TMUX_TIP);
     };
-    // F3 (RUSH-2185 / EXEC-23a): paneExitStatus returns {dead:false} for BOTH
-    // "pane is alive" and "tmux query failed (race / pane already gone)". Require
-    // POSITIVE proof before taking the keep-session path — a separate direct query
-    // that only returns true when tmux explicitly confirms pane_dead=0.
     const checkPaneKnownAlive = async (p) => {
         try {
             const r = await runTmux({ socket, args: ['display-message', '-pt', p, '-p', '#{pane_dead}'], throwOnError: false });
@@ -1486,13 +871,6 @@ async function runInTmux(options, executable, args) {
             return false;
         }
     };
-    /**
-     * Resolve what an attach client's return actually means, for EVERY path that
-     * attaches (the fresh wrapper below AND the resume-attach above). Asking tmux
-     * is the only way to tell "the user detached" from "the agent exited" from
-     * "the session went away underneath us", so an attach that skips this cannot
-     * do better than assume success — which is exactly the defect EXEC-23b fixes.
-     */
     let paneLaunchBinding;
     const bindCompletedPane = () => {
         recordCompletedLaunch(paneLaunchBinding);
@@ -1501,44 +879,18 @@ async function runInTmux(options, executable, args) {
         const after = pane ? await paneExitStatus(pane, socket) : { found: false, dead: false, status: undefined };
         if (after.dead) {
             bindCompletedPane();
-            // Positive proof of a genuinely completed pane (paneExitStatus confirmed
-            // dead) — capture its scrollback as refusal evidence for the caller
-            // (classifyClaudeRunRefusal etc.) BEFORE tearing the session down.
-            // Deliberately not done for the "alive" (detach) or "unknown" branches
-            // below: neither is a demonstrated completion, so neither may carry
-            // evidence a caller could mistake for a real refusal or success.
             const tail = await capturePaneTail(pane);
-            // Nonzero exit after attach → the agent crashed rather than the user
-            // detaching cleanly (a clean detach leaves the pane ALIVE, handled below).
-            // F2: for interactive runs, also recap a clean exit-0 — the harness exited
-            // without error but without starting a REPL, which is still a failure.
             if (shouldRecapDeadPane(after.status, resolveInteractive(options))) {
                 await surfacePaneFailure(pane, after.status, `${options.agent} exited`, tail);
             }
             await killSession(name, socket).catch(() => { });
-            // A dead pane whose status tmux never reported is UNKNOWN, not success —
-            // and surfacePaneFailure already printed `exit 1` for it, so the old
-            // `?? 0` made the message and the returned code disagree (EXEC-23b).
             return { exitCode: tmuxRunExitCode(after, false), stderr: '', stdout: tail };
         }
-        // after.dead===false, but that could be a stale/unreadable-pane result.
-        // Require positive proof before keeping the session as "user detached".
         if (pane && await checkPaneKnownAlive(pane)) {
-            // Confirmed alive: the user pressed Ctrl-b d; keep the session for `agents focus`.
             return { exitCode: tmuxRunExitCode(after, true), stderr: '', stdout: '' };
         }
-        // F4 (EXEC-23b): the outcome is UNKNOWN — tmux could not tell us whether the
-        // agent finished or was killed. MUST NOT be reported as success: a caller
-        // scripting `agents run` would count a run killed mid-work as a clean
-        // finish. Tear down so no orphan session is left, say so, and exit non-zero
-        // — the same "1 if unknown" rule the `--device` follow path already uses.
         await killSession(name, socket).catch(() => { });
-        // One computation feeds both the banner and the return value — printing a
-        // code the caller does not receive is the same defect in miniature.
         const exitCode = tmuxRunExitCode(after, false);
-        // Two distinct causes reach here, and the banner must not assert the wrong
-        // one: a pane we HAD (the session went away under it) versus a run whose
-        // pane id tmux never reported at creation, which had nothing to read from.
         const cause = pane
             ? 'The tmux session went away before its exit status could be read, so this run may have been killed mid-work.'
             : 'This run had no readable tmux pane, so its exit status could never be read.';
@@ -1546,49 +898,27 @@ async function runInTmux(options, executable, args) {
             `${GRAY}  ${cause}${OFF}\n` + NO_TMUX_TIP);
         return { exitCode, stderr: '', stdout: '' };
     };
-    // A native resume must not create a competing wrapper for a live session.
-    // A retained dead pane is reaped before the harness resumes normally.
     const resumePrep = options.resume ? await prepareSessionForResume(name, socket) : { decision: 'create' };
     if (resumePrep.decision === 'attach') {
         if (options.sessionId)
             writeSessionAliasRecord(options.sessionId, name);
         await attachTmux({ socket, args: ['attach-session', '-t', name] });
-        // EXEC-23b: a resume-attach is an attach like any other — it must ask tmux
-        // what happened rather than assume 0. Before this it returned a hardcoded
-        // success, so a resumed run whose server died under it reported a clean
-        // finish, the identical defect on the identical shape.
         return resolveAfterAttach(resumePrep.pane);
     }
-    // SessionStart learns some harness IDs only after launch. Carry the wrapper
-    // name into that hook so it can bind both identities durably.
     const execEnv = { ...buildExecEnv(options), AGENT_TMUX_SESSION_NAME: name };
-    // The pane sources its env from a 0600 file it unlinks before exec, so no
-    // resolved secret VALUE reaches the process table (RUSH-2100). SessionMeta.cmd
-    // keeps the value-redacted inline form — the human-readable record of what ran,
-    // which never carried real values anyway (RUSH-1758).
     const envFile = path.join(getRuntimeStateDir(), 'tmux-env', `${name}-${randomUUID().slice(0, 8)}.env`);
     writeTmuxEnvFile(execEnv, envFile);
     let cmd = buildTmuxAgentCommand(executable, args, execEnv, { envFile });
     const leaseVersion = options.version ?? resolveVersion(options.agent, cwd);
     if (leaseVersion && isVersionInstalled(options.agent, leaseVersion)) {
         const leaseCli = getCliLaunch(['__launch-lease', options.agent, leaseVersion], getAgentsBinPath());
-        // The pane outlives a detached launcher. Lease its own exec-replaced shell
-        // before launching, so detaching cannot open an unprotected launch gap.
         cmd = `${[leaseCli.command, ...leaseCli.args].map(shellQuote).join(' ')} "$$" || exit 1; ${cmd}`;
     }
     const metaCmd = buildTmuxAgentCommand(executable, args, execEnv, { redactEnvValues: true });
     const labels = { agent: options.agent };
-    // Only publish an id the harness actually received. createSession turns this
-    // label into the `@ag_session_id` tmux option that status bars read, and a
-    // launcher-internal id displayed there looks exactly like a resumable one
-    // while `ag focus <id>` rejects it.
     if (isHarnessKnownSessionId(options.agent, options.sessionId, options.resume)) {
         labels.sessionId = options.sessionId;
     }
-    // Only a launched pane sources-and-unlinks the env file. If createSession
-    // throws, the pane never runs, so the resolved secrets (incl. the master
-    // passphrase) would linger on disk — remove it on that failure path
-    // (RUSH-2100). On success the detached pane owns the unlink.
     let meta;
     try {
         meta = await createSession({ name, cmd, metaCmd, cwd, socket, source: 'cli', labels });
@@ -1597,34 +927,22 @@ async function runInTmux(options, executable, args) {
         try {
             fs.rmSync(envFile, { force: true });
         }
-        catch { /* best-effort */ }
+        catch { }
         throw err;
     }
     const pane = meta.pane;
     if (options.sessionId)
         writeSessionAliasRecord(options.sessionId, name);
     if (pane) {
-        // When the AGENT pane dies, detach the client (don't kill) so the session
-        // survives just long enough to read the dead pane's exit status below. The
-        // `#{hook_pane}` guard scopes this to the agent pane only: if the user splits
-        // the window and exits one of THEIR panes, the else-branch closes that split
-        // in place instead of detaching everyone (`run-shell -C` executes the
-        // targeted kill inside tmux's server command queue, avoiding a second
-        // client racing the same socket under load, #965). Without the guard,
-        // exiting any split kicked the user clean out of tmux.
         const hookInstalled = await setSessionHook(name, 'pane-died', agentPaneDiedHook(name, pane), socket);
-        // Stamp the schema marker only after tmux accepted the hook. A failed
-        // install stays unmarked so daemon reconciliation retries it later.
         if (hookInstalled)
             await markSessionHookSchema(name, socket);
-        // Record the agent's OS pid (the pane leaf, thanks to `exec`) WITH its tmux
-        // pane so the active-scan attributes it exactly and shows the %pane.
         let panePid = 0;
         try {
             const r = await runTmux({ socket, args: ['display-message', '-pt', pane, '-p', '#{pane_pid}'], throwOnError: false });
             panePid = parseInt(r.stdout.trim(), 10) || 0;
         }
-        catch { /* best-effort */ }
+        catch { }
         writePidSessionEntry({
             pid: panePid,
             agent: options.agent,
@@ -1633,10 +951,6 @@ async function runInTmux(options, executable, args) {
             cwd,
             actor: resolveActor().id,
             initiatedBy: resolveActor().kind,
-            // spawnAgent injected AGENT_LAUNCH_ID into options.env before delegating
-            // here; record the same id so the hook (running under the pane-leaf agent
-            // pid) reconciles by launchId. This pane's pid usually IS the agent pid,
-            // but the launchId join is robust even when it isn't.
             launchId: options.env?.AGENT_LAUNCH_ID,
             terminalId: launchIdentityEnv().AGENT_TERMINAL_ID,
             tmuxPane: pane,
@@ -1655,44 +969,20 @@ async function runInTmux(options, executable, args) {
             });
         }
     }
-    // The agent could exit before we attach (fast failure). Don't attach to an
-    // already-dead pane — surface its output + status directly and tear down.
     const before = pane ? await paneExitStatus(pane, socket) : { found: false, dead: false, status: undefined };
     if (before.dead) {
         bindCompletedPane();
-        // Positive proof of a genuinely completed pane — capture scrollback as
-        // refusal evidence before tearing the session down (see the matching
-        // comment in resolveAfterAttach).
         const tail = await capturePaneTail(pane);
-        // F2 (RUSH-2185 / EXEC-23a): for interactive runs, ALWAYS recap — a clean
-        // exit-0 before attach means the harness has no interactive REPL and the
-        // user would see only a bare `[detached]` with no clue why. For headless
-        // runs the old quiet behaviour stands: exit-0 is a successful quick run.
         if (shouldRecapDeadPane(before.status, resolveInteractive(options))) {
             await surfacePaneFailure(pane, before.status, `${options.agent} exited before it could start`, tail);
         }
         await killSession(name, socket).catch(() => { });
-        // A dead pane whose status tmux never reported is an UNKNOWN outcome, not a
-        // success — and the banner one line up already printed `exit 1` for it, so
-        // the old `?? 0` also made the message and the returned code disagree.
         return { exitCode: tmuxRunExitCode(before, false), stderr: '', stdout: tail };
     }
     await attachTmux({ socket, args: ['attach-session', '-t', name] });
     return resolveAfterAttach(pane);
 }
-/**
- * Print the run's resolved session id as a one-line stdout sentinel so a `--device`
- * launcher can relate the remote-created session back to itself (see the
- * `emitSessionId` option and hosts/session-marker.ts).
- *
- * For Claude the id was forced up front (`options.sessionId`, wired as
- * `--session-id`), so it's authoritative with no lookup. Every other agent coined
- * its OWN id, which its SessionStart hook recorded under this run's launchId — the
- * exact join key `agents sessions --active` uses — so we read it back from the hook
- * index by launchId (falling back to the child pid the hook may have recorded
- * under). Nothing to emit when the hook hasn't landed an id (hookless harness):
- * the launcher simply keeps the un-mapped task, never a fabricated id.
- */
+// Publish only a session id supplied by the harness or joined through the shared launch id.
 function emitResolvedSessionId(options, launchId, childPid) {
     let sessionId = options.sessionId;
     if (!sessionId) {
@@ -1704,29 +994,16 @@ function emitResolvedSessionId(options, launchId, childPid) {
             });
         }
         catch {
-            /* hook index unreadable — emit nothing rather than a guess */
         }
     }
     if (sessionId)
         process.stdout.write(sessionIdMarkerLine(sessionId));
 }
-/**
- * Build the `run.launch` event payload. Pure and exported so the signedIn ->
- * launchedLoggedOut mapping is unit-testable without spawning. Mirrors the
- * buildRotationDecisionEvent / emitRotationDecision split in rotate.ts.
- *
- * `launchedLoggedOut` is the headline flag — true ONLY when `signedIn` was
- * resolved to false (a launch into a logged-out version, the yosemite-m3 2.1.219
- * incident). An UNKNOWN verdict (`signedIn === null`) is never treated as
- * logged out.
- */
 export function buildRunLaunchPayload(input) {
     return {
         module: 'run',
         agent: input.agent,
         ...(input.harnessName ? { harnessName: input.harnessName } : {}),
-        // Omitted only when no version could be resolved at all — the typed `version`
-        // field can't carry null, and an absent version is honest.
         version: input.version,
         strategy: input.strategy ?? null,
         signedIn: input.signedIn,
@@ -1735,36 +1012,15 @@ export function buildRunLaunchPayload(input) {
         ...(input.resolvedVia ? { resolvedVia: input.resolvedVia } : {}),
     };
 }
-/**
- * Emit the pre-launch `run.launch` observability event just before the harness
- * child is spawned. Best-effort by construction — the whole point is that it can
- * NEVER break a launch, so every step (the signed-in probe, the emit itself) is
- * wrapped and a failure is swallowed. Mirrors the non-fatal pattern of
- * recordDispatchedRun and emitRotationDecision.
- *
- * The `signedIn` verdict is for the SPECIFIC launched version on THIS device, so
- * `launchedLoggedOut` catches a launch into a logged-out version that
- * `--device auto` readiness let through (the yosemite-m3 2.1.219 incident). It is
- * REUSED from `ctx.launchSignedIn` when the caller already computed it via the
- * identical gate (the rotated pick — no double fs read, no disagreement window),
- * and only otherwise re-derived via {@link isVersionLaunchableHere} (dynamically
- * imported so the spawn path takes on no static dependency on the accounting
- * layer).
- */
 async function emitRunLaunch(ctx) {
     try {
         let signedIn;
         let email;
         if (ctx.launchSignedIn !== undefined) {
-            // Caller already computed the verdict for this exact version via the same
-            // gate — reuse it verbatim.
             signedIn = ctx.launchSignedIn;
             email = ctx.launchEmail ?? null;
         }
         else {
-            // Pinned-default / shim paths: probe the version home now. Without a
-            // concrete version we cannot probe, so leave the verdict unknown (null)
-            // rather than guess.
             signedIn = null;
             email = null;
             if (ctx.version) {
@@ -1775,7 +1031,6 @@ async function emitRunLaunch(ctx) {
                     email = state.email;
                 }
                 catch {
-                    /* probe unavailable — record the launch without the signed-in verdict */
                 }
             }
         }
@@ -1790,7 +1045,6 @@ async function emitRunLaunch(ctx) {
         }));
     }
     catch {
-        /* observability must never break a launch */
     }
 }
 async function spawnAgent(options) {
@@ -1836,10 +1090,10 @@ async function spawnAgent(options) {
                     else if (!row.isApiErrorMessage && row.message?.model && content.trim())
                         clearClaudeModelRefusal(modelKey, row.message.model);
                 }
-                catch { /* Partial or non-message transcript rows provide no evidence. */ }
+                catch { }
             }
         }
-        catch { /* Transcript observation must not interrupt the harness. */ }
+        catch { }
     };
     const observer = transcript ? setInterval(observeTranscript, 2_000) : undefined;
     observer?.unref();
@@ -1865,19 +1119,10 @@ async function spawnAgent(options) {
 }
 async function spawnAgentLeased(options) {
     bootMark('spawn-agent:enter');
-    // Assign a known session id up front for agents that accept one, so the
-    // launcher can record an EXACT pid -> session mapping (see pid-registry) —
-    // otherwise the headless `ag sessions --active` path can only guess
-    // "newest .jsonl in the cwd" and collapses co-located agents onto one row.
-    // Claude: `--session-id <uuid>` CREATES the session with that id (wired in
-    // buildExecCommand). Skip on resume — the id is the one being resumed.
     if (options.agent === 'claude' && !options.resume && !options.sessionId) {
         options = { ...options, sessionId: randomUUID() };
     }
     ensureVendorHomeForSpawn(options);
-    // Record the run's --name against its session id (when both are known at
-    // launch) so `agents sessions <name>` resolves it. Best-effort; unnamed runs
-    // and agents whose id isn't known up front simply skip this.
     if (options.name && options.sessionId) {
         recordRunName({ sessionId: options.sessionId, name: options.name, agent: options.agent, cwd: options.cwd });
     }
@@ -1886,10 +1131,6 @@ async function spawnAgentLeased(options) {
     const timeoutMs = options.timeout ? parseTimeout(options.timeout) : undefined;
     const piped = !process.stdout.isTTY;
     const interactive = resolveInteractive(options);
-    // Fail loud before spawning a headless codex whose Linux sandbox can't start —
-    // otherwise it burns a turn and lands zero tools (PHNX-3285). Cheap gate first
-    // so the userns probe (one `unshare`) runs only for the exact case it applies to
-    // (codex + Linux + headless + a sandboxed mode), never for every spawn.
     if (options.agent === 'codex' && process.platform === 'linux' && !interactive) {
         const codexMode = options.mode ? normalizeMode(options.mode) : defaultModeFor(options.agent);
         if (codexMode !== 'skip') {
@@ -1907,18 +1148,9 @@ async function spawnAgentLeased(options) {
             }
         }
     }
-    // Fail loud before an INTERACTIVE claude run on a worker with no synced
-    // credential falls through to Claude Code's "Select login method" screen — an
-    // interactive OAuth on a headless box that never persists, the 10-minute
-    // re-login loop (PHNX-3502 sibling). A worker authenticates from the
-    // setup-token; when none resolves for the selected account, refuse with the
-    // real fix instead of the useless login prompt. Headless already fails loud
-    // (401), so the gate is interactive-only (the preflight enforces that).
+    // Headed Claude uses native OAuth only; workers require the selected slot's durable setup token and never open interactive login.
     if (options.agent === 'claude') {
         const { versionHome } = resolveExecConfigHome(options);
-        // A credential reaches the child if the worker setup-token resolves for the
-        // selected account OR the caller passed an explicit --env override
-        // (buildExecEnv merges options.env last, so it wins even the worker strip).
         const hasWorkerCredential = Boolean(options.env?.CLAUDE_CODE_OAUTH_TOKEN) ||
             (versionHome ? resolveClaudeSetupToken(versionHome) !== null : false);
         const loginTrap = claudeWorkerLoginTrapPreflight({
@@ -1932,34 +1164,12 @@ async function spawnAgentLeased(options) {
             process.stderr.write(`\x1b[31m${loginTrap}\x1b[0m\n`);
             return { exitCode: 1, stdout: '', stderr: loginTrap };
         }
-        // A credentialed run on a worker never needs Claude Code's first-run
-        // onboarding, and in a provider (setup-token) launch's shared version home
-        // nothing else completes it: the tab opened on the theme picker instead of
-        // the agent (yosemite-m1, 2026-09-28). A headed device keeps its own
-        // onboarding; the person at it answers it.
         if (hasWorkerCredential && versionHome && !isHeadedDeviceRole(selfConfiguredDeviceRole())) {
             seedClaudeWorkerHomeIdentity(versionHome);
         }
     }
-    // Budget live kill-switch (issue #346). For headless runs we incrementally
-    // parse stream-json usage off stdout, accumulate cost, and kill the child the
-    // moment a configured cap is crossed — exactly like the --timeout path, but
-    // resolving with a DISTINCT exit code so CI/headless can tell budget-kill from
-    // timeout. Spend is recorded to the shared ledger in the close handler. The
-    // watcher is dormant (and zero-cost) when no caps are configured.
     const cwd = options.cwd || process.cwd();
-    // Resolve the launch id once. It doubles as the budget watcher's run id AND is
-    // exported to the child as AGENT_LAUNCH_ID, so the agent's SessionStart hook
-    // records the SAME id in its own state file (terminals/sessions/<pid>.json).
-    // That id is the join key that reconciles this launch's pid-registry entry
-    // with the hook's authoritative session id even when the hook runs under a
-    // different pid (tmux pane leaf / cmd.exe wrapper) — see pid-registry.ts and
-    // session/hook-sessions.ts. ADOPT a launch id a `--device` launcher already
-    // forwarded (via `--env AGENT_LAUNCH_ID=…`) so ONE correlation key spans the
-    // SSH hop and the launcher can resolve this run's real session id for every
-    // agent, not just Claude (RUSH-2034); mint a fresh one for every local run.
-    // Injected into options.env so every downstream env build (the bare spawn
-    // below AND the tmux env prefix in runInTmux) carries it.
+    // One launch id joins SSH, tmux, hook, and tracker observations into the same run.
     const launchId = resolveLaunchId(options.env?.AGENT_LAUNCH_ID);
     const runId = launchId;
     options = { ...options, env: { ...options.env, AGENT_LAUNCH_ID: launchId } };
@@ -1968,9 +1178,6 @@ async function spawnAgentLeased(options) {
         agent: options.agent,
         version: options.version,
         cwd: options.cwd || process.cwd(),
-        // The mode that ran, not the one requested — `agents run` passes the
-        // requested mode so the resolver can warn, but telemetry must agree with
-        // the audit log. See RUSH-2106 for removing that ambiguity at the source.
         mode: resolveMode(options.agent, normalizeMode(options.mode)),
         model: options.model,
         interactive,
@@ -1979,11 +1186,6 @@ async function spawnAgentLeased(options) {
         command: executable,
         args: redactArgs(args.slice(0, 10)),
     });
-    // Interactive spawn-wrap: run the agent INSIDE a shared-socket tmux session
-    // (then attach this TTY) so it gets a unique, addressable %pane. Opt-in via
-    // this device's tmux.enabled, local and remote alike (PHNX-3316); a followed
-    // remote run left bare relies on reconnect-and-resume, not a pane. Every
-    // failed guard keeps the bare spawn below.
     const tmuxWrap = resolveTmuxWrap({
         interactive,
         platform: process.platform,
@@ -1996,17 +1198,6 @@ async function spawnAgentLeased(options) {
         hasTty: !!process.stdout.isTTY,
     });
     if (tmuxWrap.kind === 'undurable') {
-        // Refuse rather than start work a blink would destroy. This is the ONLY
-        // check — `ensureHostReady` gates a `--device` dispatch on the peer being
-        // reachable and able to run the pinned agent, not on it having tmux, so
-        // there is no launcher-side probe ahead of this one. Failing here still
-        // fails before the agent starts, which is what matters; a pre-dispatch
-        // probe would only move the message earlier, at the cost of a round trip on
-        // every launch. Reached only when the wrap was wanted: the device opted in
-        // via tmux.enabled, or a followed run whose launcher had no TTY (CI,
-        // scripts) left the peer nothing to attach to, so the pane is its stdout.
-        // The config tip uses the ssh form because tmux.enabled is machine-local:
-        // setting it from the launcher throws (assertLocalTarget).
         const msg = `agents: ${machineId()} has no tmux, so this --device run cannot get the pane it needs.\n`
             + `  install it:              (apt|dnf|brew) install tmux\n`
             + `  or turn the wrap off:    agents ssh ${machineId()} 'agents devices config ${machineId()} tmux.enabled off'\n`
@@ -2015,14 +1206,6 @@ async function spawnAgentLeased(options) {
         timer.end({ exitCode: 1, status: 'failed', error: 'remote interactive run has no tmux for durability' });
         return { exitCode: 1, stdout: '', stderr: msg };
     }
-    // Pre-launch marker (`run.launch`), fired on THIS device right before the
-    // harness child is spawned — for BOTH the tmux-wrapped and bare paths below,
-    // and only once the undurable refusal above has passed (a refused run never
-    // spawns). Unlike `run.dispatched` (recordDispatchedRun, at FINALIZE), this
-    // records a launch that then sits stuck at a login screen and never finalizes,
-    // so a launch into a logged-out version is visible instead of silent. The
-    // signed-in verdict is REUSED from the rotated pick when the command threaded
-    // it (options.launchSignedIn), else re-derived from the version home.
     await emitRunLaunch({
         agent: options.agent,
         harnessName: options.harnessName,
@@ -2046,23 +1229,10 @@ async function spawnAgentLeased(options) {
         }
     }
     return new Promise((resolve, reject) => {
-        // Interactive mode inherits all stdio so the CLI owns the TTY (TUI
-        // rendering, raw-mode keystrokes, colored output). Headless mode pipes
-        // stderr so we can scan for rate limits and feed fallback. stdout stays
-        // inherited for TTY, piped when the caller pipes us downstream.
-        // PIPE (and later tee) stdout whenever the live budget watcher must read it
-        // — for ALL non-interactive runs when caps are active, regardless of TTY.
-        // See shouldTapStdout() for the rationale (FIX 3, issue #346).
         const tapStdout = shouldTapStdout(interactive, piped, watcherState !== null, options.captureStdoutTail);
         const stdio = interactive
             ? ['inherit', 'inherit', 'inherit']
             : ['inherit', tapStdout ? 'pipe' : 'inherit', 'pipe'];
-        // On Windows, .cmd batch wrappers (npm-installed CLIs) require shell:true
-        // whether addressed by name or absolute path. On that shell path, compose a
-        // single fully-quoted command line and pass an EMPTY args array (see
-        // composeWin32CommandLine) so Node never concatenates the args array — which
-        // carries the user's prompt — into the cmd.exe line unescaped (DEP0190 +
-        // command injection).
         const useShell = process.platform === 'win32' && (!path.isAbsolute(executable) || executable.endsWith('.cmd'));
         const spawnCommand = useShell ? composeWin32CommandLine(executable, args) : executable;
         const spawnArgs = useShell ? [] : args;
@@ -2073,10 +1243,6 @@ async function spawnAgentLeased(options) {
             env: buildExecEnv(options),
             shell: useShell,
         });
-        // Record this launch so `ag sessions --active` can map the pid to its exact
-        // session (sessionId is set for Claude above) instead of guessing the newest
-        // .jsonl in the cwd — the collapse that made co-located agents indistinguishable.
-        // Best-effort: pruned when the pid dies; a failed write just degrades to the heuristic.
         writePidSessionEntry({
             pid: child.pid ?? 0,
             agent: options.agent,
@@ -2102,23 +1268,16 @@ async function spawnAgentLeased(options) {
                 startedAtMs: Date.now(),
             });
         }
-        // Mark startup time (time from function call to process spawn)
         timer.mark('startup');
         let budgetKilled = false;
         let budgetKillTimer;
         let stdoutTail = '';
         const STDOUT_TAIL_CAP = 16 * 1024;
         if (!interactive && tapStdout && child.stdout) {
-            // TEE the child's stdout back to the parent's so the user still sees
-            // output (mirrors stdio:'inherit') while we tap the same stream for usage.
             child.stdout.pipe(process.stdout);
-            // Keep a rolling TAIL (billing refusals arrive at the very end of a run)
-            // for the fallback chain's rate-limit scan.
             child.stdout.on('data', (chunk) => {
                 stdoutTail = (stdoutTail + chunk.toString('utf-8')).slice(-STDOUT_TAIL_CAP);
             });
-            // Tap the same stream for budget usage events without consuming the pipe
-            // (a 'data' listener and .pipe() both receive every chunk). Kill on breach.
             if (watcherState) {
                 let pendingLine = '';
                 child.stdout.on('data', (chunk) => {
@@ -2165,31 +1324,19 @@ async function spawnAgentLeased(options) {
             recordCompletedLaunch(launchBinding);
             if (timeoutTimer)
                 clearTimeout(timeoutTimer);
-            // Clear the budget-kill SIGKILL escalation timer (mirror the --timeout
-            // timer cleanup) so a programmatic caller reusing execAgent (the #332 loop
-            // driver) never sees a stray 5s kill event fire after the child has exited.
             if (budgetKillTimer)
                 clearTimeout(budgetKillTimer);
-            // Record final spend to the shared ledger (issue #346). Best-effort: a
-            // ledger write must never mask the run's own outcome.
             if (watcherState) {
                 try {
                     watcherState.finalize();
                 }
-                catch { /* ledger write is non-critical */ }
-                // Release the watcher's references / stop accepting events (symmetry).
+                catch { }
                 try {
                     watcherState.watcher.dispose();
                 }
-                catch { /* dispose is best-effort */ }
+                catch { }
             }
-            // Budget kill resolves with a DISTINCT non-zero exit so CI/headless and
-            // teams/cloud can tell a budget termination apart from a normal failure.
             const exitCode = budgetKilled ? BUDGET_KILL_EXIT_CODE : (code ?? 0);
-            // Relate the session id back to a `--device` launcher (see the emitSessionId
-            // doc). Claude's id is the one we forced; every other agent coined its own,
-            // which the SessionStart hook recorded under this run's launchId — resolve
-            // and print it as a one-line sentinel that rides the followed log home.
             if (options.emitSessionId)
                 emitResolvedSessionId(options, launchId, child.pid);
             timer.end({ exitCode, status: budgetKilled ? 'budget_killed' : code === 0 ? 'success' : 'failed' });
@@ -2197,21 +1344,8 @@ async function spawnAgentLeased(options) {
         });
     });
 }
-/** Exit code spawnAgent resolves with when a run is killed for crossing a budget cap. */
 export const BUDGET_KILL_EXIT_CODE = 7;
-/**
- * Exit code a tmux-wrapped run resolves with when tmux cannot tell us how the
- * agent finished — the pane is unreadable, or it is dead with no reported status
- * (EXEC-23b). Never 0: an unknown outcome reported as success is how a run killed
- * mid-work gets counted as a clean finish by whatever scripted it.
- */
 export const UNKNOWN_OUTCOME_EXIT_CODE = 1;
-/**
- * Resolve the budget watcher for a run. Returns null (watcher dormant) when no
- * caps are configured, so non-budget users pay nothing. When caps exist, builds
- * a live watcher seeded with the day/project spend already on the ledger, plus
- * a finalize() that appends this run's accumulated spend.
- */
 async function setupBudgetWatcher(options, cwd, runId) {
     const interactive = resolveInteractive(options);
     if (interactive)
@@ -2232,7 +1366,6 @@ async function setupBudgetWatcher(options, cwd, runId) {
         agentDaySpend: { [options.agent]: ledger.spendForAgentDay(options.agent, today, entries) },
     });
     const watcher = makeLiveSpendWatcher({ caps, onBreach: () => { } });
-    // Accumulate per-(model) usage for a clean final ledger record.
     const seen = [];
     const model = options.model ?? `${options.agent}-default`;
     return {
@@ -2266,13 +1399,6 @@ async function setupBudgetWatcher(options, cwd, runId) {
         },
     };
 }
-/**
- * Patterns that indicate a rate/usage limit. Matching is intentionally broad
- * because providers phrase these differently -- Anthropic uses "5-hour limit"
- * and "rate limit", OpenAI surfaces 429s, Google says "quota exceeded".
- * False positives here just trigger a fallback attempt; false negatives leave
- * the original error unhandled, which is worse.
- */
 export const RATE_LIMIT_PATTERNS = [
     /rate[\s-]?limit/i,
     /usage[\s-]?limit/i,
@@ -2282,23 +1408,12 @@ export const RATE_LIMIT_PATTERNS = [
     /too many requests/i,
     /api[\s_-]?overloaded/i,
     /\boverloaded\b/i,
-    // Claude billing refusals — "You've hit your org's monthly spend limit" and
-    // "You're out of usage credits". Both end the run with exit 1 and are exactly
-    // the condition a fallback chain exists to recover from. Printed to STDOUT,
-    // hence the stdout tail in SpawnResult.
     /spend[\s-]?limit/i,
     /out of (?:usage )?credits/i,
 ];
-/** Return true if the text contains any known rate-limit or overload indicator. */
 export function detectRateLimit(text) {
     return RATE_LIMIT_PATTERNS.some(pattern => pattern.test(text));
 }
-/**
- * Narrow detector for a BILLING exhaustion — tokens/credits run out or the
- * monthly spend cap is hit — as opposed to a time-window rate limit. This class
- * does NOT recover on a clock, so rotation must remember it per-account
- * (noteClaudeOutOfCredits) until a later successful run clears it.
- */
 const OUT_OF_CREDITS_PATTERNS = [
     /out of (?:usage )?credits/i,
     /spend[\s-]?limit/i,
@@ -2306,17 +1421,6 @@ const OUT_OF_CREDITS_PATTERNS = [
 export function detectOutOfCredits(text) {
     return OUT_OF_CREDITS_PATTERNS.some(pattern => pattern.test(text));
 }
-/**
- * Classify a Claude run's output + exit code, model-limit refusal included.
- * Precedence: a session-limit reset first (it carries a clock), then a
- * clock-less billing exhaustion, then a MODEL-specific refusal ("You've
- * reached your Fable limit…") — checked BEFORE the exit-0 clear so a model
- * refusal that ends the run with exit 0 is never misread as a clean success
- * that clears every other stale marker on the account. A model refusal never
- * maps to `note_out_of_credits`/`note_session`: those are account-wide, this
- * names one model. Only a clean run with NO refusal text clears stale
- * markers; anything else leaves them untouched.
- */
 export function classifyClaudeRunRefusal(output, exitCode, model) {
     const sessionLimitReset = parseClaudeSessionLimitReset(output);
     if (sessionLimitReset)
@@ -2331,22 +1435,7 @@ export function classifyClaudeRunRefusal(output, exitCode, model) {
         return { action: 'clear' };
     return { action: 'none' };
 }
-/**
- * Parse Codex's usage-limit refusal reset. Codex prints
- * `ERROR: You've hit your usage limit. … try again at Sep 12th, 2026 8:32 AM.`
- * (or `…try again at 8:32 AM.` for the 5-hour window). The reset is what makes
- * this a session-style limit that auto-clears on its clock rather than a
- * clock-less billing exhaustion. Ordinal suffixes (`12th`) are stripped so
- * `Date.parse` accepts the date; a time-only reset resolves against today/tomorrow.
- * Returns null when there is no future reset to parse (caller then leaves the
- * marker untouched rather than persisting a sticky one it cannot expire).
- */
 export function parseCodexUsageLimitReset(text, nowMs = Date.now()) {
-    // Gate on the CLI's own refusal phrasing, NOT a bare "usage limit" substring:
-    // this runs against a 16KB stdout tail of `codex exec`, which streams the whole
-    // agent transcript, so a session that merely *discusses* usage-limit code would
-    // otherwise false-positive and wrongly mark a HEALTHY account excluded. Mirrors
-    // the narrow Claude convention (`hit your session limit`).
     if (!/hit your usage limit/i.test(text))
         return null;
     const match = /try again (?:at|on)\s+([^.\n]+)/i.exec(text);
@@ -2355,14 +1444,8 @@ export function parseCodexUsageLimitReset(text, nowMs = Date.now()) {
     const segment = match[1].trim().replace(/(\d{1,2})(st|nd|rd|th)\b/gi, '$1');
     const absolute = Date.parse(segment);
     if (!Number.isNaN(absolute)) {
-        // A full date parsed — honor it only while still in the future; a past reset
-        // means the window already recovered, so there is nothing to note. Do NOT
-        // fall through to the clock path, which would understate the real date as
-        // today/tomorrow.
         return absolute > nowMs ? new Date(absolute) : null;
     }
-    // No date parsed — the 5-hour "try again at 8:32 AM" (time-only) form. Resolve
-    // it against today, rolling to tomorrow when the clock has already passed.
     const clock = /(\d{1,2})(?::(\d{2}))?\s*(am|pm)/i.exec(segment);
     if (!clock)
         return null;
@@ -2376,18 +1459,6 @@ export function parseCodexUsageLimitReset(text, nowMs = Date.now()) {
         result.setDate(result.getDate() + 1);
     return result;
 }
-/**
- * Classify what a Codex run's output + exit code means for the account's
- * persisted refusal marker — the Codex sibling of {@link classifyClaudeRunRefusal}
- * (the `ClaudeRefusalAction` shape is harness-generic; the usage cache it drives
- * is identity-keyed and shared across harnesses). Codex's usage limit is
- * time-windowed and carries a reset ("try again at <date>"), so it is noted as a
- * clock-bearing session limit that auto-clears — NOT a clock-less out_of_credits,
- * which would stay sticky until a successful run the excluded account can never
- * get. A genuine credit/quota exhaustion IS clock-less. A clean run clears any
- * stale marker; a limit with no parseable reset is left untouched (the run still
- * cascades via detectRateLimit) rather than persisting an unexpirable marker.
- */
 export function classifyCodexRunRefusal(output, exitCode, nowMs = Date.now()) {
     const reset = parseCodexUsageLimitReset(output, nowMs);
     if (reset)
@@ -2420,11 +1491,6 @@ const AUTH_FAILURE_PATTERNS = [
     /organization has (?:disabled|revoked) .*(?:subscription|access)/i,
     /401\b[^\n]*(?:OAuth|authenticat|credential|Unauthorized)/i,
 ];
-/**
- * Return true if the text contains any known authentication-failure indicator.
- * Agent-agnostic: matches the user-visible error string wherever it surfaces
- * (stdout tail, a captured error message, a plain-text agent's output).
- */
 export function detectAuthFailure(text) {
     return AUTH_FAILURE_PATTERNS.some(pattern => pattern.test(text));
 }
@@ -2467,12 +1533,6 @@ export function detectAuthFailureEvent(logText, agent) {
     }
     return false;
 }
-/**
- * Return the first human-readable auth-failure phrase found in the text, for use
- * as a stable, short run `errorMessage` reason. Falls back to null when the only
- * signal was the structural `error:"authentication_failed"` marker with no
- * user-visible string.
- */
 export function authFailureReason(text) {
     for (const pattern of AUTH_FAILURE_PATTERNS) {
         const m = text.match(pattern);
@@ -2481,20 +1541,6 @@ export function authFailureReason(text) {
     }
     return null;
 }
-/**
- * Decide whether a run's stream-json log is an authentication failure. The
- * single source of truth for both the foreground and detached run paths.
- *
- * The structural marker (`detectAuthFailureEvent`, gated on `is_error:true`) is
- * authoritative and safe on ANY exit — it catches a logged-out Claude that exits
- * 0 (its `result` event carries `is_error:true` while `terminal_reason` is
- * "completed"). The raw user-visible string (`detectAuthFailure`) is only
- * consulted when the process actually FAILED, as a fallback for a run that died
- * mid-stream before emitting a `result` event. That gate is what prevents a
- * genuinely-completed run whose output merely *mentions* an auth phrase (e.g. a
- * routine documenting a login flow) from being misclassified and having its
- * legitimate report suppressed.
- */
 export function isAuthFailureFromLog(logText, agent, opts) {
     if (detectAuthFailureEvent(logText, agent))
         return true;
@@ -2502,16 +1548,6 @@ export function isAuthFailureFromLog(logText, agent, opts) {
         return true;
     return false;
 }
-/**
- * Build the prompt handed to the fallback agent when the primary was stopped
- * mid-task by a rate limit.
- *
- * When the prior agent was Claude we pin its session ID via `--session-id` so
- * `prevSessionId` is always defined; for other primaries we pass undefined and
- * get a simpler retry-with-context prompt. Claude understands `/continue <id>`
- * via its shipped skill -- other agents fall through to an explicit instruction
- * that points at the version-agnostic `agents sessions <id>` reader.
- */
 export function buildFallbackPrompt(prevAgent, prevSessionId, nextAgent, originalPrompt) {
     if (nextAgent === 'claude' && prevSessionId) {
         return `/continue ${prevSessionId}`;
@@ -2525,20 +1561,7 @@ export function buildFallbackPrompt(prevAgent, prevSessionId, nextAgent, origina
     lines.push(``, `Original request: ${originalPrompt}`, ``, `Continue from where the prior agent left off.`);
     return lines.join('\n');
 }
-/**
- * Run an agent and, on rate-limit failure, cascade through the fallback chain.
- *
- * The primary agent gets the original prompt. Subsequent agents get a
- * `/continue <id>`-style handoff (see buildFallbackPrompt) when we can pin a
- * session ID -- which today means Claude as primary (supports `--session-id`).
- * For other primaries, fallbacks run with the original prompt plus a
- * retry-with-context note, since we can't deterministically resolve their
- * auto-generated session IDs.
- *
- * Only rate-limit failures cascade. Other errors (missing flag, auth failure,
- * compile error) bubble up from the primary so the caller sees the real cause
- * instead of an opaque "all agents failed" message.
- */
+// Fallback preserves an explicit mode; only an implicit mode is re-resolved for the next harness.
 export async function runWithFallback(options) {
     const chain = [
         { agent: options.agent, version: options.version },
@@ -2546,11 +1569,6 @@ export async function runWithFallback(options) {
     ];
     let prevAgent;
     let prevSessionId;
-    // Workflow capability scoping only takes effect on claude (buildExecCommand
-    // guards `--tools` / `--mcp-config` / `--strict-mcp-config` on agent==='claude').
-    // A fallback to any non-claude agent would run with NONE of that scoping — the
-    // declared sandbox silently evaporates. Warn loudly so a rate-limit handoff to
-    // an unscoped agent is never silent (issue #324 fail-open).
     const scopingActive = (options.toolsRestrict && options.toolsRestrict.length > 0)
         || !!options.mcpConfigPath;
     if (scopingActive) {
@@ -2563,25 +1581,18 @@ export async function runWithFallback(options) {
     }
     for (let i = 0; i < chain.length; i++) {
         const { agent, version, envOverride } = chain[i];
-        // Every fallback entry can target a different harness/version home. Sync
-        // its active preset immediately before dispatch so entries 2..N cannot
-        // inherit the stale rules file left by the primary entry.
         const rulesVersion = version ?? resolveVersion(agent);
         if (rulesVersion) {
             applyActiveRulesPresetAtRun(agent, rulesVersion, getVersionHomePath(agent, rulesVersion));
             applySystemResourcesAtRun(agent, rulesVersion, getVersionHomePath(agent, rulesVersion));
         }
-        // Record the entry we're about to attempt so the caller (audit log) sees the
-        // agent+version that actually ran, even after a rate-limit handoff.
         if (options.dispatchSink) {
             options.dispatchSink.agent = agent;
             options.dispatchSink.version = version;
         }
         const pinnedSessionId = agent === 'claude' ? randomUUID() : undefined;
-        // Same-host retry (same agent+version as previous entry — used by profile
-        // `fallback_model` swaps) keeps the original prompt: the model changed,
-        // not the CLI, so a `/continue` handoff prompt would be misleading.
         const prev = i > 0 ? chain[i - 1] : undefined;
+        // Same-agent entries are account/model retries, not cross-harness transcript handoff.
         const sameHostRetry = !!prev && prev.agent === agent && prev.version === version;
         const prompt = prevAgent && !sameHostRetry
             ? buildFallbackPrompt(prevAgent, prevSessionId, agent, options.prompt)
@@ -2594,8 +1605,6 @@ export async function runWithFallback(options) {
             prompt,
             env: envOverride ? { ...(options.env ?? {}), ...envOverride } : options.env,
             sessionId: pinnedSessionId ?? (i === 0 ? options.sessionId : undefined),
-            // Claude prints billing refusals (spend limit / out of credits) to
-            // stdout; tail it so the cascade check below can see them.
             captureStdoutTail: true,
         };
         const label = version ? `${agent}@${version}` : agent;
@@ -2620,13 +1629,6 @@ export async function runWithFallback(options) {
             throw err;
         }
         const output = `${result.stderr}\n${result.stdout}`;
-        // Persist a per-account refusal marker so rotation stops re-picking a
-        // known-dead account: a session/usage limit recovers on its clock, a billing
-        // exhaustion (tokens/credits) recovers only on a later successful run, and a
-        // clean run clears any stale marker. Claude and Codex both surface these as
-        // run-ending text, and the usage cache is identity-keyed (shared across
-        // harnesses), so one path notes either. Decisions extracted + unit-tested in
-        // classify{Claude,Codex}RunRefusal.
         const refusal = agent === 'claude'
             ? classifyClaudeRunRefusal(output, result.exitCode ?? 1, execOpts.model)
             : agent === 'codex'
@@ -2634,12 +1636,6 @@ export async function runWithFallback(options) {
                 : null;
         const sessionLimitReset = refusal?.action === 'note_session' ? refusal.resetsAt : null;
         if (refusal && version && refusal.action !== 'none') {
-            // Resolve the account from the HOME this attempt actually authenticated
-            // from — execHome (a slot dir, PHNX-3940 T5) or configVersion wins over
-            // the bare managed-binary version home. Reading `getVersionHomePath(agent,
-            // version)` unconditionally attributed a refusal to the wrong account for
-            // every account-slot / configVersion launch, since `version` there is the
-            // BINARY, not the credential's home.
             const { versionHome: refusalHome } = resolveExecConfigHome(execOpts);
             const account = await getAccountInfo(agent, refusalHome ?? getVersionHomePath(agent, version));
             const usageKey = getUsageLookupKey(account);
@@ -2652,16 +1648,13 @@ export async function runWithFallback(options) {
                     clearClaudeAccountRefusal(usageKey);
             }
         }
-        // A model-limit refusal commonly ends the CLI turn with exit 0 (Claude
-        // just refuses to keep going on that model rather than crashing) — so,
-        // like a session-limit reset, it must not be read as a clean success that
-        // short-circuits the cascade before the fallback chain ever runs.
         const modelLimited = refusal?.action === 'note_model_limit';
         if (result.exitCode === 0 && !sessionLimitReset && !modelLimited)
             return 0;
         const isLast = i === chain.length - 1;
         if (isLast)
             return result.exitCode || 1;
+        // Authentication and ordinary failures never trigger provider fallback; only explicit capacity signals do.
         if (!sessionLimitReset && !modelLimited && !detectRateLimit(result.stderr) && !detectRateLimit(result.stdout)) {
             return result.exitCode;
         }