@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/daemon/runner.js

@@ -1,18 +1,3 @@
-/**
- * Job execution engine for routines.
- *
- * Builds agent-specific CLI commands from job configs, spawns them with
- * sandboxed or unsandboxed environments, captures stdout to log files,
- * enforces timeouts, and extracts the final assistant report from the
- * agent's stream-JSON output.
- *
- * Version/account selection mirrors `agents run`: when a routine does not pin
- * `version:`, the runner uses the configured run strategy (default `balanced`)
- * to pick a healthy install, pins the absolute binary via `getBinaryPath`, and
- * arms same-agent failover across other healthy accounts when a rate/usage
- * limit is detected mid-run (foreground `executeJob` only — detached daemon
- * fires once with the pre-flight pick).
- */
 import { spawn, execFileSync } from 'child_process';
 import * as fs from 'fs';
 import * as fsp from 'fs/promises';
@@ -60,7 +45,7 @@ function recordRoutineAuthOutcome(agent, accountName, version, outcome) {
             : null;
         recordRunAuthOutcome({ agent, accountId, version: version ?? null, account: accountName, outcome });
     }
-    catch { /* best-effort */ }
+    catch { }
 }
 export class RoutineAlreadyRunningError extends Error {
     constructor(jobName, runId) {
@@ -70,26 +55,7 @@ export class RoutineAlreadyRunningError extends Error {
 }
 const ROUTINE_LAUNCH_LOCK_STALE_MS = 30_000;
 const ROUTINE_LAUNCH_LOCK_WAIT_MS = 10_000;
-/**
- * The prior run of this routine that still holds the active-run slot, or null.
- *
- * ONLY a run still marked `running` can hold the slot. Every terminal status —
- * completed / failed / timeout / missed / blocked / skipped — releases it the
- * moment it is reached (RUSH-2640). A `failed`/`timeout` record used to keep the
- * slot while its pid stayed alive, but that conflated two different operations:
- * cleaning up a leftover process group (reapTerminalRoutineProcesses's job) with
- * occupying the slot. A daemon-launched run that reached a terminal state while
- * still carrying the daemon's own pid (a host run that threw `target_unreachable`
- * before spawning a child) then held the slot forever, because the daemon never
- * dies and `isPidOurs` never went false — every later scheduled slot was refused
- * with `already has an active run` while the routine was silently dead.
- *
- * A `running` record is also aged out past its own timeout: a run cannot
- * legitimately outlive its configured deadline, so past that window it is a
- * wedged record (a daemon that died mid-run, a missed child-exit event, a reused
- * pid an old record without `spawnedAt` reads as "ours"), not a live run — and it
- * never holds the slot regardless of what its recorded pid now points at.
- */
+// Only a live, within-timeout running record holds the slot; dead/stale running and terminal records release it.
 function activeRoutineRun(config) {
     const timeoutMs = parseTimeout(config.timeout) || 10 * 60 * 1000;
     const now = Date.now();
@@ -102,9 +68,6 @@ function activeRoutineRun(config) {
         const limit = run.timeoutMs ?? timeoutMs;
         if (Number.isFinite(startedAt) && now - startedAt >= limit)
             continue;
-        // A provisional launcher claim carries no child pid yet — trust it until the
-        // timeout window above elapses. A record with a child pid is active only
-        // while that pid is genuinely ours (alive with the same birth time).
         if (!run.pid)
             return run;
         if (isPidOurs(run.pid, run.spawnedAt))
@@ -112,14 +75,6 @@ function activeRoutineRun(config) {
     }
     return null;
 }
-/**
- * Consecutive trailing `skipped`/`active_run` records — a routine that keeps
- * being refused because a prior run "still owns" the slot. After the slot is
- * released correctly on terminal states (see {@link activeRoutineRun}) this can
- * only accumulate for a genuine long-overlap or a new wedge; either way it means
- * the routine has stopped firing on schedule and should be surfaced, not left to
- * pile up silently. `runs` is oldest→newest (listRuns sorts by run id).
- */
 export function activeRunSkipStreak(runs) {
     let streak = 0;
     for (let i = runs.length - 1; i >= 0; i--) {
@@ -132,38 +87,17 @@ export function activeRunSkipStreak(runs) {
     }
     return streak;
 }
-/** How many consecutive active-run skips before a routine's stall is surfaced. */
 const SKIP_STREAK_ALERT_THRESHOLD = 3;
-/**
- * The pid to stamp on a launcher's provisional active claim, or null when the
- * launcher is this box's routines daemon.
- *
- * The claim pid exists so a launcher that dies between claiming the slot and
- * spawning the child releases the slot quickly (`isPidOurs` goes false) instead
- * of wedging it for the full timeout. That fast recovery only helps a SHORT-LIVED
- * foreground launcher (`agents routines run`): the daemon never dies between
- * claim and spawn, and recording ITS pid is actively harmful — the daemon
- * outlives every run, so `isPidOurs` never goes false and a claim finalized to a
- * terminal state before its child spawned kept the slot and drew
- * `reapTerminalRoutineProcesses` at the daemon's own process group on every tick
- * (RUSH-2640, requirement: never record the daemon's own pid as a run's pid). So
- * the daemon records no claim pid; the timeout window bounds a daemon that
- * crashes mid-claim instead.
- */
+// The long-lived daemon never records its own pid as a provisional child claim.
 export function launcherClaimPid() {
     try {
-        // Mirrors daemon.ts readDaemonPid() (PID_FILE = 'daemon.pid'); read directly
-        // rather than importing it to avoid a runner<->daemon import cycle.
         const daemonPid = parseInt(fs.readFileSync(path.join(getDaemonDir(), 'daemon.pid'), 'utf-8').trim(), 10);
         if (Number.isFinite(daemonPid) && daemonPid === process.pid)
             return null;
     }
-    catch { /* no daemon pid file — a foreground launcher; record its pid */ }
+    catch { }
     return process.pid;
 }
-/** Serialize concurrent launches of one routine on this box (the on-disk claim
- *  primitive `claimRunSlot` is what holds across processes; this lock only makes
- *  the allocate→spawn window atomic within this process's launch paths). */
 async function withRoutineLock(config, launch) {
     const target = path.join(getJobRunsDir(config.name), '.launch-claim');
     ensureLockTarget(target, '', 0o700);
@@ -184,13 +118,6 @@ async function withRoutineLock(config, launch) {
         await release();
     }
 }
-/**
- * Reject placement/body combinations the runner cannot execute — before the
- * attempt is allocated, so an invalid config (host+workflow, cloud+command, …)
- * throws cleanly rather than allocating a run record it can never satisfy. These
- * mirror the defensive guards inside `executeJobOnHost`/`executeJobOnCloud`;
- * `validateJob` already rejects the same combinations at add/edit time.
- */
 function assertRunnablePlacement(config) {
     const strategy = resolveHostStrategy(config);
     if (strategy === 'host' || strategy === 'fleet') {
@@ -210,7 +137,6 @@ function assertRunnablePlacement(config) {
             throw new Error(`Routine '${config.name}' uses 'command:', which can't execute in the cloud yet — remove 'hostStrategy: cloud' or 'command:'.`);
     }
 }
-/** Write a pre-execution terminal record (blocked/skipped) that spawns nothing. */
 function writeTerminalRecord(config, runId, status, trigger, extra) {
     fs.mkdirSync(getRunDir(config.name, runId), { recursive: true });
     const now = new Date().toISOString();
@@ -236,7 +162,6 @@ function writeTerminalRecord(config, runId, status, trigger, extra) {
     writeRunMeta(meta);
     return meta;
 }
-/** Persist the cross-entry-point active claim before releasing the launch lock. */
 function writeActiveClaim(config, attempt) {
     const now = new Date().toISOString();
     const meta = {
@@ -245,17 +170,7 @@ function writeActiveClaim(config, attempt) {
         ...runProvenance(config),
         ...attempt.stamp,
         ...(config.workflow ? { workflow: config.workflow } : config.command ? { command: config.command } : config.agent ? { agent: config.agent } : {}),
-        // The launcher owns this provisional claim until the command/agent child
-        // replaces it with its own pid. Recording a SHORT-LIVED foreground launcher's
-        // pid makes a crash between lock release and child spawn recoverable instead
-        // of wedging the routine for its full configured timeout. The long-lived
-        // daemon records no pid here (see launcherClaimPid): its pid never dies, so
-        // recording it wedged the slot forever and mis-aimed the process reaper at the
-        // daemon itself (RUSH-2640).
         pid: launcherClaimPid(),
-        // `isPidOurs` compares this value with the OS process birth time. The
-        // daemon may have been alive for days before claiming a routine, so the
-        // claim must carry the launcher's birth, not the claim timestamp.
         spawnedAt: Date.now() - process.uptime() * 1000,
         status: 'running',
         startedAt: now,
@@ -266,24 +181,11 @@ function writeActiveClaim(config, attempt) {
     writeRunMeta(meta);
     return meta;
 }
-/**
- * Allocate a routine attempt BEFORE any placement / version / sandbox / preflight
- * / dispatch work, so every rejected, skipped, or blocked fire leaves exactly one
- * visible terminal record. Runs inside {@link withRoutineLock}. Enforces, in order:
- *
- *  1. single-fire — a scheduled slot atomically claims its (routine, UTC) run
- *     directory; a duplicate cron delivery for the same slot returns the original
- *     attempt and spawns nothing.
- *  2. non-overlap — a prior run of this routine that is still active makes this
- *     attempt a `skipped`/`active_run` record linking the live run.
- *  3. readiness — an unresolved/blocked execution context (bad cwd, non-portable
- *     path, missing project base, …) makes this a `blocked` record.
- */
+// Schedule and catchup deliveries atomically claim the same (routine, UTC slot).
 function allocateRoutineAttempt(config, trigger) {
     const scheduledForIso = trigger.scheduledFor
         ? (typeof trigger.scheduledFor === 'string' ? trigger.scheduledFor : trigger.scheduledFor.toISOString())
         : undefined;
-    // 1. Slot claim (schedule/catchup). Manual/webhook/event fires get a fresh id.
     let runId;
     if (scheduledForIso) {
         runId = slotRunId(scheduledForIso);
@@ -305,7 +207,6 @@ function allocateRoutineAttempt(config, trigger) {
         runId = generateRunId();
         fs.mkdirSync(getRunDir(config.name, runId), { recursive: true });
     }
-    // 2. Non-overlap: a prior run of THIS routine is still live.
     const active = activeRoutineRun(config);
     if (active && active.runId !== runId) {
         return {
@@ -327,10 +228,6 @@ function allocateRoutineAttempt(config, trigger) {
             }),
         };
     }
-    // Gate on deprecation alone, not ROUTINE_AGENT_IDS membership — a retired
-    // harness leaves the command table (gemini did), and the legacy routine must
-    // still land a visible 'blocked' record, never a generic buildJobCommand
-    // failure (RUSH-2202).
     if (!config.workflow && config.agent && !isCustomHarnessName(config.agent) && isAgentHardDeprecated(config.agent)) {
         const reason = hardDeprecationError(config.agent);
         return {
@@ -354,9 +251,6 @@ function allocateRoutineAttempt(config, trigger) {
             }),
         };
     }
-    // 3. Readiness: resolve the execution context for the routine's placement.
-    //    Local placement inspects this box's filesystem; host/fleet/cloud defer
-    //    existence (the remote fs is unreachable here) and enforce portability only.
     const mode = resolveHostStrategy(config);
     const ctx = resolveJobExecutionContext(config, {
         mode,
@@ -381,14 +275,6 @@ function allocateRoutineAttempt(config, trigger) {
     }
     return { proceed: true, attempt: { runId, stamp } };
 }
-/**
- * Emit a loud, once-per-wedge warning when a routine has been refused its slot
- * for {@link SKIP_STREAK_ALERT_THRESHOLD} consecutive scheduled runs. Fires only
- * when the streak first reaches the threshold (not on every later skip), so a
- * genuinely-stalled routine surfaces once instead of piling up silent `skipped`
- * records the way RUSH-2640 did. Runs on the daemon's own stderr, so it lands in
- * the daemon log the operator reads.
- */
 function surfaceWedgedRoutine(config, terminal) {
     if (terminal.status !== 'skipped' || terminal.skipReason !== 'active_run')
         return;
@@ -399,13 +285,6 @@ function surfaceWedgedRoutine(config, terminal) {
     process.stderr.write(`[agents] routine '${config.name}' skipped ${streak} consecutive scheduled runs — ` +
         `its active-run slot is still held by ${stuck}; the routine is not firing on schedule.\n`);
 }
-/**
- * Claim one routine attempt under the short launch lock, then execute after
- * releasing it. The persisted `running` claim makes a concurrent entry point
- * skip immediately instead of waiting for a foreground run to finish. `run` is
- * the placement/command/agent dispatch, invoked only when the attempt proceeds;
- * `wrapTerminal` adapts a pre-spawn terminal record into the caller's return type.
- */
 async function runWithAttempt(config, trigger, run, wrapTerminal) {
     const claimed = await withRoutineLock(config, async () => {
         const alloc = allocateRoutineAttempt(config, trigger);
@@ -436,96 +315,42 @@ async function runWithAttempt(config, trigger, run, wrapTerminal) {
         }));
     }
 }
+// Never signal this process; timeout callbacks own their child, while reconciliation birth-time-verifies recorded pids before calling here.
 function terminateRoutineTree(pid) {
     if (!pid)
         return;
-    // Never take THIS process down. Both kills below are unconditional SIGKILLs,
-    // so a RunMeta naming the reaper's own pid -- a reused pid, a record written
-    // by the process now doing the reaping, or a hand-written fixture -- makes the
-    // reaper SIGKILL itself, and via `-pid` its whole process group with it. There
-    // is no recovery from that: the run is never finalized, and on the daemon it
-    // takes the scheduler down mid-sweep. daemon.ts:457 already refuses to evict an
-    // incumbent whose pid is `process.pid` for exactly this reason; the reap path
-    // needs the same guard. Skipping the kill still lets the caller finalize the
-    // run record, which is the part that matters.
     if (pid === process.pid)
         return;
     if (process.platform === 'win32') {
         killTree(pid);
         return;
     }
-    // Detached spawn makes the child a new process-group leader; kill the group.
-    // If setsid has not landed yet (or the pid is not a leader), -pid fails with
-    // ESRCH and the child stays up — also kill the pid itself.
     try {
         process.kill(-pid, 'SIGKILL');
     }
-    catch { /* not a group leader, or already exited */ }
+    catch { }
     try {
         process.kill(pid, 'SIGKILL');
     }
-    catch { /* already exited */ }
+    catch { }
 }
-/**
- * Where each agent's transcript files live under an overlay HOME, mirroring
- * `SESSION_ROOT_SPECS` (session/discover.ts) — the CLI's own source of truth
- * for which on-disk trees hold live session files. Kept in this shape (not a
- * shared import) because `archiveRoutineTranscripts` only needs a flat
- * root+ext pair to `walkForFiles`, not the version-home/backup fan-out
- * `getAgentSessionDirs` does for live discovery.
- *
- * `opencode` is deliberately absent: `SESSION_ROOT_SPECS` itself has no entry
- * for it — its transcripts live in one incrementally-scanned SQLite db
- * (`scanOpenCodeIncremental`), not a per-session file tree — so there is
- * nothing here to mirror without inventing a new discovery path.
- */
 const ROUTINE_TRANSCRIPT_SPECS = {
     claude: [{ root: ['.claude', 'projects'], ext: '.jsonl' }],
     codex: [{ root: ['.codex', 'sessions'], ext: '.jsonl' }],
     cursor: [{ root: ['.cursor', 'projects'], ext: '.jsonl' }],
     antigravity: [{ root: ['.gemini', 'antigravity-cli', 'conversations'], ext: '.db' }],
     droid: [{ root: ['.factory', 'sessions'], ext: '.jsonl' }],
-    // Kimi splits a session across two files (session/discover.ts:4382-4384):
-    // state.json (title/timestamps) and agents/main/wire.jsonl (the actual
-    // conversation). Both extensions are needed — .json alone archives only
-    // the metadata shell and silently drops every message.
     kimi: [
         { root: ['.kimi-code', 'sessions'], ext: '.json' },
         { root: ['.kimi-code', 'sessions'], ext: '.jsonl' },
     ],
     grok: [{ root: ['.grok', 'sessions'], ext: '.json' }],
-    // Muse: ~/.local/share/muse/sessions/YYYY/MM/DD/<uuid>/session.jsonl
     muse: [{ root: ['.local', 'share', 'muse', 'sessions'], ext: '.jsonl' }],
 };
-/**
- * Working directory for a routine's LOCAL child, resolved from its explicit
- * `project`/`cwd` execution anchor via {@link resolveJobExecutionContext} — never
- * inferred from `repo` (which is external repository identity only) and never the
- * daemon's launch cwd. A command routine with neither field lands in `$HOME`
- * (housekeeping); an unresolved/blocked agent context also falls back to `$HOME`
- * so a caller that reaches this (past the readiness gate) has a valid directory,
- * but the gate should have paused such a routine before it ever spawned.
- */
 export function routineSpawnCwd(config) {
     const ctx = resolveJobExecutionContext(config, { mode: 'local' });
     return ctx.absoluteCwd ?? os.homedir();
 }
-/**
- * Bake the daemon-job argv skeleton from AGENT_COMMANDS.
- *
- * The two tables used to be independent copies of the same launch decision.
- * Argv now comes from AGENT_COMMANDS.base / promptFlag / jsonFlags / modeFlags.
- * Two documented exceptions, not a second table:
- *   - kimi uses `--prompt` (long form). `-p` is the exec alias; combining
- *     either with --plan/--auto/--yolo aborts, so routineModeArgs emits no
- *     mode flag. The daemon has always spawned the long form.
- *   - claude places `--verbose` (from jsonFlags) before the prompt and bakes
- *     modeFlags.plan so claudeAdapter.routineModeArgs can splice
- *     plan → acceptEdits / auto / skip.
- *
- * Returns undefined when `agent` is outside ROUTINE_AGENT_IDS (grok and every
- * other harness the daemon does not fire locally).
- */
 export function bakeRoutineArgv(agent) {
     if (!ROUTINE_AGENT_IDS.includes(agent))
         return undefined;
@@ -552,50 +377,26 @@ export function bakeRoutineArgv(agent) {
     }
     return cmd;
 }
-/** Build the full CLI argv for executing a job, applying mode, model, and permission flags. */
 export function buildJobCommand(config, resolvedPrompt, forwardAccount = true) {
-    // Workflow branch: delegate to `agents run <workflow>` which handles subagent
-    // injection, WORKFLOW.md orchestration, and model selection via frontmatter.
-    // appendModelAndReasoning is intentionally skipped — the workflow frontmatter
-    // owns model selection. No --timeout flag: the runner enforces its own SIGTERM/SIGKILL.
     if (config.workflow) {
         const cmd = ['agents', 'run', config.workflow, resolvedPrompt, '--mode', config.mode];
         if (config.account && forwardAccount)
             cmd.push('--account', config.account);
         return cmd;
     }
-    // Past the workflow branch this is an agent (or resume) job — command jobs never
-    // reach buildJobCommand (execute*Job branches out first), and validateJob guarantees agent.
     const agent = config.agent;
-    // Resume branch: reopen an EXISTING session via `agents run <agent> --resume <id>`
-    // instead of starting fresh. The real session resumes with its full prior context
-    // (index-based lookup, cwd-independent) and `resolvedPrompt` becomes its next turn —
-    // so a self-scheduled wake (e.g. /hibernate) is handled by the session that scheduled
-    // it, not a fresh, context-less agent that would refuse an "opaque" instruction.
     if (config.resume) {
         const cmd = ['agents', 'run', agent, '--resume', config.resume, resolvedPrompt, '--mode', config.mode];
         if (config.account && forwardAccount)
             cmd.push('--account', config.account);
         return cmd;
     }
-    // Custom-harness branch: delegate to `agents run <name>`, which owns profile
-    // resolution (host binary, model env, provider auth) — the same delegation
-    // the workflow and resume branches use. The profile pins its own version and
-    // auth, so no command template, binary pinning, or account-env injection
-    // applies here.
     if (isCustomHarnessName(agent)) {
         const cmd = ['agents', 'run', agent, resolvedPrompt, '--mode', config.mode];
         if (config.account && forwardAccount)
             cmd.push('--account', config.account);
         return cmd;
     }
-    // Native slot accounts share one managed binary version, so the baked
-    // harness argv cannot identify which login to spawn. Dispatch through
-    // `agents run <agent>#<name>` (the same seam as resume/custom) so T5
-    // spawn-time resolution selects the slot. `--account` is an agents-cli
-    // flag; the harness binary would ignore or reject it.
-    // Provider/durable-pinned accounts stay on the harness argv + env-injection
-    // path: `#name` is a native selector and would not inject their bundle.
     if (config.account && forwardAccount && !findAccount(config.account)) {
         const spec = config.version
             ? `${agent}@${config.version}#${config.account}`
@@ -604,29 +405,18 @@ export function buildJobCommand(config, resolvedPrompt, forwardAccount = true) {
     }
     const template = bakeRoutineArgv(agent);
     if (!template) {
-        // A name outside both tables was either never valid or was a custom
-        // harness whose profile has since been deleted — validateJob accepted it
-        // against a profile that existed then. Name the repair, not just the miss.
         throw new Error(`Unsupported agent for daemon jobs: ${agent}. ` +
             `If '${agent}' was a custom harness, its profile no longer exists on this device — ` +
             `recreate it (agents harness add ${agent} ...) or point the routine at another agent.`);
     }
     let cmd = template.map((part) => part.replace('{prompt}', resolvedPrompt));
-    // Canonicalize mode (accepts legacy `full` as alias for `skip`).
     const mode = normalizeMode(config.mode);
-    // Routine launch-arg quirks (the harness axis of Move 3): each per-agent arm
-    // moves to its harness adapter; runner appends model/reasoning flags after,
-    // exactly as every arm did. Agents with no routine quirk have no adapter
-    // override, so they skip both — the old behavior for an entry with no arm.
     const routineAdapter = resolveHarnessAdapter(agent);
     if (routineAdapter.routineModeArgs) {
         routineAdapter.routineModeArgs(cmd, { mode, config, resolveHeadlessMode });
         appendModelAndReasoning(cmd, config);
     }
-    // allow.dirs → harness-specific grants. Codex is handled in its branch above
-    // (workspace_roots). Claude / Kimi / Cursor take --add-dir; Grok gets rules
-    // (+ sandbox widen when GROK_SANDBOX is on). Reject leading '-' so a routine
-    // YAML can't smuggle an argv flag past the sandbox as an allow.dirs entry.
+    // A leading dash would turn a YAML directory into an injected harness flag.
     if (config.allow?.dirs?.length && agent !== 'codex') {
         for (const dir of config.allow.dirs) {
             if (dir.startsWith('-')) {
@@ -639,16 +429,7 @@ export function buildJobCommand(config, resolvedPrompt, forwardAccount = true) {
     }
     return cmd;
 }
-/**
- * Append the agent's canonical model flag and reasoning flags to a command.
- *
- * Pass-through model resolution: validates against the installed (agent, version)
- * catalog when possible and writes a warning to stderr on miss, but never blocks.
- * Reasoning level (config.config.reasoning) maps to per-agent flags via models.ts.
- */
 function appendModelAndReasoning(cmd, config) {
-    // Only called from buildJobCommand's agent path AFTER the custom-harness
-    // branch returned — config.agent is a native id here.
     const agent = config.agent;
     const model = config.config?.model;
     if (model) {
@@ -677,35 +458,10 @@ function appendModelAndReasoning(cmd, config) {
 function generateRunId() {
     return new Date().toISOString().replace(/[:.]/g, '-');
 }
-/**
- * Agents whose config dir `buildExecEnv` relocates OUT of the sandbox overlay HOME
- * into their per-version home (exec.ts: CLAUDE_CONFIG_DIR / CODEX_HOME). A routine
- * spawned for one of these writes its transcript under the version home, NOT the overlay
- * the sandbox generated — so the archiver has to read it there. Both are version-pinned
- * (never self-updating), so `RunMeta.version` names a real home.
- *
- * Scoped to the agents whose archived transcript the DISCOVERY side can already index as
- * origin='routine' — `readRoutineArchiveMeta` (session/discover.ts) has a branch for
- * claude and codex but not kimi. Kimi also relocates (KIMI_CODE_HOME) and hits the same
- * bug, but archiving it here without a discovery branch would only copy files that are
- * never indexed; adding a kimi reader (its session spans state.json + wire.jsonl under a
- * `session_<uuid>` dir) is the separate follow-up that lets kimi join this set. Muse
- * (XDG, self-updating) and copilot (no transcript spec) are likewise out of scope.
- */
 const CONFIG_DIR_RELOCATED_AGENTS = new Set(['claude', 'codex']);
-/** Whether this run's transcript lands in a SHARED per-version home (accumulating every
- *  session that version+account ever ran) rather than the run's own disposable overlay. */
 function usesSharedTranscriptHome(agent, version) {
     return Boolean(version) && CONFIG_DIR_RELOCATED_AGENTS.has(agent);
 }
-/**
- * The directories the child actually writes a transcript to for one spec — resolved to
- * match `buildExecEnv` (exec.ts), the single decision-point for where the transcript
- * lands, so the archiver can never drift from it. For a config-dir-relocated agent that
- * is the per-version home (`.claude`, `.codex`, …); for everyone else it is the sandbox
- * overlay HOME. Codex may run from a SUN_LEN-safe short home on macOS (codex-home.ts),
- * so both candidates are returned and the caller skips whichever does not exist.
- */
 function routineTranscriptSourceRoots(agent, version, overlayHome, spec) {
     if (usesSharedTranscriptHome(agent, version)) {
         const roots = [path.join(getVersionHomePath(agent, version), ...spec.root)];
@@ -716,22 +472,13 @@ function routineTranscriptSourceRoots(agent, version, overlayHome, spec) {
     }
     return [path.join(overlayHome, ...spec.root)];
 }
-/** Path of the per-run baseline recorded before spawn (see {@link snapshotRoutineTranscriptBase}). */
 function transcriptBasePath(runDir) {
     return path.join(runDir, '.transcript-base.json');
 }
-/**
- * Record every transcript file already present in the child's transcript dirs BEFORE
- * the run spawns. When the transcript lands in a shared per-version home, this baseline
- * is what lets the archiver copy only the file THIS run produced instead of sweeping in
- * every sibling session that home holds (which would mis-tag them all `origin='routine'`
- * under this run's name). Called once per run, before spawn.
- */
+// Shared version homes contain sibling transcripts, so snapshot before spawn and archive only newly-created files.
 export function snapshotRoutineTranscriptBase(meta, runDir, overlayHome) {
     if (!meta.agent)
         return;
-    // A host/cloud custom-harness run records the harness name, which has no
-    // transcript spec — the null-specs guard below skips it, as before.
     const specs = ROUTINE_TRANSCRIPT_SPECS[meta.agent];
     if (!specs)
         return;
@@ -750,12 +497,8 @@ export function snapshotRoutineTranscriptBase(meta, runDir, overlayHome) {
         fs.writeFileSync(transcriptBasePath(runDir), JSON.stringify([...preexisting]), { mode: 0o600 });
     }
     catch {
-        // Best-effort: a missing baseline is handled conservatively at archive time
-        // (a shared home is skipped rather than bulk-copied).
     }
 }
-/** Read the pre-spawn baseline. `null` means none was recorded (older run or a failed
- *  snapshot) — the archiver then refuses to bulk-copy a shared home. */
 function readTranscriptBase(runDir) {
     try {
         const arr = JSON.parse(fs.readFileSync(transcriptBasePath(runDir), 'utf-8'));
@@ -763,24 +506,18 @@ function readTranscriptBase(runDir) {
             return new Set(arr.filter((x) => typeof x === 'string'));
     }
     catch {
-        // No baseline file, or it was unreadable/corrupt.
     }
     return null;
 }
 export function archiveRoutineTranscripts(meta, runDir, overlayHome) {
     if (!meta.agent)
         return;
-    // A host/cloud custom-harness run records the harness name, which has no
-    // transcript spec — the null-specs guard below skips it, as before.
     const specs = ROUTINE_TRANSCRIPT_SPECS[meta.agent];
     if (!specs)
         return;
     const home = overlayHome ?? getJobHomePath(meta.jobName);
     const shared = usesSharedTranscriptHome(meta.agent, meta.version);
     const base = readTranscriptBase(runDir);
-    // A shared per-version home holds every session that version+account ran, so without a
-    // per-run baseline we cannot tell this run's transcript from a sibling's — copy nothing
-    // rather than mis-tag them all. A disposable overlay is this run's alone, so copy all.
     if (shared && base === null)
         return;
     for (const spec of specs) {
@@ -789,7 +526,6 @@ export function archiveRoutineTranscripts(meta, runDir, overlayHome) {
             if (!fs.existsSync(sourceRoot))
                 continue;
             for (const sourcePath of walkForFiles(sourceRoot, spec.ext, 100_000)) {
-                // Skip files that predate this run (a sibling session in the shared home).
                 if (base?.has(sourcePath))
                     continue;
                 const rel = path.relative(sourceRoot, sourcePath);
@@ -802,31 +538,17 @@ export function archiveRoutineTranscripts(meta, runDir, overlayHome) {
                     fs.chmodSync(destPath, 0o600);
                 }
                 catch {
-                    // The process already reached a terminal state; a concurrently removed
-                    // transcript should not rewrite that outcome.
                 }
             }
         }
     }
 }
-/**
- * Build the argv for a command-mode routine: run the shell string directly
- * through the platform shell. No agent binary, no rotation, no sandbox.
- */
 function buildShellCommand(command) {
     return process.platform === 'win32'
         ? ['cmd', '/c', command]
         : ['/bin/sh', '-c', command];
 }
-/**
- * Real (un-sandboxed) environment for a command routine. Command routines do
- * `npm i -g` / `git pull` and need the actual $HOME / $PATH, not the sandbox
- * overlay. Only TZ is injected when the routine pins a timezone.
- *
- * The current binary's directory is prepended to PATH so bare `agents` invocations
- * resolve to the same install on Windows (where shell-function injection is not
- * available) and as a fallback on POSIX for invocations like `command agents`.
- */
+// Command routines inherit real HOME/base PATH then prepend this CLI's bin; only agent routines receive overlay/version-home isolation.
 function commandSpawnEnv(config) {
     const env = { ...process.env };
     if (config.timezone)
@@ -839,49 +561,24 @@ function commandSpawnEnv(config) {
     }
     return env;
 }
-/** POSIX single-quote a string so it is safe to embed in a `/bin/sh -c` script. */
 function shSingleQuote(s) {
     return `'${s.replace(/'/g, `'\\''`)}'`;
 }
-/**
- * Build a POSIX shell function that forwards `agents <sub...>` to the SAME binary
- * currently running. Command routines shell out to the bare name `agents`
- * (e.g. `agents repo pull system`); without this, the routine resolves `agents`
- * through its inherited PATH, which can pick up a stale install in an nvm/system
- * Node prefix that shadows the current binary (RUSH-2431).
- *
- * Uses getCliLaunch so the relaunch is correct for both JS installs
- * (`node <entry> <sub...>`) and compiled standalone binaries (`<bin> <sub...>`).
- */
+// Bind bare `agents` inside a command routine to the exact binary running this daemon.
 function agentsShellFunction() {
     const launch = getCliLaunch(['__ac_placeholder__']);
     const parts = [launch.command];
-    // JS installs: getCliLaunch returns [node, entryScript, placeholder].
-    // Standalone: it returns [binary, placeholder].
     if (launch.args.length > 0 && launch.args[0] !== '__ac_placeholder__' && fs.existsSync(launch.args[0])) {
         parts.push(launch.args[0]);
     }
     const invocation = parts.map(shSingleQuote).join(' ');
     return `agents() { ${invocation} "$@"; }`;
 }
-/**
- * Wrap a command-routine shell string so any bare `agents` invocation resolves
- * to the current binary. On POSIX this injects an `agents` shell function; on
- * Windows it is left unchanged and commandSpawnEnv prepends the current binary's
- * directory to PATH instead.
- */
 function wrapCommandRoutine(command) {
     if (process.platform === 'win32')
         return command;
     return `${agentsShellFunction()}\n${command}`;
 }
-/**
- * Detached command routines write their own exit code to `<runDir>/exit-code`
- * (see the wrapper in executeCommandJobDetached). `monitorRunningJobs` reads it
- * to recover the true terminal status when the daemon restarted between spawn and
- * exit and so missed the in-process `child.on('exit')`. Returns null when the
- * file is absent/unparseable (child killed or crashed before writing it).
- */
 function readCommandExitCode(runDir) {
     try {
         const raw = fs.readFileSync(path.join(runDir, 'exit-code'), 'utf-8').trim();
@@ -893,10 +590,9 @@ function readCommandExitCode(runDir) {
         return null;
     }
 }
-/** Claude's own local auth check; unlike account metadata it cannot mistake identity for a usable login. */
 export function claudeVersionIsAuthenticated(version) {
     if (!isVersionInstalled('claude', version))
-        return true; // synthetic/unit plans are validated at spawn
+        return true;
     const binary = getBinaryPath('claude', version);
     if (!binary)
         return false;
@@ -914,28 +610,13 @@ export function claudeVersionIsAuthenticated(version) {
         return false;
     }
 }
-/**
- * Resolve the version/account chain for a routine the same way `agents run`
- * does: honor an explicit `version:` pin; otherwise use the configured run
- * strategy (default `balanced`) so credit-exhausted / rate-limited accounts
- * are skipped pre-flight, and synthesize a same-agent failover chain from the
- * other healthy accounts for mid-run rate limits.
- *
- * Workflows are left alone — `agents run <workflow>` owns selection.
- */
 export async function resolveRoutineLaunch(config, cwd = process.cwd(), deps = {}) {
     if (config.workflow) {
         return { chain: [], rotation: null, pinned: false };
     }
     if (config.agent && isCustomHarnessName(config.agent)) {
-        // A custom harness pins its own version/auth in the profile, so there is
-        // no version/account chain to resolve here — `agents run <name>` owns it
-        // (matching exec's "strategy ignored: custom harness pins its own
-        // version/auth").
         return { chain: [], rotation: null, pinned: false };
     }
-    // resolveRoutineLaunch is only called for agent jobs (workflow returns above;
-    // command jobs branch out of execute*Job before reaching this).
     const agent = config.agent;
     const { findAccount, findUnifiedAccount, resolveAccountSelection, resolveCredentialAccount } = await import('../account-registry.js');
     const meta = (deps.readMeta ?? readMeta)();
@@ -946,27 +627,16 @@ export async function resolveRoutineLaunch(config, cwd = process.cwd(), deps = {
         ? (explicitCredential ? config.account : undefined)
         : resolveAccountSelection(undefined, agent, meta)?.id;
     if (selectedCredential) {
-        // A default/binding may resolve to a native account — never route that
-        // through the provider credential path (it has no bundle to resolve).
         const unified = findUnifiedAccount(selectedCredential, meta);
         if (unified?.kind !== 'native')
             (deps.resolveCredentialAccount ?? resolveCredentialAccount)(selectedCredential, agent);
     }
     if (config.account && !explicitCredential) {
-        // A native routine account is named by its durable name; the version matcher
-        // keys on the identity (email/accountKey), so translate before resolving,
-        // and refuse a login that belongs to a different harness. Scope the lookup to
-        // the routine's own harness: `identityLabel` defaults to the login's email, so
-        // `account: <email>` matches every harness that identity is signed into, and
-        // un-scoped this resolved whichever row the store ordered first — then rejected
-        // it on the very next line.
         const unified = findUnifiedAccount(config.account, meta, undefined, agent);
         if (unified?.kind === 'native' && unified.agent !== agent) {
             throw new Error(`Routine '${config.name}' account '${config.account}' is a ${unified.agent} login and cannot authenticate ${agent}.`);
         }
         const identity = unified?.kind === 'native' ? unified.identityKey : config.account;
-        // Prefer the full candidate so a slot-sourced native account (shared
-        // managed-install `version`) still carries its name for `--account`.
         const accountVersion = deps.resolveAccountVersion
             ? await deps.resolveAccountVersion(agent, identity)
             : (await (deps.resolveAccountCandidate ?? resolveAccountCandidate)(agent, identity))?.version ?? null;
@@ -978,9 +648,6 @@ export async function resolveRoutineLaunch(config, cwd = process.cwd(), deps = {
                 chain: [{ agent, version: config.version ?? accountVersion }],
                 rotation: null,
                 pinned: true,
-                // Post-T5 every native slot on a harness shares the managed binary
-                // version, so the version pin is no longer enough — forward `--account`
-                // (name or `#name`) so spawn resolves the selected slot.
                 forwardAccount: true,
             };
         }
@@ -998,9 +665,6 @@ export async function resolveRoutineLaunch(config, cwd = process.cwd(), deps = {
             ...(config.account ? { forwardAccount: explicitCredential } : {}),
         };
     }
-    // A per-routine strategy travels with the definition and beats the firing
-    // box's ambient run.<agent>.strategy — otherwise selection policy silently
-    // depends on whichever device fires the job (RUSH-2719).
     const strategy = config.strategy ?? getConfiguredRunStrategy(agent, cwd);
     let version;
     let rotation = null;
@@ -1013,10 +677,6 @@ export async function resolveRoutineLaunch(config, cwd = process.cwd(), deps = {
         exhausted = resolved.exhausted;
         noVerifiedUsage = resolved.noVerifiedUsage ?? false;
         if (noVerifiedUsage) {
-            // Entirely stale usage (PHNX-2526): a routine is unattended, so there is
-            // no picker to divert to — it fails loud below rather than launch on a
-            // stale number. Do NOT log `rotation.picked` as a pick; it is the refused
-            // stale candidate, kept only for the failover chain.
             process.stderr.write(`[agents] routine ${config.name}: ${strategy} found no ${agent} account with fresh usage — refusing to route on stale data\n`);
         }
         else if (rotation) {
@@ -1044,16 +704,9 @@ export async function resolveRoutineLaunch(config, cwd = process.cwd(), deps = {
     catch (err) {
         process.stderr.write(`[agents] routine ${config.name}: strategy ${strategy} skipped: ${err.message}\n`);
     }
-    // Zero healthy accounts is NOT a "fall back to the default pin" case — that
-    // pin is exactly the exhausted account an unattended routine would hammer
-    // every tick (RUSH-2132). Throwing fails the job run (nonzero), and the
-    // message text is the contract the Factory watchdog tail-detects.
     if (exhausted) {
         throw new Error(formatNoHealthyAccountError(agent, strategy, exhausted));
     }
-    // Entirely stale usage is also NOT a "fall back to the default pin" case — the
-    // default is exactly the account whose stale number can't be trusted. Fail the
-    // run loud (NO_VERIFIED_USAGE) rather than hammer it every tick (PHNX-2526).
     if (noVerifiedUsage) {
         throw new Error(formatNoVerifiedUsageError(agent, strategy, rotation?.healthy ?? []));
     }
@@ -1094,11 +747,6 @@ export async function resolveRoutineLaunch(config, cwd = process.cwd(), deps = {
         pinned: false,
     };
 }
-/**
- * Rewrite `cmd[0]` to the absolute binary for `agent@version` when installed.
- * Bypasses the bare-name shim so a sandboxed HOME / missing default pin cannot
- * surface as "agents: no version of X configured".
- */
 export function pinJobBinary(cmd, agent, version) {
     if (!version || cmd.length === 0)
         return cmd;
@@ -1111,27 +759,6 @@ export function pinJobBinary(cmd, agent, version) {
     next[0] = binary;
     return next;
 }
-/**
- * Whether a job's command is dispatched through `agents run` (so `cmd[0] === 'agents'`)
- * rather than the agent binary directly. True for workflow jobs and for resume jobs.
- * Such commands must NOT be binary-pinned (pinning rewrites cmd[0] to the agent binary,
- * producing a broken `<binary> run …`) and must not receive a version-pinned spawn env.
- */
-/**
- * Assert a routine's account can be dispatched to the resolved placement, BEFORE
- * any off-box dispatch (placement is resolved before {@link resolveRoutineLaunch}),
- * at the top of both the foreground and detached paths:
- *
- * - **native** account → rejected for host AND cloud: a native login is a
- *   device-local harness credential that cannot be forwarded off-box.
- * - **provider** account + **cloud** → rejected (fail loud): the cloud dispatch
- *   has no secure way to inject a device-local provider bundle yet.
- * - **provider** account + **host** → allowed: the host dispatch forwards the
- *   account NAME (the remote resolves its own local bundle — no secret copied).
- *
- * `account` is injectable so the guard is unit-tested for both modes without a
- * registry or a real dispatch.
- */
 export async function assertRoutineAccountLocalForPlacement(config, mode, deps = {}) {
     if (!config.account)
         return;
@@ -1147,7 +774,6 @@ export async function assertRoutineAccountLocalForPlacement(config, mode, deps =
         throw new Error(`Routine '${config.name}' account '${config.account}' is a device-local ${account.agent} login and cannot run on a ${mode} placement. Use a provider account, or place this routine on the device that holds the login.`);
     }
     if (mode === 'cloud' && account?.kind === 'provider') {
-        // RUSH-2689: cloud+provider injection not yet implemented.
         throw new Error(`Routine '${config.name}' account '${config.account}' is a provider credential; cloud placement cannot securely inject it (RUSH-2689). Run this routine locally or on a host that holds the bundle.`);
     }
 }
@@ -1160,12 +786,6 @@ export async function dispatchPlacedJob(config, target, attempt, deps = {}) {
     }
     return (deps.cloud ?? executeJobOnCloud)(config, { detached: false }, attempt);
 }
-/**
- * Build the options passed to `dispatchPromptToHost` for a host routine. Split
- * out so the execution boundary is unit-testable: it MUST forward the routine's
- * `account` by name (the remote resolves its own local bundle; no secret copied)
- * — dropping it silently ran the remote under the wrong identity.
- */
 export function buildHostDispatchOptions(config, ctx) {
     return {
         agent: config.agent,
@@ -1174,7 +794,7 @@ export function buildHostDispatchOptions(config, ctx) {
         effort: config.effort,
         model: config.config?.model,
         account: config.account,
-        timeout: config.timeout, // enforced by the REMOTE agents run
+        timeout: config.timeout,
         remoteCwd: ctx.remoteCwd,
         name: config.name,
         cwd: ctx.runDir,
@@ -1206,11 +826,6 @@ export function mergeRoutineProviderEnv(env, config, agent) {
     Object.assign(env, resolveCredentialAccount(unified.name, agent).env);
     return env;
 }
-/**
- * Merge sandbox/base env with the canonical per-version exec env
- * (CLAUDE_CONFIG_DIR / CODEX_HOME / …) so routines share account isolation
- * with `agents run`.
- */
 export function buildRoutineSpawnEnv(baseEnv, agent, version, timezone, overlayHome) {
     const execEnv = buildExecEnv({
         agent,
@@ -1225,29 +840,9 @@ export function buildRoutineSpawnEnv(baseEnv, agent, version, timezone, overlayH
         if (v !== undefined)
             out[k] = v;
     }
-    // CLAUDE_CODE_OAUTH_TOKEN comes in two flavours, and only one is safe for a
-    // routine. KEEP a per-account `claude setup-token` (long-lived, NON-rotating,
-    // keyed to this home's own account) that buildExecEnv injected from the reserved
-    // `auth` bundle (resolveClaudeSetupToken) — that is the durable cure for the
-    // single-use-refresh-token revocation storm: a setup-token never rotates, so a
-    // scheduled routine can't land on a sibling home's just-rotated-out credential.
-    // STRIP an INHERITED ambient value instead: buildExecEnv spreads process.env
-    // (exec.ts) and sanitizeProcessEnv leaves credentials, so a daemon env that
-    // happens to carry a shared/rotating CLAUDE_CODE_OAUTH_TOKEN would otherwise make
-    // every routine run on that one token — the RUSH-1822 fleet-wide-logout path.
-    // Distinguish by value: only the resolved setup-token survives.
-    // Authoritative: buildExecEnv injects the setup-token but then spreads the caller
-    // env over it, so an ambient CLAUDE_CODE_OAUTH_TOKEN would win — re-assert here.
     const setupToken = agent === 'claude' && version
         ? resolveClaudeSetupToken(getVersionHomePath('claude', version))
         : null;
-    // A headed device (personal or desktop — the user's own interactive box or a
-    // headed always-on box) uses the per-version login for EVERY run, routines
-    // included — the setup-token is a worker-only credential (RUSH-2395, mirrors
-    // the claude adapter's headed-device branch). On a headed box, only strip an
-    // inherited copy of the account's OWN setup-token by value so a leaked ambient
-    // value can't override the login; a token the user set deliberately is a
-    // different string and survives.
     if (isHeadedDeviceRole(selfConfiguredDeviceRole())) {
         if (setupToken && out.CLAUDE_CODE_OAUTH_TOKEN === setupToken)
             delete out.CLAUDE_CODE_OAUTH_TOKEN;
@@ -1259,8 +854,6 @@ export function buildRoutineSpawnEnv(baseEnv, agent, version, timezone, overlayH
         delete out.CLAUDE_CODE_OAUTH_TOKEN;
     }
     if (agent === 'cursor' && overlayHome) {
-        // prepareJobHome links this host's Cursor auth file here. Pin XDG_CONFIG_HOME
-        // to the overlay so an ambient value cannot bypass the routine sandbox.
         out.XDG_CONFIG_HOME = path.join(overlayHome, '.config');
     }
     if (overlayHome && agent === 'claude')
@@ -1271,13 +864,7 @@ export function buildRoutineSpawnEnv(baseEnv, agent, version, timezone, overlayH
         out.TZ = timezone;
     return out;
 }
-/**
- * Spawn one attempt, capture logs to `attemptLogPath`, enforce timeout.
- * Rate-limit scanning uses only this attempt's log (not prior failover output).
- * The attempt log is also appended into `combinedLogPath` for a continuous trail.
- */
 function spawnJobAttempt(cmd, env, attemptLogPath, timeoutMs, combinedLogPath, cwd = os.homedir()) {
-    // Isolate this attempt's output so detectRateLimit never sees prior attempts.
     fs.writeFileSync(attemptLogPath, '', { mode: 0o600 });
     const stdoutFd = fs.openSync(attemptLogPath, 'a', 0o600);
     return new Promise((resolve) => {
@@ -1294,17 +881,17 @@ function spawnJobAttempt(cmd, env, attemptLogPath, timeoutMs, combinedLogPath, c
             try {
                 fs.closeSync(stdoutFd);
             }
-            catch { /* fd already closed */ }
+            catch { }
             let logText = '';
             try {
                 logText = fs.readFileSync(attemptLogPath, 'utf-8');
             }
-            catch { /* missing log */ }
+            catch { }
             if (combinedLogPath) {
                 try {
                     fs.appendFileSync(combinedLogPath, logText);
                 }
-                catch { /* best-effort trail */ }
+                catch { }
             }
             resolve({ ...result, logText });
         };
@@ -1313,13 +900,13 @@ function spawnJobAttempt(cmd, env, attemptLogPath, timeoutMs, combinedLogPath, c
                 if (child.pid)
                     process.kill(-child.pid, 'SIGTERM');
             }
-            catch { /* process already exited */ }
+            catch { }
             setTimeout(() => {
                 try {
                     if (child.pid)
                         process.kill(-child.pid, 'SIGKILL');
                 }
-                catch { /* process already exited */ }
+                catch { }
             }, 5000);
             finish({
                 exitCode: null,
@@ -1350,51 +937,18 @@ function spawnJobAttempt(cmd, env, attemptLogPath, timeoutMs, combinedLogPath, c
         child.unref();
     });
 }
-/**
- * Execute a job synchronously (waits for completion or timeout before resolving).
- *
- * When `config.loop` is set the job is routed through the loop driver (`runLoop`
- * from loop.ts) instead of a single spawn — same driver as `agents run --loop` and
- * workflow `loop:` blocks (issue #400). The optional `deps` parameter provides
- * injectable seams (runIteration, sleep, writeCheckpoint) used by tests; production
- * callers omit it and get the defaults.
- *
- * Single-shot path: pre-flight version/account selection + mid-run rate-limit
- * failover across healthy same-agent accounts (RUSH-1016).
- */
-/**
- * Actor provenance for a routine run (RUSH-2020): `actor` is the routine's
- * CREATOR (carried from the job config), `triggeredBy` is whoever kicked off THIS
- * run (`resolveActor().id` — a person for a manual run, `UNRESOLVED@<host>` for an
- * unattended scheduled fire). Spread into every RunMeta so a fired cron traces
- * back to the person who scheduled it.
- */
 function runProvenance(config) {
     return { ...(config.actor ? { actor: config.actor } : {}), triggeredBy: resolveActor().id };
 }
-/**
- * Inject the routine creator's actor into a run's base env so the fired agent
- * INHERITS it (the `AGENTS_ACTOR` path in actor.ts) instead of re-resolving to
- * `UNRESOLVED@<host>` on an unattended fire — so its session, events, and commits
- * all attribute to the person who scheduled the routine (RUSH-2020). Mutates and
- * returns the same env object for call-site brevity.
- */
 function injectRoutineActor(env, config) {
     if (config.actor && !env.AGENTS_ACTOR)
         env.AGENTS_ACTOR = config.actor;
     return env;
 }
 export async function executeJob(config, deps, trigger = { kind: 'manual' }) {
-    // Unified attempt: allocate + persist the run record (or a terminal blocked/
-    // skipped record) BEFORE placement, version selection, sandbox, or preflight —
-    // and hold the active-run claim so a manual run cannot overlap a scheduled one.
     return runWithAttempt(config, trigger, (attempt) => executeJobPlaced(config, deps, attempt), (meta) => ({ meta, reportPath: null }));
 }
 async function executeJobPlaced(config, deps, attempt) {
-    // Placement (hostStrategy / bare host:) — body may run on another machine
-    // over SSH or in the cloud; local version selection / sandbox / spawn then
-    // do not apply. Sync callers (manual `routines run`, catchup) follow the
-    // remote run to completion when possible.
     {
         const { resolvePlacementTarget } = await import('../routines-placement.js');
         const target = await resolvePlacementTarget(config);
@@ -1402,9 +956,6 @@ async function executeJobPlaced(config, deps, attempt) {
         if (placed)
             return placed;
     }
-    // Command-mode: run a plain shell command directly (no agent, no rotation,
-    // no pinning, no sandbox overlay). Reuses the run-record machinery so
-    // list/runs/overdue keep working.
     if (config.command) {
         return executeCommandJobForeground(config, attempt);
     }
@@ -1419,14 +970,6 @@ async function executeJobPlaced(config, deps, attempt) {
         schedule: config.schedule,
     });
     const resolvedPrompt = resolveJobPrompt(config);
-    // Resume must run against the REAL home: `--resume <id>` resolves the session from
-    // the agent's config dir, and the sandbox overlay home has only a freshly-generated
-    // config with no session store. So a resume job is never sandboxed, regardless of
-    // `config.sandbox` (see the resume branch in buildJobCommand).
-    // Resume needs the REAL home (session store); a custom harness needs it too —
-    // the delegated `agents run <name>` resolves ~/.agents (profiles, setup
-    // sentinel, version homes) from HOME, which the overlay would hide. Exec
-    // still isolates the run in the host version home it swaps HOME into.
     const useSandbox = config.sandbox !== false && !config.resume && !(config.agent && isCustomHarnessName(config.agent));
     const overlayHome = useSandbox ? prepareJobHome(config, primaryVersion) : undefined;
     const runId = attempt.runId;
@@ -1435,13 +978,6 @@ async function executeJobPlaced(config, deps, attempt) {
     const baseEnv = injectRoutineActor(useSandbox
         ? buildSpawnEnv(overlayHome, config.env)
         : { ...process.env }, config);
-    // Workflows run via `agents run <workflow>` which delegates to claude under the hood.
-    // Use 'claude' as the effective agent for report extraction and metadata when workflow is set.
-    // (command jobs branched out earlier, so config.agent is set on the non-workflow path.)
-    // Custom harness/profile name (e.g. `deepseek`) stays on harnessName; the
-    // HOST CLI is effectiveAgent. The loop path spawns in-process via runLoop
-    // and never re-enters `agents run`, so it must stamp harnessName itself
-    // (PHNX-2935) — same field commands/exec.ts sets on ExecOptions.
     const harnessName = !config.workflow && config.agent && isCustomHarnessName(config.agent)
         ? config.agent
         : undefined;
@@ -1470,17 +1006,8 @@ async function executeJobPlaced(config, deps, attempt) {
         exitCode: null,
     };
     writeRunMeta(meta);
-    // Baseline the child's transcript dirs BEFORE spawning so archiveRoutineTranscripts
-    // copies only THIS run's transcript out of a shared per-version home (RUSH-2271).
     snapshotRoutineTranscriptBase(meta, runDir, overlayHome);
-    // Auth preflight: if the resolved account is provably signed out (revoked or
-    // unconfigured), record a terminal `blocked`/`agent_auth_failed` run with the
-    // re-login repair instead of spawning a doomed run that 401s and burns a
-    // session (PHNX-3415). `blocked` (readiness rejection, no body ran) is kept
-    // distinct from `failed` (a body ran and errored) per RT-7. Cache-only + fails
-    // OPEN — see fireTimeAuthReadiness.
     const preflightVersion = launch.chain[0]?.version;
-    // Dynamic import breaks the routine-readiness -> scheduling/routines -> runner cycle.
     const { fireTimeAuthReadiness } = await import('../routine-readiness.js');
     const authBlocker = preflightVersion ? fireTimeAuthReadiness(effectiveAgent, preflightVersion) : null;
     if (authBlocker) {
@@ -1493,14 +1020,11 @@ async function executeJobPlaced(config, deps, attempt) {
         return { meta, reportPath: null };
     }
     const timeoutMs = parseTimeout(config.timeout) || 10 * 60 * 1000;
-    // Loop path: delegate to runLoop (same driver as `agents run --loop` / workflow loop:).
     if (config.loop) {
         const spawnEnv = buildRoutineSpawnEnv(baseEnv, effectiveAgent, primaryVersion, config.timezone, overlayHome);
         const execOptions = {
             agent: effectiveAgent,
             harnessName,
-            // Routine-supported self-updating CLIs (Cursor/Droid) use one global
-            // binary; a versioned shim would point at a nonexistent isolated install.
             version: isSelfUpdatingAgent(effectiveAgent) ? undefined : primaryVersion,
             prompt: resolvedPrompt,
             mode: normalizeMode(config.mode),
@@ -1531,11 +1055,8 @@ async function executeJobPlaced(config, deps, attempt) {
         archiveRoutineTranscripts(meta, runDir, overlayHome);
         return { meta, reportPath: null };
     }
-    // Single-shot path: build the command once, then walk the launch chain on
-    // rate/usage-limit failures (same detectRateLimit patterns as agents run).
     const baseCmd = buildJobCommand(config, resolvedPrompt, launch.forwardAccount !== false);
     const stdoutPath = path.join(runDir, 'stdout.log');
-    // Truncate the log for a clean run; failover attempts append.
     fs.writeFileSync(stdoutPath, '', { mode: 0o600 });
     const chain = launch.chain.length > 0
         ? launch.chain
@@ -1549,11 +1070,6 @@ async function executeJobPlaced(config, deps, attempt) {
         if (i === 0) {
             process.stderr.write(`[agents] routine ${config.name}: running ${label}\n`);
         }
-        // A rate-limit failover spawns the NEXT chain entry, whose version/account has
-        // its own per-version transcript home. Re-point meta.version at the attempt that
-        // is about to run and re-baseline that home, so the archiver reads the transcript
-        // where THIS attempt writes it — not chain[0]'s home (RUSH-2271). The pre-loop
-        // snapshot already covered chain[0]; this makes every later attempt correct too.
         meta.version = attemptVersion;
         snapshotRoutineTranscriptBase(meta, runDir, overlayHome);
         const viaAgentsRun = dispatchesViaAgentsRun(config);
@@ -1570,7 +1086,6 @@ async function executeJobPlaced(config, deps, attempt) {
                 return e;
             })()
             : buildRoutineSpawnEnv(baseEnv, attemptAgent, attemptVersion, config.timezone, overlayHome);
-        // Remaining timeout budget shared across failover attempts.
         const elapsed = Date.now() - Date.parse(meta.startedAt);
         const remaining = Math.max(1_000, timeoutMs - (Number.isFinite(elapsed) ? elapsed : 0));
         const attemptLogPath = path.join(runDir, `stdout.attempt-${i}.log`);
@@ -1586,24 +1101,15 @@ async function executeJobPlaced(config, deps, attempt) {
             return { meta, reportPath };
         }
         if (attempt.status === 'completed') {
-            // Exit code alone is unreliable for auth: a logged-out Claude can exit 0
-            // with a `result` event carrying is_error:true (terminal_reason
-            // "completed"). Consult the SAME structural signal the detached path uses
-            // so both paths agree — raw text is deliberately NOT used here, so a
-            // genuinely-completed run that merely mentions an auth phrase stays a
-            // success (processFailed:false).
             if (isAuthFailureFromLog(attempt.logText, effectiveAgent, { processFailed: false })) {
                 const reason = authFailureReason(attempt.logText) ?? 'authentication_failed';
                 recordRoutineAuthOutcome(attemptAgent, config.account, attemptVersion, { ok: false, verdict: 'revoked', detail: reason });
                 finalizeRunMeta(meta, 'failed', attempt.exitCode ?? 1, { errorMessage: `auth_failed: ${reason}` });
                 writeRunMeta(meta);
                 timer.end({ status: 'failed', exitCode: meta.exitCode ?? undefined, runId, error: `auth_failed: ${reason}` });
-                // Never persist the login-error text as the report.
                 archiveRoutineTranscripts(meta, runDir, overlayHome);
                 return { meta, reportPath: null };
             }
-            // A clean routine completion is real auth evidence — record it so a worker's
-            // token reads `last used ok` and a stale failure fact is cleared (PHNX-4116).
             recordRoutineAuthOutcome(attemptAgent, config.account, attemptVersion, { ok: true });
             finalizeRunMeta(meta, 'completed', 0);
             writeRunMeta(meta);
@@ -1612,7 +1118,6 @@ async function executeJobPlaced(config, deps, attempt) {
             archiveRoutineTranscripts(meta, runDir, overlayHome);
             return { meta, reportPath };
         }
-        // Failed — cascade only on rate/usage limit when more chain entries remain.
         const isLast = i === chain.length - 1;
         const rateLimited = detectRateLimit(attempt.logText) || (attempt.error ? detectRateLimit(attempt.error) : false);
         if (!isLast && rateLimited) {
@@ -1622,11 +1127,6 @@ async function executeJobPlaced(config, deps, attempt) {
             fs.appendFileSync(stdoutPath, `\n[agents] ${label} hit rate/usage limit — failover → ${nextLabel}\n`);
             continue;
         }
-        // Auth failure — the agent is logged out / token revoked. Unlike a rate
-        // limit it is not self-healing by failover (every chain entry on the same
-        // account fails identically), so rate-limit is classified first (above) and
-        // auth only when NOT rate-limited. Classified so the failure is visible and,
-        // critically, so the login-error text is never persisted as the report.
         const authFailed = !rateLimited && (isAuthFailureFromLog(attempt.logText, effectiveAgent, { processFailed: true }) ||
             (attempt.error ? detectAuthFailure(attempt.error) : false));
         if (attempt.error) {
@@ -1650,24 +1150,15 @@ async function executeJobPlaced(config, deps, attempt) {
             runId,
             ...(failureErrorMessage ? { error: failureErrorMessage } : {}),
         });
-        // On auth failure the last assistant text IS the login error — never persist
-        // it as report.md; it would otherwise be injected into the next run's prompt
-        // via {last_report}.
         const reportPath = authFailed ? null : extractAndSaveReport(stdoutPath, effectiveAgent, runDir);
         archiveRoutineTranscripts(meta, runDir, overlayHome);
         return { meta, reportPath };
     }
-    // Unreachable: chain is always non-empty, but keep a safe fallback.
     finalizeRunMeta(meta, 'failed', 1);
     writeRunMeta(meta);
     timer.end({ status: 'failed', exitCode: 1, runId });
     return { meta, reportPath: null };
 }
-/**
- * Dispatch a routine to the agent's native cloud provider (or the configured
- * default). Writes a local run record with `cloudTaskId` so list/runs still
- * work; does not wait for cloud completion on the detached path.
- */
 async function executeJobOnCloud(config, opts, attempt) {
     if (config.workflow) {
         throw new Error(`Routine '${config.name}' runs a workflow bundle, which can't execute in the cloud yet — remove 'hostStrategy: cloud' or 'workflow:'.`);
@@ -1720,20 +1211,15 @@ async function executeJobOnCloud(config, opts, attempt) {
         try {
             insertTask(task);
         }
-        catch { /* store is best-effort */ }
+        catch { }
         meta.cloudTaskId = task.id;
         meta.cloudProvider = task.provider;
-        // Terminal cloud responses (e.g. antigravity) finalize immediately.
-        // Async providers leave the run `running` with the cloud task id for
-        // the user to follow via `agents cloud status`.
         if (task.status === 'completed') {
             finalizeRunMeta(meta, 'completed', 0);
         }
         else if (task.status === 'failed' || task.status === 'cancelled') {
             finalizeRunMeta(meta, 'failed', 1, { errorMessage: task.summary ?? `cloud ${task.status}` });
         }
-        // Non-terminal statuses stay `running` for both detached and sync paths;
-        // the user follows via `agents cloud status <id>`.
         writeRunMeta(meta);
         timer.end({ status: meta.status, exitCode: meta.exitCode ?? undefined, runId });
         return { meta, reportPath: null };
@@ -1779,7 +1265,7 @@ async function executeJobOnHost(config, opts, attempt) {
         ...runProvenance(config),
         ...attempt.stamp,
         agent: config.agent,
-        pid: null, // no local process — the run lives on the host
+        pid: null,
         spawnedAt: Date.now(),
         status: 'running',
         startedAt: new Date().toISOString(),
@@ -1790,8 +1276,6 @@ async function executeJobOnHost(config, opts, attempt) {
     writeRunMeta(meta);
     const { task, exitCode } = await dispatchPromptToHost(host, buildHostDispatchOptions(config, { remoteCwd, runDir, detached: opts.detached }));
     meta.hostTaskId = task.id;
-    // Sync path: a real exit code finalizes now. -1 (follow window closed) and
-    // the detached path leave the meta `running` for the monitor to reconcile.
     if (!opts.detached && exitCode !== null && exitCode !== undefined && exitCode !== -1) {
         finalizeRunMeta(meta, exitCode === 0 ? 'completed' : 'failed', exitCode);
     }
@@ -1799,7 +1283,6 @@ async function executeJobOnHost(config, opts, attempt) {
     timer.end({ status: meta.status, exitCode: meta.exitCode ?? undefined, runId });
     return { meta, reportPath: null };
 }
-/** Spawn a job as a detached process and return immediately with run metadata. */
 async function executeCommandJobForeground(config, attempt) {
     const timer = createTimer('agent.run', {
         jobName: config.name,
@@ -1845,7 +1328,7 @@ async function executeCommandJobForeground(config, attempt) {
             try {
                 fs.closeSync(stdoutFd);
             }
-            catch { /* fd already closed */ }
+            catch { }
             resolve(r);
         };
         const timeoutTimer = setTimeout(() => {
@@ -1853,13 +1336,13 @@ async function executeCommandJobForeground(config, attempt) {
                 if (child.pid)
                     process.kill(-child.pid, 'SIGTERM');
             }
-            catch { /* process already exited */ }
+            catch { }
             setTimeout(() => {
                 try {
                     if (child.pid)
                         process.kill(-child.pid, 'SIGKILL');
                 }
-                catch { /* process already exited */ }
+                catch { }
             }, 5000);
             finish({ exitCode: null, status: 'timeout' });
         }, timeoutMs);
@@ -1885,25 +1368,18 @@ async function executeCommandJobForeground(config, attempt) {
     });
     return { meta, reportPath: null };
 }
-/** Invoke a lifecycle hook without letting a caller error break run finalization. */
 function safeHook(fn) {
     if (!fn)
         return;
     try {
         fn();
     }
-    catch { /* hooks are best-effort */ }
+    catch { }
 }
-/** Spawn a job as a detached process and return immediately with run metadata. */
 export async function executeJobDetached(config, hooks, trigger = { kind: 'manual' }) {
     return runWithAttempt(config, trigger, (attempt) => executeJobDetachedClaimed(config, attempt, hooks), (meta) => meta);
 }
 async function executeJobDetachedClaimed(config, attempt, hooks) {
-    // Placement (hostStrategy / bare host:) — dispatch off-box and return; the
-    // monitor finalizes host: runs, cloud runs stay terminal when dispatch ends.
-    // Either way the in-process onFinish hook does not fire for off-box routines
-    // (the monitor tick observes an already-finalized record), so notify-desktop
-    // sends the finish notification only for local detached runs below (RUSH-2030).
     {
         const { resolvePlacementTarget } = await import('../routines-placement.js');
         const target = await resolvePlacementTarget(config);
@@ -1923,15 +1399,9 @@ async function executeJobDetachedClaimed(config, attempt, hooks) {
             return meta;
         }
     }
-    // Command-mode: fire a plain shell command detached (no agent, no rotation,
-    // no pinning, no sandbox overlay). Still writes a run record so the daemon,
-    // list/runs, and overdue tracking keep working.
     if (config.command) {
         return executeCommandJobDetached(config, attempt, hooks);
     }
-    // Pre-flight: pick a healthy version/account so the daemon does not launch
-    // into a credit-exhausted install. Detached cannot mid-run failover (no exit
-    // wait); the next schedule tick re-selects if this attempt still fails.
     const launch = await resolveRoutineLaunch(config);
     const version = launch.chain[0]?.version ?? config.version;
     const timer = createTimer('agent.run', {
@@ -1944,19 +1414,9 @@ async function executeJobDetachedClaimed(config, attempt, hooks) {
     });
     const resolvedPrompt = resolveJobPrompt(config);
     let cmd = buildJobCommand(config, resolvedPrompt, launch.forwardAccount !== false);
-    // workflow AND resume dispatch through `agents run` — never binary-pin them (pinning
-    // rewrites cmd[0] to the agent binary → broken `<binary> run …`).
     if (!dispatchesViaAgentsRun(config) && version && config.agent) {
         cmd = pinJobBinary(cmd, config.agent, version);
     }
-    // Resume must run against the REAL home: `--resume <id>` resolves the session from
-    // the agent's config dir, and the sandbox overlay home has only a freshly-generated
-    // config with no session store. So a resume job is never sandboxed, regardless of
-    // `config.sandbox` (see the resume branch in buildJobCommand).
-    // Resume needs the REAL home (session store); a custom harness needs it too —
-    // the delegated `agents run <name>` resolves ~/.agents (profiles, setup
-    // sentinel, version homes) from HOME, which the overlay would hide. Exec
-    // still isolates the run in the host version home it swaps HOME into.
     const useSandbox = config.sandbox !== false && !config.resume && !(config.agent && isCustomHarnessName(config.agent));
     const overlayHome = useSandbox ? prepareJobHome(config, version) : undefined;
     const runId = attempt.runId;
@@ -1975,10 +1435,8 @@ async function executeJobDetachedClaimed(config, attempt, hooks) {
                 e.TZ = config.timezone;
             return e;
         })()
-        // Non-command path only: config.agent is always set here (command/workflow branch earlier).
         : buildRoutineSpawnEnv(baseEnv, config.agent, version, config.timezone, overlayHome);
     // RUSH-2860: if this host holds gh auth, the sandbox child MUST see it —
-    // otherwise monitors runs records ok while every gh call inside fails.
     if (useSandbox)
         assertSandboxForwardsHostGhAuth(spawnEnv);
     const effectiveAgent = config.workflow
@@ -2002,15 +1460,8 @@ async function executeJobDetachedClaimed(config, attempt, hooks) {
         completedAt: null,
         exitCode: null,
     };
-    // Baseline the child's transcript dirs BEFORE spawning so archiveRoutineTranscripts
-    // copies only THIS run's transcript out of a shared per-version home (RUSH-2271).
     snapshotRoutineTranscriptBase(meta, runDir, overlayHome);
-    // Auth preflight (mirrors executeJob): a provably signed-out resolved account
-    // records a terminal `blocked`/`agent_auth_failed` run with the re-login repair
-    // instead of spawning a doomed run that 401s and burns a session (PHNX-3415).
-    // Cache-only + fails OPEN — see fireTimeAuthReadiness.
     const preflightVersion = launch.chain[0]?.version;
-    // Dynamic import breaks the routine-readiness -> scheduling/routines -> runner cycle.
     const { fireTimeAuthReadiness } = await import('../routine-readiness.js');
     const authBlocker = preflightVersion ? fireTimeAuthReadiness(effectiveAgent, preflightVersion) : null;
     if (authBlocker) {
@@ -2018,7 +1469,7 @@ async function executeJobDetachedClaimed(config, attempt, hooks) {
         try {
             fs.closeSync(stdoutFd);
         }
-        catch { /* already closed */ }
+        catch { }
         meta.readiness = authBlocker;
         finalizeRunMeta(meta, 'blocked', null, { errorMessage: `blocked: ${authBlocker.code} — ${authBlocker.message}` });
         writeRunMeta(meta);
@@ -2042,14 +1493,10 @@ async function executeJobDetachedClaimed(config, attempt, hooks) {
         finalizeRunMeta(meta, status, exitCode, errorMessage ? { errorMessage } : undefined);
         writeRunMeta(meta);
         archiveRoutineTranscripts(meta, runDir, overlayHome);
-        // Never persist the report on an auth failure — the last assistant text is
-        // the login error, which would poison the next run's {last_report} prompt.
         const isAuthFailure = !!errorMessage && errorMessage.startsWith('auth_failed:');
         if (status !== 'timeout' && !isAuthFailure)
             extractAndSaveReport(stdoutPath, effectiveAgent, runDir);
         timer.end({ status, exitCode: exitCode ?? undefined, runId, ...(errorMessage ? { error: errorMessage } : {}) });
-        // Fire the finish/output notification AFTER the report is written so the hook
-        // can read report.md (RUSH-2030). Best-effort; never breaks finalization.
         safeHook(hooks?.onFinish ? () => hooks.onFinish(meta) : undefined);
     };
     timeoutTimer = setTimeout(() => {
@@ -2061,10 +1508,7 @@ async function executeJobDetachedClaimed(config, attempt, hooks) {
         try {
             logText = fs.readFileSync(stdoutPath, 'utf-8');
         }
-        catch { /* log unreadable */ }
-        // processFailed gates the raw-text fallback so a COMPLETED run (exit 0) that
-        // merely mentions an auth phrase is never misclassified; the structural
-        // marker still catches an exit-0 auth failure on its own.
+        catch { }
         if (isAuthFailureFromLog(logText, effectiveAgent, { processFailed: (code ?? 1) !== 0 })) {
             const reason = authFailureReason(logText) ?? 'authentication_failed';
             recordRoutineAuthOutcome(effectiveAgent, config.account, meta.version, { ok: false, verdict: 'revoked', detail: reason });
@@ -2073,7 +1517,6 @@ async function executeJobDetachedClaimed(config, attempt, hooks) {
         }
         const inferred = inferFinalStatusFromLog(stdoutPath, effectiveAgent);
         const finalStatus = inferred ? inferred.status : (code === 0 ? 'completed' : 'failed');
-        // A clean completion clears any stale auth-failure fact for this account.
         if (finalStatus === 'completed')
             recordRoutineAuthOutcome(effectiveAgent, config.account, meta.version, { ok: true });
         if (inferred) {
@@ -2087,7 +1530,7 @@ async function executeJobDetachedClaimed(config, attempt, hooks) {
         try {
             fs.closeSync(stdoutFd);
         }
-        catch { /* fd already closed */ }
+        catch { }
         settle('failed', 1, err.message);
         process.stderr.write(`[agents] daemon: spawn failed for job "${config.name}": ${err.message}\n`);
     });
@@ -2095,17 +1538,11 @@ async function executeJobDetachedClaimed(config, attempt, hooks) {
     try {
         fs.closeSync(stdoutFd);
     }
-    catch { /* fd already closed */ }
+    catch { }
     meta.pid = child.pid || null;
     writeRunMeta(meta);
     return { ...meta };
 }
-/**
- * Detached (fire-and-forget) execution for a command-mode routine. Mirrors the
- * agent detached flow: write an initial running record, spawn the shell command
- * un-sandboxed, unref, then record the pid. The daemon does not wait for exit;
- * `monitorRunningJobs` reaps the record on the next tick.
- */
 function executeCommandJobDetached(config, attempt, hooks) {
     const timer = createTimer('agent.run', {
         jobName: config.name,
@@ -2117,14 +1554,7 @@ function executeCommandJobDetached(config, attempt, hooks) {
     fs.mkdirSync(runDir, { recursive: true });
     const stdoutPath = path.join(runDir, 'stdout.log');
     const stdoutFd = fs.openSync(stdoutPath, 'w', 0o600);
-    // Wrap the shell so the child records its own exit code to <runDir>/exit-code.
-    // The in-process `child.on('exit')` below writes the terminal record while the
-    // daemon is alive (the common case); the file lets monitorRunningJobs recover
-    // the real status if the daemon restarted between spawn and exit. (win32 relies
-    // on the exit event only.)
     const exitCodePath = path.join(runDir, 'exit-code');
-    // Run the command in a SUBSHELL `( … )` so that if it calls `exit`, only the
-    // subshell exits — the outer shell still captures `$?` and writes the file.
     const wrappedCommand = wrapCommandRoutine(config.command);
     const cmd = process.platform === 'win32'
         ? buildShellCommand(wrappedCommand)
@@ -2150,9 +1580,6 @@ function executeCommandJobDetached(config, attempt, hooks) {
         ...backgroundSpawnOptions({ cwd: routineSpawnCwd(config), fdStdio: true }),
         env,
     });
-    // Record the real terminal status ourselves — the daemon stays alive after this
-    // fire-and-forget call, so the exit event fires here. (monitorRunningJobs no
-    // longer force-fails command jobs; it reads exit-code only on the restart edge.)
     let settled = false;
     let timeoutTimer;
     const settle = (status, exitCode, errorMessage) => {
@@ -2164,8 +1591,6 @@ function executeCommandJobDetached(config, attempt, hooks) {
         finalizeRunMeta(meta, status, exitCode, errorMessage ? { errorMessage } : undefined);
         writeRunMeta(meta);
         timer.end({ status, exitCode: exitCode ?? undefined, runId, ...(errorMessage ? { error: errorMessage } : {}) });
-        // Finish notification (RUSH-2030). For command routines the threshold only
-        // surfaces failures, decided in routine-notify.ts. Best-effort.
         safeHook(hooks?.onFinish ? () => hooks.onFinish(meta) : undefined);
     };
     timeoutTimer = setTimeout(() => {
@@ -2181,7 +1606,7 @@ function executeCommandJobDetached(config, attempt, hooks) {
     try {
         fs.closeSync(stdoutFd);
     }
-    catch { /* fd already closed */ }
+    catch { }
     meta.pid = child.pid || null;
     writeRunMeta(meta);
     return { ...meta };
@@ -2202,7 +1627,6 @@ function extractAndSaveReport(stdoutPath, agentType, runDir) {
     }
     return null;
 }
-/** Extract the final assistant message from a stream-JSON log file as a markdown report. */
 export function extractReport(stdoutPath, agentType) {
     if (!fs.existsSync(stdoutPath))
         return null;
@@ -2230,7 +1654,7 @@ export function extractReport(stdoutPath, agentType) {
                     }
                 }
             }
-            catch { /* malformed JSONL line */ }
+            catch { }
         }
         return lastMessage || null;
     }
@@ -2238,20 +1662,12 @@ export function extractReport(stdoutPath, agentType) {
         return null;
     }
 }
-/** Derive the final status of a detached run by reading the agent's stream-json
- *  tail. Detached children fire-and-forget, so we never see their exit code
- *  directly — but Claude's stream-json terminates with a `type: result` line
- *  that carries `is_error`. If we find it, the run completed cleanly (modulo
- *  agent-reported error). If not, the process likely died mid-stream and the
- *  caller should treat the run as failed. */
 export function inferFinalStatusFromLog(stdoutPath, agent) {
     if (!fs.existsSync(stdoutPath))
         return null;
     try {
         const content = fs.readFileSync(stdoutPath, 'utf-8');
         const lines = content.split('\n').filter((l) => l.trim());
-        // Walk backwards over the last few lines — the result marker is always
-        // at the tail. Cap the scan so a huge stdout doesn't iterate forever.
         for (let i = lines.length - 1, scanned = 0; i >= 0 && scanned < 20; i--, scanned++) {
             try {
                 const parsed = JSON.parse(lines[i]);
@@ -2262,7 +1678,6 @@ export function inferFinalStatusFromLog(stdoutPath, agent) {
                 }
             }
             catch {
-                // malformed JSONL line — keep scanning
             }
         }
         return null;
@@ -2272,19 +1687,7 @@ export function inferFinalStatusFromLog(stdoutPath, agent) {
     }
 }
 const MAX_WALL_CLOCK_MS = 24 * 60 * 60 * 1000;
-/**
- * Verify that a PID still belongs to the process we spawned, not a recycled
- * OS PID. Uses the recorded `spawnedAt` (epoch ms) from meta.json and
- * compares against the process's actual start time via `ps`. Returns true
- * when the PID is alive AND plausibly ours.
- */
-/** Bound the identity `ps` — a hung `ps` must never freeze its caller for long (matches routine-process-cleanup's probe). */
 const PS_IDENTITY_TIMEOUT_MS = 5_000;
-/**
- * Pure: does a `ps -o etime=` value place the process's birth within 30s of when
- * we recorded spawning it? An empty/unknown reading conservatively reads as ours
- * — never reap a run on a doubtful identity probe.
- */
 function etimeIndicatesOurs(etime, spawnedAt) {
     if (!etime)
         return true;
@@ -2301,17 +1704,6 @@ function etimeIndicatesOurs(etime, spawnedAt) {
     const processStartMs = Date.now() - uptimeSec * 1000;
     return Math.abs(processStartMs - spawnedAt) < 30_000;
 }
-/**
- * Synchronous identity check for callers OTHER than the periodic heartbeat tick:
- * the `agents routines list/status` builders and stop-time enumeration (both in
- * short-lived CLI processes), plus the scheduler's fire-time slot-claim
- * (`activeRoutineRun`) and status projection (`isRunGenuinelyInFlight`). Those
- * last two DO run in-process on the daemon's event loop, but are event-driven
- * (they fire when a job is dispatched, not on a fixed cadence) and the `ps` here
- * is now bounded to {@link PS_IDENTITY_TIMEOUT_MS} — they are not the
- * unconditional every-tick scan PHNX-3695 targets. The heartbeat tick's own scan
- * uses the non-blocking {@link isPidOursAsync} instead.
- */
 function isPidOurs(pid, spawnedAt) {
     try {
         process.kill(pid, 0);
@@ -2331,13 +1723,6 @@ function isPidOurs(pid, spawnedAt) {
         return true;
     }
 }
-/**
- * Async, deadline-bounded twin of {@link isPidOurs} for the daemon's heartbeat
- * tick (`reapExitedRunningJobs`) — the `ps` probe runs on the shared event loop,
- * so it MUST NOT block it (PHNX-3695). Same semantics: dead pid → not ours;
- * no recorded `spawnedAt` or Windows → assume ours; a failed/empty probe reads
- * as ours (conservative — never reap on a doubtful probe).
- */
 async function isPidOursAsync(pid, spawnedAt) {
     if (!isAlive(pid))
         return false;
@@ -2347,23 +1732,10 @@ async function isPidOursAsync(pid, spawnedAt) {
         return true;
     const res = await execFileBounded('ps', ['-p', String(pid), '-o', 'etime='], { timeoutMs: PS_IDENTITY_TIMEOUT_MS });
     if (res.code !== 0)
-        return true; // probe failed → keep the run, same as the sync catch
+        return true;
     return etimeIndicatesOurs(res.stdout.trim(), spawnedAt);
 }
-/**
- * Finalize one `host:`-placed run by healing its host-task sidecar against the
- * remote `.exit` (lib/hosts/reconcile.ts). Mutates + persists the meta only
- * when the sidecar reached a terminal state.
- */
-/** Apply a healed host-task's terminal state to the local run record. Shared by the sync and async host reconcilers. */
-function applyHealedHostRun(meta, healed, 
-// The routine-end emit acquires the event-log file lock. On the daemon
-// heartbeat tick (finalizeHostRunAsync) that MUST be the async, non-blocking
-// variant, or the synchronous `withFileLock` (lockSync + Atomics.wait, up to
-// 30s under contention) freezes the whole event loop — the exact wedge PHNX-3695
-// targets, on a path guard-no-sync-io does not scan (PHNX-3727). The sync CLI
-// path (finalizeHostRun) keeps the default synchronous emit.
-emit = emitRoutineEnd) {
+function applyHealedHostRun(meta, healed, emit = emitRoutineEnd) {
     if (healed.status !== 'completed' && healed.status !== 'failed')
         return;
     finalizeRunMeta(meta, healed.status, healed.exitCode ?? (healed.status === 'completed' ? 0 : 1), { completedAt: healed.finishedAt ?? undefined });
@@ -2377,35 +1749,17 @@ function finalizeHostRun(meta) {
             return;
         applyHealedHostRun(meta, reconcileHostTask(task));
     }
-    catch { /* unreachable host or unreadable sidecar — retry next sweep */ }
+    catch { }
 }
-/**
- * Async twin of {@link finalizeHostRun} for the daemon heartbeat tick
- * (PHNX-3695). A `host:`-placed run's remote `.exit` is read over ssh; on the
- * tick that read MUST be async (`reconcileHostTaskAsync` → `sshExecAsync`) or a
- * single 6s ssh timeout freezes the whole event loop — the exact bug class this
- * effort targets, worse than the local `ps` probe.
- */
 async function finalizeHostRunAsync(meta) {
     try {
         const task = loadHostTask(meta.hostTaskId);
         if (!task)
             return;
-        // Tick path: emit through the async, non-blocking file lock (PHNX-3727).
         applyHealedHostRun(meta, await reconcileHostTaskAsync(task), (m) => { void emitRoutineEndAsync(m); });
     }
-    catch { /* unreachable host or unreadable sidecar — retry next sweep */ }
+    catch { }
 }
-/**
- * PIDs of the in-flight detached routine children on THIS device — every local
- * run record still marked `running` whose spawned process is genuinely alive
- * (`isPidOurs`, so a dead-and-reused pid does not count). These are the `unref`'d
- * spawns that survive a daemon exit in their own process group (SING-11a): a
- * takeover must not kill them and `stopDaemon` reports them rather than pretending
- * the process tree is clean (SING-12). Scoped to `getRunsDir()`, which is under
- * this state dir's HOME, so a different state dir's children are invisible here.
- * `host:`-placed runs have no local pid and are excluded.
- */
 export function listLiveRoutineChildren() {
     const runsDir = getRunsDir();
     if (!fs.existsSync(runsDir))
@@ -2438,25 +1792,11 @@ export function listLiveRoutineChildren() {
                 if (isPidOurs(meta.pid, meta.spawnedAt))
                     pids.push(meta.pid);
             }
-            catch { /* unreadable/partial record — skip */ }
+            catch { }
         }
     }
     return pids;
 }
-/**
- * Whether a run record marked `running` is genuinely in flight right now. A
- * `running` status alone is not enough: `writeActiveClaim` stamps a provisional
- * claim as `running` with `pid: null` BEFORE the child spawns, and
- * `monitorRunningJobs()` does not reap a null-pid record (it has no process to
- * probe, and ages it out only past the configured timeout — up to a week). So a
- * daemon crash in that spawn window leaves a `running` record for a run that is
- * not running (RUSH-2640). A caller answering "is one running now?" MUST gate on
- * this, mirroring `listLiveRoutineChildren`'s local-liveness test:
- * - a local child is in flight only while its pid is still ours (alive, same
- *   birth time — a dead-and-reused pid does not count);
- * - a `host:`-placed run has no local pid by design and is in flight until its
- *   remote `.exit` is reconciled (`finalizeHostRun`).
- */
 export function isRunGenuinelyInFlight(meta) {
     if (meta.status !== 'running')
         return false;
@@ -2466,39 +1806,10 @@ export function isRunGenuinelyInFlight(meta) {
         return false;
     return isPidOurs(meta.pid, meta.spawnedAt);
 }
-/**
- * Reconcile ONE `running` record once its process identity is known (`ours` =
- * the recorded pid is still genuinely the child we spawned). Shared verbatim by
- * the synchronous {@link monitorRunningJobs} (off-loop callers) and the async
- * {@link reapExitedRunningJobs} (daemon heartbeat tick) so there is one copy of
- * the finalize/timeout/report logic — only the surrounding directory/`ps` IO
- * differs by sync-vs-async flavor. Caller has already confirmed `meta.status`
- * is `running`. The finalize/report/archive helpers stay synchronous: they run
- * ONLY when a run actually transitions (times out or its process exited), a
- * conditional/rare event, not the every-tick scan the loop-starvation fix
- * (PHNX-3695) targets. The one exception is the `routine.end` EVENT emit, whose
- * file lock CAN block for up to 30s under contention even on that rare path — so
- * the emitter is injected: the off-loop sync caller passes `emitRoutineEnd`
- * (synchronous, so a short-lived CLI process flushes it before exit), the daemon
- * tick passes a fire-and-forget `emitRoutineEndAsync` (the long-lived daemon
- * flushes it, and the shared event loop is never blocked on the lock).
- */
 function reconcileRunningRecord(meta, jobRunsPath, runDirName, ours, emitEnd) {
-    // Host-placed runs (meta.hostTaskId) are handled by the caller, sync or async
-    // — their remote `.exit` read is ssh I/O that must stay off the daemon tick's
-    // event loop (finalizeHostRunAsync). Records reaching here are local-pid runs.
     const runDirPath = path.join(jobRunsPath, runDirName);
     const stdoutPath = path.join(runDirPath, 'stdout.log');
-    // Command-mode records carry no agent; there is no stream-json report to
-    // parse or extract. Reap them on pid liveness alone.
     const isCommandRun = Boolean(meta.command) || !meta.agent;
-    // Age-out runs FIRST, before the null-pid guard below, so a wedged record
-    // still marked `running` past its deadline is always finalized — a
-    // provisional launcher claim whose daemon crashed before spawning a child
-    // (pid null), or an old record whose recorded pid was reused, would
-    // otherwise linger as `running` forever (RUSH-2640). Only kill a process
-    // group that is genuinely still ours; terminating a reused pid would kill
-    // an unrelated process, and a null pid has nothing to kill.
     const wallClockMs = Date.now() - Date.parse(meta.startedAt);
     const timeoutMs = meta.timeoutMs ?? MAX_WALL_CLOCK_MS;
     if (Number.isFinite(wallClockMs) && wallClockMs > timeoutMs) {
@@ -2517,11 +1828,6 @@ function reconcileRunningRecord(meta, jobRunsPath, runDirName, ours, emitEnd) {
         return;
     if (!ours) {
         if (isCommandRun) {
-            // Command routines normally record their own terminal status via
-            // child.on('exit') (so this record would already be non-'running' and
-            // skipped above). Reaching here means the daemon restarted mid-run and
-            // missed the exit event — recover the true code from the exit-code file
-            // the child wrote; its absence means the child was killed/crashed.
             const ec = readCommandExitCode(runDirPath);
             finalizeRunMeta(meta, ec === 0 ? 'completed' : 'failed', ec);
         }
@@ -2542,15 +1848,6 @@ function reconcileRunningRecord(meta, jobRunsPath, runDirName, ours, emitEnd) {
         }
     }
 }
-/**
- * Scan all runs marked "running" and finalize any whose process has exited.
- *
- * SYNCHRONOUS — for OFF-loop callers only (the `agents routines list/status`
- * builders and CLI best-effort orphan reaps), which run in short-lived CLI
- * processes where a bounded synchronous `ps`/scan cannot starve a served event
- * loop. The daemon's own heartbeat tick MUST use {@link reapExitedRunningJobs}
- * instead — a sync scan there would freeze the shared event loop (PHNX-3695).
- */
 export function monitorRunningJobs() {
     const runsDir = getRunsDir();
     if (!fs.existsSync(runsDir))
@@ -2565,8 +1862,6 @@ export function monitorRunningJobs() {
                 .filter((e) => e.isDirectory());
         }
         catch (err) {
-            // A retention/cleanup pass may remove a job directory after the root
-            // snapshot. The next monitor sweep observes the remaining state.
             if (err.code === 'ENOENT')
                 continue;
             throw err;
@@ -2579,27 +1874,17 @@ export function monitorRunningJobs() {
                 const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
                 if (meta.status !== 'running')
                     continue;
-                // `host:`-placed run — no local pid; reconcile against the remote `.exit`.
                 if (meta.hostTaskId) {
                     finalizeHostRun(meta);
                     continue;
                 }
                 const ours = meta.pid ? isPidOurs(meta.pid, meta.spawnedAt) : false;
-                // Sync emit: an off-loop CLI process must flush the event before it exits.
                 reconcileRunningRecord(meta, jobRunsPath, runDirEntry.name, ours, emitRoutineEnd);
             }
-            catch { /* corrupt or unreadable meta.json */ }
+            catch { }
         }
     }
 }
-/**
- * Async, non-blocking twin of {@link monitorRunningJobs} for the daemon's
- * heartbeat tick (PHNX-3695). Identical reconciliation via
- * {@link reconcileRunningRecord}, but the directory walk uses `fs/promises` and
- * the pid-identity probe uses the deadline-bounded {@link isPidOursAsync}, so
- * the every-tick scan never freezes the shared event loop — the freeze that
- * left the browser IPC `version` probe unanswered.
- */
 export async function reapExitedRunningJobs() {
     const runsDir = getRunsDir();
     let jobDirs;
@@ -2607,7 +1892,7 @@ export async function reapExitedRunningJobs() {
         jobDirs = await fsp.readdir(runsDir, { withFileTypes: true });
     }
     catch {
-        return; // runs dir absent — nothing to reap
+        return;
     }
     for (const jobDir of jobDirs) {
         if (!jobDir.isDirectory())
@@ -2618,8 +1903,6 @@ export async function reapExitedRunningJobs() {
             runDirs = await fsp.readdir(jobRunsPath, { withFileTypes: true });
         }
         catch {
-            // A retention/cleanup pass may remove a job directory after the root
-            // snapshot. The next sweep observes the remaining state.
             continue;
         }
         for (const runDirEntry of runDirs) {
@@ -2630,18 +1913,14 @@ export async function reapExitedRunningJobs() {
                 const meta = JSON.parse(raw);
                 if (meta.status !== 'running')
                     continue;
-                // `host:`-placed run — read its remote `.exit` over ssh ASYNC so a slow
-                // host never freezes the tick's event loop (PHNX-3695).
                 if (meta.hostTaskId) {
                     await finalizeHostRunAsync(meta);
                     continue;
                 }
                 const ours = meta.pid ? await isPidOursAsync(meta.pid, meta.spawnedAt) : false;
-                // Fire-and-forget async emit: the event-log lock must never block the
-                // daemon tick's shared event loop; the long-lived daemon still flushes it.
                 reconcileRunningRecord(meta, jobRunsPath, runDirEntry.name, ours, (m) => { void emitRoutineEndAsync(m); });
             }
-            catch { /* corrupt or unreadable meta.json */ }
+            catch { }
         }
     }
 }