@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/commands/teams.js

@@ -51,7 +51,6 @@ const AGENT_NAMES = {
     warp: 'Warp',
 };
 const VALID_AGENTS = ['claude', 'codex', 'cursor', 'opencode', 'grok', 'antigravity', 'kimi', 'droid', 'warp'];
-// 'full' kept as historical alias for 'skip'; normalized to 'skip' downstream.
 const VALID_MODES = ['plan', 'edit', 'auto', 'skip', 'full'];
 const VALID_EFFORTS = ['low', 'medium', 'high', 'xhigh', 'max', 'auto'];
 const VALID_CLOUD_PROVIDERS = ['rush', 'codex', 'factory'];
@@ -60,8 +59,8 @@ function statusColor(status) {
         case 'pending': return chalk.blue;
         case 'running': return chalk.yellow;
         case 'completed': return chalk.green;
-        case 'pr_open': return chalk.magenta; // RUSH-2380: process done, PR not merged
-        case 'stranded': return chalk.yellow; // PHNX-2951: done but work not committed
+        case 'pr_open': return chalk.magenta;
+        case 'stranded': return chalk.yellow;
         case 'failed': return chalk.red;
         case 'stopped': return chalk.gray;
         default: return chalk.white;
@@ -157,11 +156,6 @@ function fullName(type, version) {
     const name = AGENT_NAMES[type];
     return version ? `${name} ${version}` : name;
 }
-/**
- * One-line operator nudge after `teams start`: teammates are briefed to post
- * IMPORTANT milestones to the feed (RUSH-2250), and this is how to watch them.
- * Print-only — no engine behavior.
- */
 export function printFeedHint(team) {
     console.log(chalk.gray('Tip: teammates post IMPORTANT milestones to the feed (') +
         chalk.cyan('agents feed timeline') +
@@ -169,20 +163,6 @@ export function printFeedHint(team) {
         chalk.cyan(`agents teams status ${team}`) +
         chalk.gray('.'));
 }
-/**
- * Resolve a teammate spec to its execution target.
- *
- * Accepts:
- *  - `claude`            — default version of an installed agent
- *  - `claude@2.1.112`    — pinned version of an installed agent
- *  - `<profile-name>`    — runs through `agents run <profile>`, with the
- *                          profile's host agent used as the underlying
- *                          AgentType for event parsing and CLI checks.
- *
- * `agent` is always the underlying harness so event parsers, CLI-availability
- * checks, and version pins keep working. `profileName` is set only when the
- * spec resolved through a profile.
- */
 function parseTeammate(spec) {
     const [name, version] = spec.split('@');
     if (VALID_AGENTS.includes(name)) {
@@ -193,9 +173,6 @@ function parseTeammate(spec) {
             profileName: null,
         };
     }
-    // Not a built-in agent id — try resolving as a profile name. A profile
-    // pinning a version is allowed; `profile@<override>` is not (would conflict
-    // with the profile's own host.version).
     if (!version && profileExists(name)) {
         try {
             const profile = readProfile(name);
@@ -215,14 +192,6 @@ function parseTeammate(spec) {
 function shortId(id) {
     return id.slice(0, 8);
 }
-/**
- * Decide how a follow-up to a teammate is delivered from its reconciled status.
- * Pure — the source of truth for the routing table, unit-tested without I/O.
- *   - pending                       -> not-started (tell them to `teams start`)
- *   - running     + message         -> steer (mailbox)
- *   - stopped/etc + message         -> resume (re-enter session)
- *   - any actionable + no message   -> need-message
- */
 export function decideTeamMessageRoute(status, hasMessage) {
     if (status === AgentStatus.PENDING)
         return { kind: 'not-started' };
@@ -232,11 +201,6 @@ export function decideTeamMessageRoute(status, hasMessage) {
         return { kind: 'steer' };
     return { kind: 'resume' };
 }
-/**
- * Preamble injected into every factory worker's prompt. Tells the worker
- * which team + teammate name + task-type it is, and how to file new tasks.
- * The actual how-to lives in the /factory-worker skill.
- */
 function factoryWorkerPreamble(team, name, taskType, after) {
     const n = name ?? '<anonymous>';
     const deps = after.length > 0 ? after.join(', ') : '(none)';
@@ -255,33 +219,6 @@ function factoryWorkerPreamble(team, name, taskType, after) {
 function mkManager() {
     return new AgentManager();
 }
-/**
- * Tell the user a worktree from a failed `teams add` is still on disk, and give
- * them the exact commands to remove it. Reached only when we could not remove it
- * ourselves — a leftover `agents/<name>` branch is what makes the retry fail with
- * `fatal: a branch ... already exists`, so it must never be silent (RUSH-2356).
- */
-/**
- * Tear down a worktree a failed operation left behind — but ONLY if it is a
- * genuine orphan.
- *
- * Extracted because this guard was hand-duplicated at two call sites (`teams
- * add` and the pr-watch fixer) and the copy at the fixer path was written
- * WITHOUT it, which is RUSH-2356 reoccurring at the one site that skipped the
- * check. One implementation, one place to get it right.
- *
- * The two errors here are not symmetric, so the guard deliberately fails
- * CLOSED: a spurious "claimed" strands a branch a human can delete, while a
- * spurious "unclaimed" runs `git worktree remove --force` over a live
- * teammate's checkout and destroys uncommitted work. So an unreadable record
- * means "leave it alone and tell the user", never "assume it is free".
- *
- * A staged teammate is exactly the case that makes this necessary: `spawn()`
- * persists its meta.json and only THEN runs the retention pass, which refreshes
- * every sibling and can throw on a distributed one — so a failure can land here
- * with a live, durably-recorded, merely-pending `--after` teammate already
- * owning this worktree.
- */
 export async function tearDownOrphanWorktree(mgr, baseCwd, name) {
     try {
         if (await mgr.isWorktreeClaimed(name))
@@ -303,34 +240,15 @@ function warnOrphanWorktree(baseCwd, name, reason) {
         `  Remove it manually: git -C ${baseCwd} worktree remove --force .agents/worktrees/${name} ` +
         `&& git -C ${baseCwd} branch -D agents/${name}\n`));
 }
-/** Pluralize a commit count: "1 commit" / "3 commits". */
 function commitsWord(behind) {
     return `${behind} commit${behind === 1 ? '' : 's'}`;
 }
-/**
- * The blocking message when `teams add` is pointed at a stale checkout. Pure so
- * the guidance is pinned by tests (mirrors `remoteCwdOnAddError`): it MUST name
- * how far behind, tell the caller to sync with remote main, and mention `--confirm`
- * as the override.
- */
 export function staleRepoError(params) {
     return (`${params.where} is ${commitsWord(params.behind)} behind origin/${params.base}. ` +
         `A team started here would build on stale code — bring it up to date with remote main first:\n` +
         `  ${params.sync}\n` +
         `Then re-run \`agents teams add ${params.team} …\`, or pass --confirm to start on the stale repo anyway.`);
 }
-/**
- * Guard against pointing a team at a stale checkout. Before a teammate is bound
- * to a repo, this fetches origin and counts how far behind `origin/<default>` the
- * base checkout is (the local cwd, or the repo provisioned on a `--device` host).
- * If it is behind and the caller did NOT pass `--confirm`, the add is refused with
- * {@link staleRepoError} — because a team started on stale code reasons and builds
- * against a tree that has already moved on (the 71-commit-stale s1 checkout
- * incident). With `--confirm` it prints a one-line advisory and proceeds.
- *
- * A `null` behind-count (offline, non-repo, unreachable host) is "can't tell" and
- * never blocks — this is a freshness nudge, not a hard prerequisite.
- */
 async function assertRepoFreshOrConfirm(params) {
     const { team, confirm, json } = params;
     const res = params.remote
@@ -354,11 +272,6 @@ async function assertRepoFreshOrConfirm(params) {
     }
     dieFriction('teams', 'repo-stale', staleRepoError({ team, where, behind: res.behind, base: res.base, sync }), 1, { json });
 }
-/**
- * Register the generic cloud dispatcher — staged cloud teammates get
- * dispatched when their --after deps resolve, using repo/branch stored on
- * the teammate itself so we don't need the original --cloud CLI args.
- */
 function wireCloudDispatcher(mgr) {
     mgr.setCloudDispatcher(async (a) => {
         if (!a.cloudProvider) {
@@ -372,9 +285,6 @@ function wireCloudDispatcher(mgr) {
 }
 export function cloudDispatchOptions(agent) {
     return {
-        // PHNX-3236: a cloud teammate runs in the provider sandbox and never inherits
-        // the local merge-guard.sh hook, so the prompt policy is its ONLY self-merge
-        // boundary — apply the same helper buildRunArgv uses for local/remote.
         prompt: withTeammatePrPolicy(agent.prompt, agent.mode),
         agent: agent.agentType,
         repo: agent.cloudRepo ?? undefined,
@@ -383,17 +293,6 @@ export function cloudDispatchOptions(agent) {
         env: shareRuntimeEnv(),
     };
 }
-/**
- * Advisory: warn once per agent type of any still-pending (staged `--after`)
- * teammate whose CLI may not be signed in. Warn-only — never blocks `start`.
- * Local teammates only; cloud teammates authenticate through their provider.
- */
-/**
- * Advisory line for a version-pinned teammate whose account can't serve a run
- * right now. A pinned target (`agents run <agent>@<version>`) bypasses account
- * rotation — the pin IS the target — so unlike a bare teammate it can't route
- * around a throttled/expired account; it will launch and likely 429 at once.
- */
 function throttleWarningLine(agent, version, r) {
     const who = `${AGENT_NAMES[agent]} ${version}`;
     const acct = r.email ? ` (${r.email})` : '';
@@ -405,21 +304,13 @@ function throttleWarningLine(agent, version, r) {
         chalk.gray(`\n  A pinned version skips account rotation, so it will launch on this account and may immediately hit its limit.` +
             `\n  Use a bare \`${agent}\` teammate to let the team pick a healthy account, or pass --force to silence this.`));
 }
-/**
- * Advisory: for each staged VERSION-PINNED teammate, warn if its account is
- * rate-limited / out of credits / signed out right now — reusing the router's
- * own eligibility signal (`checkRunAccountReadiness`) so the warning matches
- * what the spawn would actually do. Bare teammates (rotation handles them) and
- * profile/cloud teammates (account not locally checkable) are skipped. Warns,
- * never blocks. Deduped by agent@version so N teammates on one account warn once.
- */
 async function warnThrottledTeammates(mgr, team) {
     let pending;
     try {
         pending = (await mgr.listByTask(team)).filter((a) => a.status === 'pending' && !a.cloudProvider && !a.profileName && a.version);
     }
     catch {
-        return; // team not loadable yet — nothing to warn about
+        return;
     }
     const seen = new Set();
     for (const a of pending) {
@@ -440,7 +331,7 @@ async function warnUnsignedTeammates(mgr, team) {
         pending = (await mgr.listByTask(team)).filter((a) => a.status === 'pending' && !a.cloudProvider);
     }
     catch {
-        return; // team not loadable yet — nothing to warn about
+        return;
     }
     const seen = new Set();
     for (const a of pending) {
@@ -454,14 +345,6 @@ async function warnUnsignedTeammates(mgr, team) {
         }
     }
 }
-/**
- * Single-wave start used by `teams start` without --watch. startReady()
- * terminalizes a placement/spawn/cloud/dependency failure to FAILED with
- * evidence rather than leaving it PENDING, so a teammate that failed this wave
- * appears in neither `launched` nor `still_pending` — it must be diffed against
- * the pre-wave roster and reported explicitly, or the wave reads as a success.
- * A wave that only produced failures sets a non-zero exit code.
- */
 export async function runOneWave(mgr, team, json) {
     const preWavePending = new Set((await mgr.listByTask(team)).filter((a) => a.status === 'pending').map((a) => a.agentId));
     const launched = await mgr.startReady(team);
@@ -512,12 +395,6 @@ export async function runOneWave(mgr, team, json) {
     if (launched.length > 0)
         printFeedHint(team);
 }
-/**
- * Path to the pr-watch dedupe-state file for a team. Persists the set of
- * already-handled check/comment dedupe keys so a restart of `teams pr-watch`
- * never re-spawns a fix wave for a failure it already reacted to. Lives in the
- * teammate base dir; it's a flat file so loadExistingAgents (dir-only) skips it.
- */
 async function prWatchStatePath(team) {
     const safe = team.replace(/[^A-Za-z0-9_-]/g, '_');
     return path.join(await getAgentsDir(), `pr-watch-${safe}.json`);
@@ -544,12 +421,6 @@ async function savePrWatchState(team, state) {
         debug(`Could not persist pr-watch state for ${team}: ${err.message}`);
     }
 }
-/**
- * Resolve the PRs opened by a team's teammates, de-duplicated by PR URL. A
- * teammate's PR URL comes from its own `pr_url` field or, failing that, the
- * session it ran (detected from the transcript's `gh pr create`). The teammate
- * name is the `--after` anchor for the fix/bugfix teammate we spawn.
- */
 async function resolvePrWatchTargets(mgr, team) {
     const status = await handleStatus(mgr, team, 'all');
     const sessions = await resolveTeammateSessions(status.agents);
@@ -559,38 +430,22 @@ async function resolvePrWatchTargets(mgr, team) {
         if (!prUrl)
             continue;
         if (byPr.has(prUrl))
-            continue; // first teammate to own a PR is its source
+            continue;
         byPr.set(prUrl, { prUrl, sourceTeammate: a.name ?? null });
     }
     return [...byPr.values()];
 }
-/**
- * React to one decided pr-watch action by spawning a follow-up teammate on the
- * same PR — a ci-fix teammate on RED CI, or a `bugfix` teammate on a new review
- * comment — linked `--after` the teammate that opened the PR so it slots into
- * the same DAG the supervisor already drains. Returns the teammate label.
- */
 async function reactWithTeammate(mgr, team, action, prompt) {
-    // Unique name per reaction. The dedupe key is stable across waves (keyed on the
-    // check NAME), so the wave number is what keeps successive fixers' names — and
-    // their worktrees — distinct within the team.
     const uniq = action.dedupeKey.replace(/[^A-Za-z0-9]/g, '').slice(-10) || `${action.wave}`;
     const slug = `${uniq}-w${action.wave}`;
     const name = action.kind === 'ci-fix' ? `cifix-${slug}` : `bugfix-${slug}`;
     const taskType = action.kind === 'review-fix' ? 'bugfix' : null;
-    // Link --after the source teammate when it's a real, resolvable sibling; a
-    // missing source means the PR couldn't be traced to a named teammate, so the
-    // fix runs immediately with no dependency edge.
     const after = [];
     if (action.sourceTeammate) {
         const resolved = await mgr.resolveAgentIdInTask(team, action.sourceTeammate);
         if (resolved.kind === 'ok')
             after.push(action.sourceTeammate);
     }
-    // Isolate each fixer in its own worktree so concurrent `gh pr checkout`s (across
-    // PRs, or across waves) never clash in a shared cwd. Requires a git repo — which
-    // pr-watch always is, since it operates on PRs; fall back to the cwd only when
-    // the checkout somehow isn't a repo.
     const baseCwd = process.cwd();
     let worktreeName = null;
     let worktreePath = null;
@@ -610,36 +465,15 @@ async function reactWithTeammate(mgr, team, action, prompt) {
     }
     let result;
     try {
-        result = await handleSpawn(mgr, team, 'claude', prompt, cwd, 'edit', 'medium', null, cwd, null, name, after, null, null, taskType, null, null, null, null, worktreeName, worktreePath, null, // profileName
-        null, // hostName
-        null, // hostTarget
-        null, // repoPath
-        // A pr-watch fixer belongs to the same team, so it gets the same project
-        // grants as any other teammate. Wiring `--project` into only the
-        // `teams add` caller would have left this one silently without them.
-        (await getTeam(team))?.project ?? null);
+        result = await handleSpawn(mgr, team, 'claude', prompt, cwd, 'edit', 'medium', null, cwd, null, name, after, null, null, taskType, null, null, null, null, worktreeName, worktreePath, null, null, null, null, (await getTeam(team))?.project ?? null);
     }
     catch (err) {
-        // The spawn failed after we created this fixer's worktree — tear it down so
-        // the branch `agents/<name>` doesn't block the next wave's retry with
-        // `fatal: a branch ... already exists` (RUSH-2356). Best-effort; the
-        // original failure is what propagates.
-        //
-        // Guarded exactly like the `teams add` teardown, and for the same reason:
-        // handleSpawn -> manager.spawn() persists a staged teammate's meta.json and
-        // only THEN runs the retention pass, which refreshes every sibling and can
-        // throw on a distributed one. A fixer teammate is staged with `--after` when
-        // it follows a source teammate, so a throw there lands here with a LIVE,
-        // durably-recorded, merely-pending teammate already owning this worktree —
-        // and removing it would destroy real work. Only tear down a genuine orphan.
         if (worktreeName)
             await tearDownOrphanWorktree(mgr, baseCwd, worktreeName);
         throw err;
     }
     return result.name ?? shortId(result.agent_id);
 }
-// Pick the display handle for a teammate: explicit teammate name, Claude
-// session label, then the 8-char UUID prefix.
 function handle(a) {
     return a.name || a.session_label || shortId(a.agent_id);
 }
@@ -649,8 +483,6 @@ function displayHandle(a) {
     }
     return handle(a);
 }
-// Resolve a teammate reference (name / UUID / UUID prefix) by scanning every
-// meta.json under the agents dir. Team hint narrows the search.
 async function resolveTeammateAcrossTeams(base, ref, teamHint) {
     let entries = [];
     try {
@@ -659,13 +491,10 @@ async function resolveTeammateAcrossTeams(base, ref, teamHint) {
     catch {
         return { kind: 'none' };
     }
-    // Cheap path: exact UUID or unique UUID prefix match by directory name.
     const byDir = entries.filter((e) => e === ref || e.startsWith(ref));
     if (byDir.length === 1 && byDir[0] === ref) {
         return { kind: 'ok', agentId: ref };
     }
-    // Otherwise scan meta.json files to match on name as well, and respect the
-    // team hint if given.
     const candidates = [];
     for (const dir of entries) {
         try {
@@ -684,31 +513,18 @@ async function resolveTeammateAcrossTeams(base, ref, teamHint) {
             }
         }
         catch {
-            /* skip entries without readable meta.json */
         }
     }
     if (candidates.length === 0)
         return { kind: 'none' };
     if (candidates.length === 1)
         return { kind: 'ok', agentId: candidates[0].agentId };
-    // If multiple match but one is an exact name hit, prefer it.
     const exactName = candidates.filter((c) => c.name === ref);
     if (exactName.length === 1)
         return { kind: 'ok', agentId: exactName[0].agentId };
     return { kind: 'ambiguous', candidates };
 }
-// Print a teammate block using the same session preview the sessions picker
-// uses — one canonical renderer across `agents sessions`, teams picker
-// preview, and teams status output.
-//
-// Layout:
-//   alice  claude  COMPLETED · 5.0 minutes
-//     after: bob
-//     <buildSessionPreview output>    (when the session file was found)
-//     ! reported an error             (if flagged)
-//     PR: <url>                       (if set)
 function printAgentDetail(a, session) {
-    // RUSH-2380: process COMPLETED + open PR → show PR OPEN, not COMPLETED.
     const delivery = a.delivery ??
         resolveTeammateDelivery({ status: a.status, prUrl: a.pr_url });
     const colorKey = deliveryColorKey(delivery, a.status);
@@ -743,23 +559,16 @@ function printAgentDetail(a, session) {
     if (a.failure) {
         console.log(`    ${chalk.red('failure ')} ${a.failure.code}: ${a.failure.message}`);
     }
-    // If the agent's internal session id differs from ours (non-Claude), show
-    // it as a hint for `agents sessions <id>`.
     if (a.remote_session_id && a.remote_session_id !== a.agent_id) {
         console.log(`    ${chalk.gray('session ')} ${chalk.gray(a.remote_session_id)}`);
     }
     if (session) {
-        // Hand off to the same renderer the sessions picker uses. Indent so the
-        // block visually belongs to this teammate.
         const preview = buildSessionPreview(session);
         for (const line of preview.split('\n')) {
             console.log(line ? `    ${line}` : '');
         }
     }
     else {
-        // Session file not yet on disk (e.g. teammate is pending, or their
-        // agent type writes sessions elsewhere). Fall back to a compact summary
-        // derived from the live status payload.
         const activity = [];
         if (a.files_modified.length)
             activity.push(`${a.files_modified.length} modified`);
@@ -794,15 +603,10 @@ function printAgentDetail(a, session) {
     if (a.pr_url)
         console.log(`    ${chalk.gray('PR  ')}${a.pr_url}`);
 }
-// Resolve each live teammate to its on-disk session (Claude/Codex/Gemini/
-// OpenCode all write parseable session files). `agent_id === remote_session_id`
-// for Claude teammates; non-Claude agents may carry their own session UUID on
-// `remote_session_id`. We try both.
 async function resolveTeammateSessions(agents) {
     const map = new Map();
     if (agents.length === 0)
         return map;
-    // Scan every project dir — team teammates may have run from anywhere.
     const all = await discoverSessions({ all: true, limit: 5000 });
     for (const a of agents) {
         const candidates = [a.remote_session_id, a.agent_id].filter(Boolean);
@@ -818,10 +622,6 @@ async function resolveTeammateSessions(agents) {
     }
     return map;
 }
-// Default compact renderer — one block per teammate, optimized for the
-// orchestrator scanning "what state, what did you touch, what did you say
-// last." Caller passes the projected AgentStatusSummary; for the full
-// verbose layout use printAgentDetail above.
 function printAgentSummary(s) {
     const delivery = s.delivery ??
         resolveTeammateDelivery({ status: s.status, prUrl: s.pr_url });
@@ -837,7 +637,6 @@ function printAgentSummary(s) {
     if (s.failure) {
         console.log(`    ${chalk.red('failure ')} ${s.failure.code}: ${s.failure.message}`);
     }
-    // Files: counts + basenames. Read is count only.
     const fileLines = [];
     const renderCat = (label, cat) => {
         if (cat.count === 0)
@@ -854,7 +653,6 @@ function printAgentSummary(s) {
     if (fileLines.length) {
         console.log(`    ${chalk.gray('files   ')} ${fileLines.join(chalk.gray(' · '))}`);
     }
-    // Last 3 bash commands.
     const recentBash = s.bash_commands.slice(-3);
     if (recentBash.length) {
         console.log(`    ${chalk.gray('bash    ')}`);
@@ -862,7 +660,6 @@ function printAgentSummary(s) {
             console.log(`      ${chalk.gray('$')} ${truncate(cmd, 96)}`);
         }
     }
-    // Last messages — first non-empty line of each, truncated.
     if (s.last_messages.length) {
         console.log(`    ${chalk.gray('messages')}`);
         for (const msg of s.last_messages) {
@@ -894,8 +691,6 @@ function formatTeamStatusSummary(summary) {
         parts.push(`${summary.stopped} stopped`);
     return `(${parts.join(', ')})`;
 }
-// Render a team's status in the same format the `status` subcommand uses, so
-// the interactive picker's Enter action drops the user into a familiar view.
 async function printTeamStatus(team, result) {
     const { summary, agents } = result;
     console.log(chalk.bold(`Team ${chalk.cyan(team)}  `) + chalk.gray(formatTeamStatusSummary(summary)));
@@ -918,10 +713,6 @@ async function printTeamStatus(team, result) {
     console.log();
     console.log(chalk.gray(`cursor: ${result.cursor}`));
 }
-// Compact default renderer — no session-file dive, no per-teammate
-// 15-line preview. One block per teammate, suitable for the orchestrator
-// scanning what each agent did. Use `printTeamStatus` (above) for the
-// verbose/legacy layout.
 function printTeamSummary(team, result) {
     const { summary, agents } = result;
     console.log(chalk.bold(`Team ${chalk.cyan(team)}  `) + chalk.gray(formatTeamStatusSummary(summary)));
@@ -945,14 +736,6 @@ function printTeamSummary(team, result) {
     console.log(chalk.gray('Full detail: agents teams status ' + team + ' --verbose'));
     console.log(chalk.gray('Raw log:     agents teams logs --team ' + team + ' --teammate <name>'));
 }
-// Classify a team into a single bucket for --status filtering.
-//  - empty:    no teammates (created but nobody added yet)
-//  - waiting:  only staged teammates — call `teams start` to kick them off
-//  - working:  at least one teammate still running
-//  - failed:   at least one teammate failed or was stopped (any failure wins —
-//              even if others finished, you want to know about the failure)
-//  - stranded: everyone finished, but at least one has uncommitted work and no PR
-//  - done:     everyone finished successfully, no failures, no stranded work
 function classifyTeamStatus(t) {
     if (t.agent_count === 0)
         return 'empty';
@@ -960,19 +743,13 @@ function classifyTeamStatus(t) {
         return 'working';
     if (t.failed + t.stopped > 0)
         return 'failed';
-    // At this point nobody is running/failed/stopped. If there's any pending
-    // teammate (agent_count > running+completed+failed+stopped), it's "waiting".
     const accounted = t.running + t.completed + t.failed + t.stopped;
     if (accounted < t.agent_count)
         return 'waiting';
-    // Completed-without-delivery is not "done": the work is still in the worktree
-    // and will be lost on cleanup (PHNX-2951).
     if ((t.stranded ?? 0) > 0)
         return 'stranded';
     return 'done';
 }
-// Merge persistent team registry with tasks derived from live agents so empty
-// teams (created but no teammates yet) still show up.
 function mergeTeams(registry, tasks) {
     const byName = new Map();
     for (const t of tasks)
@@ -1026,7 +803,6 @@ async function buildTasksFromSnapshots(agents) {
                 failed++;
             else if (status === AgentStatus.STOPPED)
                 stopped++;
-            // Stranded = completed with no PR and a dirty local worktree (PHNX-2951).
             if (status === AgentStatus.COMPLETED &&
                 !agent.pr_url?.trim() &&
                 !agent.host &&
@@ -1065,9 +841,7 @@ async function buildTasksFromSnapshots(agents) {
     }
     return tasks.sort((a, b) => new Date(b.modified_at).getTime() - new Date(a.modified_at).getTime());
 }
-export async function buildTeamRowsFromSnapshots(registry, agents, 
-/** team name -> the session that spawned it (see teamSpawners). */
-spawners) {
+export async function buildTeamRowsFromSnapshots(registry, agents, spawners) {
     const byTeam = new Map();
     for (const agent of agents) {
         const details = byTeam.get(agent.task_name) || [];
@@ -1075,8 +849,6 @@ spawners) {
         byTeam.set(agent.task_name, details);
     }
     const teams = mergeTeams(registry, await buildTasksFromSnapshots(agents));
-    // Recompute delivery for cached snapshots so `teams list` reflects stranded
-    // work discovered by probing the real worktree (PHNX-2951).
     for (const details of byTeam.values()) {
         for (const a of details) {
             const snapshot = agents.find((s) => s.agent_id === a.agent_id);
@@ -1151,24 +923,16 @@ async function loadTeamAgentSnapshots() {
     }));
     return snapshots.filter((snapshot) => snapshot !== null);
 }
-// Build cached rows for the `list` picker. Shared between `list` and picker
-// fallbacks for `status` / `start`; full status stays lazy until a team is picked.
 async function loadTeamRows(_mgr) {
     const [registry, agents] = await Promise.all([loadTeams(), loadTeamAgentSnapshots()]);
-    // Lineage is read off the session index, not the team registry: the registry is
-    // per-machine runtime state, while the transcript that ran `teams create` is
-    // indexed, survives the teammate cleanup, and covers teams created before this.
     let spawners;
     try {
         spawners = teamSpawners();
     }
     catch {
-        // The index is an enrichment here — a missing/locked DB just drops the column.
     }
     return await buildTeamRowsFromSnapshots(registry, agents, spawners);
 }
-// Picker fallback for `teams logs` when the teammate ref is omitted. Shows a
-// flat list of every teammate with their team context; Enter picks one.
 async function pickTeammateOr(mgr, command) {
     if (!isInteractiveTerminal()) {
         requireInteractiveSelection(`Picking a teammate for \`${command}\``, [
@@ -1218,9 +982,6 @@ async function pickTeammateOr(mgr, command) {
         throw err;
     }
 }
-// Fallback for read-only / constructive subcommands when the user omits the
-// team argument. In a TTY, show the picker and return the chosen team. Outside
-// a TTY, hard-fail with a clear error so scripts surface the missing arg.
 async function pickTeamOr(mgr, command) {
     if (!isInteractiveTerminal()) {
         requireInteractiveSelection(`Picking a team for \`${command}\``, [
@@ -1244,16 +1005,6 @@ async function pickTeamOr(mgr, command) {
         throw err;
     }
 }
-/**
- * `teams add --remote-cwd` is a no-op trap. `--remote-cwd` comes from the shared
- * `--device` option family (option.ts) and is meaningful for commands that *route*
- * to a host, but `teams add` special-cases `--device`/`--device` as PLACEMENT, so
- * the flag is never read — a teammate's directory is the team's repo plus its
- * `--worktree`, not a path passed here. Silently ignoring it misleads you into
- * thinking it set the teammate's repo path (the exact wrong model that turns one
- * team into a teardown-and-rebuild). Reject with guidance instead. Exported for
- * the unit test that pins the message.
- */
 export function remoteCwdOnAddError(team) {
     return (`--remote-cwd has no effect on 'teams add' — it does not set a teammate's repo or directory.\n` +
         `  A teammate works in the team's repo plus its own --worktree:\n` +
@@ -1261,7 +1012,6 @@ export function remoteCwdOnAddError(team) {
         `    • Place the teammate on a machine: agents teams add ${team} <agent> "<task>" --device <host> --worktree <name>\n` +
         `  (Remote worktrees fork from the host's freshly-fetched origin/<default> automatically.)`);
 }
-/** Register the `agents teams` command tree (list, create, add, status, start, remove, disband, logs, doctor). */
 export function registerTeamsCommands(program) {
     const teams = program
         .command('teams')
@@ -1324,7 +1074,6 @@ export function registerTeamsCommands(program) {
         teams rm = remove    teams d  = disband   teams ls = list
     `,
     });
-    // list
     addHostOption(teams.command('list [query]'))
         .alias('ls')
         .description('List your teams, most recent activity first')
@@ -1340,29 +1089,23 @@ export function registerTeamsCommands(program) {
             loadTeams(),
             loadTeamAgentSnapshots(),
         ]);
-        // Group agents by team so we can filter on agent-type / version.
         const byTeam = new Map();
         for (const a of everyAgent) {
             const arr = byTeam.get(a.task_name) || [];
             arr.push(a);
             byTeam.set(a.task_name, arr);
         }
-        // Same lineage enrichment as loadTeamRows — without it this listing is the
-        // one `teams list` surface that silently drops the "spawned by" column.
         let spawners;
         try {
             spawners = teamSpawners();
         }
         catch {
-            // The session index is an enrichment here; a missing one drops the column.
         }
         let rows = (await buildTeamRowsFromSnapshots(registry, everyAgent, spawners)).rows;
-        // --- query: substring match on team name ---
         if (query) {
             const q = query.toLowerCase();
             rows = rows.filter((row) => row.team.task_name.toLowerCase().includes(q));
         }
-        // --- --agent: filter teams containing a matching teammate ---
         if (opts.agent) {
             const [wantType, rawVersion] = opts.agent.split('@');
             const wantVersion = VALID_AGENTS.includes(wantType)
@@ -1373,7 +1116,6 @@ export function registerTeamsCommands(program) {
                 return teammates.some((m) => m.agent_type === wantType && (!wantVersion || m.version === wantVersion));
             });
         }
-        // --- --status: classify each team, filter ---
         if (opts.status) {
             const want = opts.status.toLowerCase();
             const validStatuses = ['working', 'done', 'stranded', 'failed', 'empty'];
@@ -1382,7 +1124,6 @@ export function registerTeamsCommands(program) {
             }
             rows = rows.filter((row) => classifyTeamStatus(row.team) === want);
         }
-        // --- --since / --until: filter by activity window ---
         if (opts.since) {
             const cutoff = parseTimeFilter(opts.since);
             if (!cutoff)
@@ -1414,7 +1155,6 @@ export function registerTeamsCommands(program) {
             try {
                 const picked = await teamPicker(rows, query);
                 if (picked) {
-                    // Fall through to the status subcommand's action for the picked team.
                     const mgr = mkManager();
                     const result = await handleStatus(mgr, picked.team, 'all');
                     await printTeamStatus(picked.team, result);
@@ -1426,11 +1166,8 @@ export function registerTeamsCommands(program) {
             }
             return;
         }
-        // Non-interactive fallback: rows flow without a header, matching the
-        // shape of `agents sessions` when piped.
         printTeamTable(rows);
     });
-    // create
     addHostOption(teams.command('create <team>'))
         .aliases(['c', 'new'])
         .description('Start a new team. No teammates yet; add them with `teams add`.')
@@ -1443,9 +1180,6 @@ export function registerTeamsCommands(program) {
         .option('--json', 'Output machine-readable JSON')
         .action(async (team, opts) => {
         try {
-            // Fail here, not at the first `teams add`: a team created against a
-            // project that does not resolve would silently fall back to the
-            // orchestrator's cwd for every teammate.
             if (opts.project) {
                 const { resolveProjectRef } = await import('../lib/project-root.js');
                 try {
@@ -1455,18 +1189,9 @@ export function registerTeamsCommands(program) {
                     dieFriction('teams', 'project-unresolved', err.message);
                 }
             }
-            // --devices / --hosts are aliases; commander can't express a two-name
-            // option that isn't a short flag, so merge them here. Split on comma,
-            // trim, drop blanks, dedupe (preserving first-seen order).
             const rawPool = [opts.devices, opts.hosts].filter(Boolean).join(',');
             const devices = [];
             for (const raw of rawPool.split(',').map((s) => s.trim()).filter(Boolean)) {
-                // Resolve `interactive` to the concrete device HERE, the same way the
-                // single `--device` pin does. A pool is a set of specific machines the
-                // scheduler picks between, so persisting the sentinel would let the
-                // pool's membership change silently the next time `interactive.host`
-                // is re-pinned — and every later friction message would quote
-                // "interactive" instead of a box the user can act on.
                 let d = raw;
                 if (isDeviceInteractive(d)) {
                     const pinned = resolveInteractiveDevice();
@@ -1479,9 +1204,6 @@ export function registerTeamsCommands(program) {
                 if (!devices.includes(d))
                     devices.push(d);
             }
-            // Validate every pooled device resolves + is POSIX (v1 remote monitor is
-            // POSIX-only). A device equal to the local machine is fine (runs local),
-            // so skip the resolve/POSIX check for it.
             for (const name of devices) {
                 if (name.toLowerCase() === machineId())
                     continue;
@@ -1495,9 +1217,6 @@ export function registerTeamsCommands(program) {
                         `the teams remote monitor is POSIX-only. Use a Linux/macOS device.`);
                 }
             }
-            // --repo: how each device gets the code. Default to the local checkout's
-            // origin when a pool is declared and we're inside a git repo, so the user
-            // never hand-manages a path per box. A poolless team leaves repo unset.
             let repo = opts.repo;
             if (!repo && devices.length > 0) {
                 const cwd = process.cwd();
@@ -1545,7 +1264,6 @@ export function registerTeamsCommands(program) {
             dieFriction('teams', 'create-failed', err.message);
         }
     });
-    // add
     addHostOption(teams.command('add <team> <teammate> <task>'))
         .alias('a')
         .description("Add a teammate to work on a task. Runs in background; returns immediately. Use 'status' to check in.")
@@ -1565,10 +1283,6 @@ export function registerTeamsCommands(program) {
         .option('--confirm', 'Proceed even when the base checkout/repo is behind origin/main (a stale repo otherwise blocks the add)')
         .option('--json', 'Output machine-readable JSON')
         .action(async (team, teammate, task, opts) => {
-        // `--remote-cwd` rides the shared --device option family but is never read by
-        // `teams add` (placement, not routing). Fail loud with guidance rather than
-        // silently ignoring it — see remoteCwdOnAddError. `!== undefined` so even an
-        // explicit empty value (`--remote-cwd ""`) is rejected, not silently dropped.
         if (opts.remoteCwd !== undefined) {
             dieFriction('teams', 'remote-cwd-on-add', remoteCwdOnAddError(team));
         }
@@ -1595,32 +1309,15 @@ export function registerTeamsCommands(program) {
                 dieFriction('teams', 'cloud-rush-needs-repo', `--cloud rush requires --repo <owner/repo>`);
             }
         }
-        // Auto-create the team if it doesn't exist yet (friendlier UX than erroring),
-        // then load its metadata — needed here for the distributed --repo (how each
-        // device gets the code) before we resolve a per-teammate --device pin.
         await ensureTeam(team);
         const teamMeta = await getTeam(team);
-        // For `teams add` the passthrough special-cases --device as PLACEMENT,
-        // not routing, so the local action reads it here.
         let explicitDevice = opts.device ?? null;
-        // `auto` is the same live fleet sentinel `agents run --device auto` resolves
-        // (RUSH-2185) — pick the concrete device name up front so the local-machine
-        // check right below (and every dieFriction message further down) sees the
-        // real target instead of the literal string "auto".
         if (explicitDevice && isDeviceAuto(explicitDevice)) {
             const plan = await resolveDeviceAuto(parseTeammate(teammate).agent);
             const picked = plan.host ?? machineId();
             process.stderr.write(chalk.gray(`[teams] device=auto → ${picked === machineId() ? 'local' : picked}\n`));
             explicitDevice = picked;
         }
-        // `interactive` needs the same up-front resolution, and for a sharper
-        // reason: `teams add`/`create` bail out of the fleet passthrough
-        // (passthrough.ts, the teams subcommand guard), so the sentinel block
-        // there never runs and this is the only resolver. Left literal, the
-        // local-machine check below compares 'interactive' against the machine id,
-        // takes the remote branch on the pinned box itself, and pins the teammate
-        // to an SSH hop into this same machine — skipping three local preflights
-        // on the way.
         if (explicitDevice && isDeviceInteractive(explicitDevice)) {
             const pinned = resolveInteractiveDevice();
             if (!pinned) {
@@ -1629,11 +1326,6 @@ export function registerTeamsCommands(program) {
             process.stderr.write(chalk.gray(`[teams] device=interactive → ${pinned === machineId() ? 'local' : pinned}\n`));
             explicitDevice = pinned;
         }
-        // Distributed teams: --device <name> PINS this teammate to a machine over
-        // SSH. Resolve + validate the placement here so a bad target fails at `add`
-        // time, not silently at launch. Persisted (hostName/hostTarget/repoPath) so
-        // startReady()/launchRemoteProcess dispatch over SSH. Unpinned teammates
-        // leave these null — the launch-time scheduler resolves the pool cascade.
         let hostName = null;
         let hostTarget = null;
         let hostRepoPath = null;
@@ -1647,9 +1339,6 @@ export function registerTeamsCommands(program) {
                 dieFriction('teams', 'device-not-resolvable', `Couldn't resolve --device "${explicitDevice}". Register it with \`agents devices add ${explicitDevice} <target>\`, ` +
                     `or pass user@host.`);
             }
-            // POSIX-only in v1: the remote follow/monitor layer offset-tails the log
-            // with tail/cat/kill, which don't exist under PowerShell. Refuse Windows
-            // up front, mirroring dispatch.ts launchDetached.
             if (remoteShellFor(host.os ?? resolveRemoteOsSync(host.name)) === 'powershell') {
                 dieFriction('teams', 'device-windows-unsupported', `Distributed teammates on Windows host "${host.name}" are not supported yet — ` +
                     `the teams remote monitor is POSIX-only (offset-tails the remote log with tail/cat/kill). ` +
@@ -1661,11 +1350,6 @@ export function registerTeamsCommands(program) {
             catch (err) {
                 dieFriction('teams', 'ssh-target-unresolvable', `Can't resolve an ssh target for "${host.name}": ${err.message}`);
             }
-            // Ensure agents-cli is present + the pin is installed on the host.
-            // Bare agent names still only warn; a concrete pin fails loud so
-            // `teams add --device` never stages a teammate the box cannot run
-            // (RUSH-2313). parseTeammate already resolves @latest/etc. to a concrete
-            // version when one is pinned on the teammate spec.
             try {
                 const parsed = parseTeammate(teammate);
                 const { warnings } = ensureHostReady(host, {
@@ -1678,19 +1362,10 @@ export function registerTeamsCommands(program) {
             catch (err) {
                 dieFriction('teams', 'host-not-ready', `Host "${host.name}" is not ready: ${err.message}`);
             }
-            // Provision the repo on the host from the team's --repo (clone into
-            // ~/.agents/repos/<team> or reuse an existing checkout), resolving to the
-            // ABSOLUTE git root so every later remote command works from an absolute
-            // path (dispatch `cd`, worktree create, polling). When the team has no
-            // --repo (the common "just send one teammate elsewhere" case, created
-            // without a pool), fall back to THIS checkout's origin so the headline case
-            // works with zero extra flags whenever you run `add` inside a git repo.
             let effectiveRepo = teamMeta?.repo ?? '';
             if (!effectiveRepo && (await isGitRepo(process.cwd()))) {
                 effectiveRepo = (await getRemoteUrl(process.cwd())) ?? '';
             }
-            // Capture the ssh args ensureRemoteRepo uses so the staleness probe below
-            // reaches the host with the same identity.
             hostExtraSshArgs = host.identityFile ? ['-i', host.identityFile, '-o', 'IdentitiesOnly=yes'] : [];
             try {
                 hostRepoPath = ensureRemoteRepo(hostTarget, effectiveRepo, team, {
@@ -1705,26 +1380,15 @@ export function registerTeamsCommands(program) {
         }
         const { agent, version, profileName } = parseTeammate(teammate);
         warnAgentDeprecated(agent);
-        // Version-installed check is about the LOCAL machine — a distributed (--on)
-        // teammate's agent/version lives on the host, verified by ensureHostReady.
         if (version && !hostName && !isVersionInstalled(agent, version)) {
             dieFriction('teams', 'agent-version-not-installed', `${AGENT_NAMES[agent]} ${version} isn't installed.\n` +
                 `  Install it:  agents add ${agent}@${version}\n` +
                 `  Or see what's installed (incl. @latest):  agents view ${agent}`);
         }
-        // Advisory sign-in check: warn but NEVER block. Detection is unreliable
-        // for opaque-cred agents, so a false negative must not stop a team. Cloud
-        // dispatch authenticates through the provider, not the local CLI — skip it.
-        // Distributed (--on) teammates authenticate on the host, not locally — skip.
         if (!opts.force && !cloudProviderId && !hostName && !(await checkCliSignedIn(agent))) {
             console.error(chalk.yellow(`⚠ ${AGENT_NAMES[agent]} may not be signed in (detection is unreliable). Adding anyway.`) +
                 chalk.gray(`\n  If it fails to start, run \`${AGENTS[agent].cliCommand}\` to log in, or pass --force to silence this.`));
         }
-        // Advisory throttle check — only for a version-pinned teammate, which
-        // bypasses account rotation and so can't route around a rate-limited /
-        // out-of-credits / signed-out account (see throttleWarningLine). Skip bare
-        // targets (rotation handles them), profiles (auth-injected account isn't
-        // the version-home one we can read), and cloud dispatch. Warn, never block.
         if (!opts.force && !cloudProviderId && !hostName && !profileName && version) {
             const readiness = await checkRunAccountReadiness(agent, version);
             if (!readiness.ready)
@@ -1753,27 +1417,17 @@ export function registerTeamsCommands(program) {
         catch (err) {
             dieFriction('teams', 'invalid-env', err.message);
         }
-        // Team already ensured + loaded above (teamMeta) for the --repo provisioning.
         const worktreesEnabled = teamMeta?.enable_worktrees ?? false;
         const sharedWorktree = teamMeta?.use_worktree ?? null;
         let worktreeName = null;
         let worktreePath = null;
         const mgr = mkManager();
-        // Validate name uniqueness + --after deps BEFORE creating a worktree
-        // (RUSH-2356): a rejected add must not leave an orphan `agents/<name>`
-        // branch that then breaks the retry with `fatal: a branch ... already
-        // exists`. spawn() calls the same method, which memoizes this result for
-        // exactly one consumer — so validation still lives in one place without
-        // paying for a second sibling status refresh on the way there.
         try {
             await mgr.validateAddPreconditions(team, opts.name ?? null, after);
         }
         catch (err) {
             dieFriction('teams', 'add-precondition-failed', err.message);
         }
-        // Stale-repo guard: refuse to point a team at a checkout behind origin/main
-        // unless --confirm. A cloud teammate clones fresh in the provider, so it has
-        // no local/remote checkout to assess — skip it there.
         if (!cloudProviderId) {
             if (hostName) {
                 await assertRepoFreshOrConfirm({
@@ -1790,10 +1444,6 @@ export function registerTeamsCommands(program) {
                 }
             }
         }
-        // Track a worktree WE create in this add so a later failure (dep race,
-        // launch error, cloud dispatch) can tear it down instead of stranding the
-        // branch. Only a worktree THIS add created is ever torn down, so a
-        // legitimately-pending teammate's worktree is never touched.
         let createdWorktree = null;
         const tearDownCreatedWorktree = async () => {
             if (!createdWorktree)
@@ -1803,10 +1453,6 @@ export function registerTeamsCommands(program) {
             await tearDownOrphanWorktree(mgr, baseCwd, name);
         };
         if (hostName) {
-            // Distributed teammate: the checkout lives on the host, so we NEVER touch
-            // the local filesystem here. A shared local worktree makes no sense for a
-            // remote teammate; a per-teammate worktree is created ON THE HOST at launch
-            // (createRemoteWorktree in launchRemoteProcess) — we just capture its name.
             if (sharedWorktree) {
                 dieFriction('teams', 'shared-worktree-remote-conflict', `Team '${team}' uses a shared local --use-worktree, which can't apply to a --device (remote) teammate.`);
             }
@@ -1822,10 +1468,8 @@ export function registerTeamsCommands(program) {
             else if (opts.worktree) {
                 dieFriction('teams', 'worktree-requires-enable-worktrees', `--worktree requires --enable-worktrees on the team. Recreate the team with: agents teams create ${team} --enable-worktrees`);
             }
-            // Local cwd stays null — the remote cwd is repoPath / the remote worktree.
         }
         else if (sharedWorktree) {
-            // Team uses a shared worktree for all teammates
             const fsp = await import('fs/promises');
             try {
                 const stat = await fsp.stat(sharedWorktree);
@@ -1852,12 +1496,6 @@ export function registerTeamsCommands(program) {
             if (!(await isGitRepo(baseCwd))) {
                 dieFriction('teams', 'worktree-needs-repo', `Worktrees require a git repository. ${baseCwd} is not inside a git repo.`);
             }
-            // Was anything under this name already here BEFORE we tried? That is
-            // the only sound basis for cleaning up a failed create: the common
-            // failure is `fatal: a branch named 'agents/<name>' already exists`,
-            // and removing a checkout we did not make can destroy uncommitted work
-            // (`teams stop` deliberately KEEPS a dirty worktree, and that teammate's
-            // record is terminal by then, so no record-based check protects it).
             const preexisting = await worktreeExists(baseCwd, opts.worktree).catch(() => true);
             try {
                 worktreeName = opts.worktree;
@@ -1865,22 +1503,12 @@ export function registerTeamsCommands(program) {
                 createdWorktree = { baseCwd, name: worktreeName };
             }
             catch (err) {
-                // `git worktree add -b` can also fail PART WAY — branch ref created,
-                // checkout not — stranding `agents/<name>` in exactly the way that
-                // breaks the retry. Clean that up only when nothing was here before
-                // AND there is still no checkout now: all that can be left is a
-                // dangling branch ref, so this can never delete anyone's files. The
-                // second half matters because a concurrent add can create a real
-                // worktree under this name during our `git fetch`, long after the
-                // pre-flight probe answered.
                 const checkoutNow = await worktreeCheckoutExists(baseCwd, opts.worktree).catch(() => true);
                 if (!preexisting && !checkoutNow) {
                     try {
                         await removeWorktree(baseCwd, opts.worktree);
                     }
                     catch {
-                        // Nothing to remove (the add died before git wrote anything), or
-                        // we can't. Either way the real error below is what matters.
                     }
                 }
                 const detail = err.message;
@@ -1894,17 +1522,6 @@ export function registerTeamsCommands(program) {
         else if (opts.worktree) {
             dieFriction('teams', 'worktree-requires-enable-worktrees', `--worktree requires --enable-worktrees on the team. Recreate the team with: agents teams create ${team} --enable-worktrees`);
         }
-        // The team's project (`teams create --project`) contributes a base cwd and
-        // the access grants for its other directories. It sits BELOW --cwd in the
-        // precedence chain: an explicit --cwd on this teammate still wins.
-        //
-        // Grants are attached even when a worktree or --cwd owns the cwd — the
-        // sibling repos are what the project binds, not where the teammate sits.
-        // Only the base cwd is resolved here — a LOCAL teammate needs a concrete
-        // directory to start in. The GRANTS are deliberately not resolved now:
-        // an unpinned teammate on a --devices pool is placed at launch, so its
-        // shape (absolute vs ~/…) is not yet knowable. The project name rides on
-        // the record and resolveTeammateGrants resolves it per launch.
         let projectCwd;
         if (teamMeta?.project && !hostName) {
             const { resolveProjectRef } = await import('../lib/project-root.js');
@@ -1915,29 +1532,16 @@ export function registerTeamsCommands(program) {
                 dieFriction('teams', 'project-unresolved', err.message);
             }
         }
-        // Distributed teammates have no LOCAL cwd — their working dir lives on the
-        // host (repoPath / the remote worktree). Local teammates default to the
-        // worktree path, then --cwd, then the project's primary directory, then
-        // the current directory.
         const cwd = hostName ? null : (worktreePath ?? opts.cwd ?? projectCwd ?? process.cwd());
-        // Factory teammates: prepend the worker-skill preamble to every task
-        // prompt so implementers/testers/reviewers know about the Ledger, the
-        // dynamic DAG, and the pattern for filing new tasks mid-flight. No
-        // preamble when --task-type isn't set (plain teammates work as before).
         let effectiveTask = task;
         if (taskType) {
             effectiveTask = factoryWorkerPreamble(team, opts.name ?? null, taskType, after) + '\n\n' + task;
         }
-        // Dispatcher callback: when a staged cloud teammate's deps resolve,
-        // AgentManager.startReady() invokes this to kick off the remote task.
         if (cloudProviderId) {
             const providerId = cloudProviderId;
             mgr.setCloudDispatcher(async (a) => {
                 const prov = resolveProvider(providerId);
                 const dispatchOpts = {
-                    // PHNX-3236: same self-merge boundary as the local/remote path — a
-                    // cloud teammate has no inherited merge-guard.sh, so the prompt is
-                    // its only layer.
                     prompt: withTeammatePrPolicy(a.prompt, a.mode),
                     agent: a.agentType,
                     repo: opts.repo,
@@ -2002,14 +1606,10 @@ export function registerTeamsCommands(program) {
             }
         }
         catch (err) {
-            // The add failed after we created its worktree — tear the worktree +
-            // branch down so a retry isn't blocked by `fatal: a branch ... already
-            // exists` (RUSH-2356). Best-effort: report the original failure either way.
             await tearDownCreatedWorktree();
             dieFriction('teams', 'add-failed', `Could not add ${fullName(agent, version)} to ${team}: ${err.message}`);
         }
     });
-    // status
     addHostOption(teams.command('status [team]'))
         .aliases(['s', 'st', 'check'])
         .description("Check in on a team: status, files touched, recent commands, last messages. Pass --verbose for the full per-teammate dump; --since for delta polling.")
@@ -2022,8 +1622,6 @@ export function registerTeamsCommands(program) {
         .action(async (team, opts) => {
         const filter = opts.filter;
         const mgr = mkManager();
-        // No team given → drop into the picker (TTY) or fail clearly (script).
-        // --parent-session is its own lookup key, so it needs no team at all.
         if (!team && !opts.parentSession) {
             const picked = await pickTeamOr(mgr, 'agents teams status');
             if (!picked)
@@ -2037,17 +1635,12 @@ export function registerTeamsCommands(program) {
                 : result.agents;
             const filtered = { ...result, agents };
             if (isJsonMode(opts)) {
-                // JSON output also respects --verbose. Default = compact summary
-                // shape; --verbose = full AgentStatusDetail. Same toggle covers
-                // both text and JSON so MCP-style consumers can opt into detail.
                 const payload = opts.verbose
                     ? filtered
                     : toTaskStatusSummary(filtered);
                 console.log(JSON.stringify(payload, null, 2));
                 return;
             }
-            // A --parent-session lookup spans teams, so there is no single team to
-            // check for existence — its label is the session that spawned them.
             const label = team ?? `session ${opts.parentSession.slice(0, 8)}`;
             if (team) {
                 const exists = await teamExists(team);
@@ -2069,11 +1662,9 @@ export function registerTeamsCommands(program) {
             }
         }
         catch (err) {
-            // `team` is undefined for a --parent-session lookup, which spans teams.
             dieFriction('teams', 'status-failed', `Could not check on ${team ? `team ${team}` : 'the requested session'}: ${err.message}`);
         }
     });
-    // active — list every live teammate across every team, grouped by team.
     teams
         .command('active')
         .description('List every teammate running right now, across all teams (PID-alive check).')
@@ -2109,7 +1700,6 @@ export function registerTeamsCommands(program) {
             console.log(chalk.bold(`Team ${chalk.cyan(team)}  ${chalk.gray(`(${agents.length} working)`)}`));
             for (const a of agents) {
                 const ident = a.name || shortId(a.agentId);
-                // A distributed teammate has no local pid; show its host + remote pid.
                 const pidStr = a.hostName
                     ? chalk.cyan(`on ${a.hostName}`) + (a.remotePid ? chalk.gray(` (pid ${a.remotePid})`) : '')
                     : a.pid ? chalk.yellow(`pid ${a.pid}`) : chalk.gray('pid ?');
@@ -2120,7 +1710,6 @@ export function registerTeamsCommands(program) {
         }
         console.log(chalk.gray(`${running.length} teammate${running.length === 1 ? '' : 's'} running. See 'agents sessions --active' for the full cross-context view.`));
     });
-    // start — fire any staged teammates whose --after deps have all completed
     addHostOption(teams.command('start [team]'))
         .description('Launch ready teammates independently. Failed launch/placement and blocked --after dependencies persist in status; --watch keeps draining viable DAG branches.')
         .option('--json', 'Output machine-readable JSON')
@@ -2137,10 +1726,6 @@ export function registerTeamsCommands(program) {
                 return;
             team = picked;
         }
-        // RUSH-2450: a disbanded team must not be re-startable. Orphan PENDING
-        // records can no longer resurrect after purge + saveMeta guard, but if a
-        // caller still points start at a gone team name, fail loud with a reason
-        // instead of launching nothing and looking successful.
         if (!(await teamExists(team))) {
             const orphanCount = (await mgr.listByTask(team)).length;
             const msg = orphanCount > 0
@@ -2169,8 +1754,6 @@ export function registerTeamsCommands(program) {
         const intervalMs = Math.max(1000, Number.parseInt(opts.interval, 10) * 1000 || 8000);
         const maxWaves = Math.max(1, Number.parseInt(opts.maxWaves, 10) || 1000);
         const json = isJsonMode(opts);
-        // Live budget kill-switch (issue #399). Dormant when no caps set — the
-        // factory dropping this in returns null and runSupervisor short-circuits.
         const { createTeamBudgetWatcher } = await import('../lib/budget/live-team.js');
         const budgetWatcher = createTeamBudgetWatcher({
             manager: mgr,
@@ -2204,10 +1787,6 @@ export function registerTeamsCommands(program) {
         emit('teams.complete', { module: 'teams', team, stoppedBy: result.stoppedBy, waves: result.waves, durationMs: result.elapsed_ms });
         if (result.stoppedBy === 'drained') {
             console.log(chalk.green(`Factory drained in ${elapsed}s (${result.waves} waves).`));
-            // First-successful-team star nudge (one-time, non-nagging). "drained"
-            // only means nothing is pending/running — teammates may have failed — so
-            // gate on a clean drain (failed === 0). A team where every teammate
-            // failed is not the success this nudge celebrates.
             if ((result.failed ?? 0) === 0) {
                 maybeShowStarNudge({ quiet: opts.json });
             }
@@ -2223,10 +1802,9 @@ export function registerTeamsCommands(program) {
             console.error(chalk.red(`Budget kill-switch tripped after ${result.waves} waves` +
                 (b ? ` (cap ${b.cap}: $${b.spend.toFixed(2)} > $${b.limit.toFixed(2)})` : '') +
                 `.`));
-            process.exitCode = 7; // Mirrors BUDGET_KILL_EXIT_CODE for CI/headless.
+            process.exitCode = 7;
         }
     });
-    // pr-watch — autonomous PR lifecycle (issue #338)
     addHostOption(teams.command('pr-watch [team]'))
         .description('Watch the PRs a team opened and react autonomously: RED CI -> spawn a fix teammate with the failure logs; new review comment -> route a bugfix teammate. Both slot into the team DAG (visible in `teams status`).')
         .option('--interval <seconds>', 'Seconds between polls (default 30)', '30')
@@ -2277,8 +1855,6 @@ export function registerTeamsCommands(program) {
                 console.error(`[${ts}] ${chalk.red('error')} on ${e.prUrl}: ${e.message}`);
             }
         };
-        // A fixer's dedupe guard clears once it settles, so a still-red check can
-        // spawn its next (budget-bounded) wave. Terminal = completed/failed/stopped.
         const reactionSettled = async (label) => {
             const roster = await mgr.listByTask(resolvedTeam);
             const teammate = roster.find((a) => a.name === label || shortId(a.agentId) === label);
@@ -2290,9 +1866,6 @@ export function registerTeamsCommands(program) {
         try {
             const result = await runPrWatch({
                 resolveTargets: async () => {
-                    // Drive the DAG each pass so fix/bugfix teammates staged --after a
-                    // now-completed source teammate actually launch — no separate
-                    // `teams start --watch` needed.
                     await mgr.rescanFromDisk();
                     await mgr.startReady(resolvedTeam);
                     return resolvePrWatchTargets(mgr, resolvedTeam);
@@ -2323,7 +1896,6 @@ export function registerTeamsCommands(program) {
             process.off('SIGTERM', onSig);
         }
     });
-    // stop
     addHostOption(teams.command('stop [team] [teammate]'))
         .description('Stop a running teammate. Resume it later with `agents teams resume`. Cleans up worktree if no uncommitted changes.')
         .option('--json', 'Output machine-readable JSON')
@@ -2364,12 +1936,10 @@ export function registerTeamsCommands(program) {
         const stopRes = await handleStop(mgr, team, agentId);
         if ('error' in stopRes)
             dieFriction('teams', 'stop-failed', stopRes.error);
-        // Clean up worktree if this teammate had one
         let worktreeKept = false;
         if (agent?.worktreeName && agent?.worktreePath) {
             try {
                 if (agent.hostName && agent.hostTarget && agent.repoPath) {
-                    // Distributed teammate: guard + remove the worktree ON THE HOST.
                     const ssh = { extraSshArgs: agent.hostIdentityFile ? ['-i', agent.hostIdentityFile, '-o', 'IdentitiesOnly=yes'] : [] };
                     if (remoteWorktreeDirty(agent.hostTarget, agent.worktreePath, ssh)) {
                         worktreeKept = true;
@@ -2390,7 +1960,6 @@ export function registerTeamsCommands(program) {
                 }
             }
             catch {
-                // best-effort cleanup
             }
         }
         if (isJsonMode(opts)) {
@@ -2413,11 +1982,6 @@ export function registerTeamsCommands(program) {
             console.log(chalk.yellow(`Worktree '${agent.worktreeName}' has uncommitted changes. Keeping it at: ${agent.worktreePath}`));
         }
     });
-    // message / resume — send a follow-up message to a teammate. Routes by the
-    // teammate's reconciled status: a RUNNING teammate is STEERED via its mailbox
-    // (delivered at its next tool call); a STOPPED one (completed/failed/stopped)
-    // is RESUMED — re-entering its own session with the message as the next user
-    // turn, re-attaching it to the team as live.
     async function teamMessageAction(team, ref, message, opts) {
         const mgr = mkManager();
         const lookup = await mgr.resolveAgentIdInTask(team, ref);
@@ -2428,9 +1992,6 @@ export function registerTeamsCommands(program) {
             dieFriction('teams', 'teammate-ambiguous', `'${ref}' matches multiple teammates: ${shorts}. Use more characters or a name.`, 2);
         }
         const agentId = lookup.agentId;
-        // mgr.get reconciles the teammate's status (PID + start-time guard / remote
-        // .exit sentinel / exit-code reap) before we branch — so running-vs-stopped
-        // is a fact, not a guess.
         const agent = await mgr.get(agentId);
         if (!agent)
             dieFriction('teams', 'teammate-vanished', `Teammate ${shortId(agentId)} vanished from team ${team}.`);
@@ -2449,7 +2010,6 @@ export function registerTeamsCommands(program) {
                 dieFriction('teams', 'resume-needs-message', `Teammate '${display}' is ${status} — pass a message to resume it: \`agents teams resume ${team} ${display} "<message>"\`.`);
                 return;
             case 'steer': {
-                // Running -> steer via mailbox; never re-launch (that forks a 2nd session).
                 enqueue(mailboxDir(agentId), { to: agentId, text: message, from: opts.from });
                 if (isJsonMode(opts)) {
                     console.log(JSON.stringify({ team, agent_id: agentId, name: agent.name ?? null, action: 'steer', status }, null, 2));
@@ -2460,7 +2020,6 @@ export function registerTeamsCommands(program) {
                 return;
             }
             case 'resume': {
-                // Stopped / completed / failed -> resume its own session with the message.
                 try {
                     await mgr.resumeTeammate(agentId, message);
                 }
@@ -2492,7 +2051,6 @@ export function registerTeamsCommands(program) {
         .action(async (team, ref, message, opts) => {
         await teamMessageAction(team, ref, message, opts);
     });
-    // remove
     teams
         .command('remove [team] [teammate]')
         .alias('rm')
@@ -2533,7 +2091,6 @@ export function registerTeamsCommands(program) {
         const agentId = lookup.agentId;
         const agent = await mgr.get(agentId);
         const display = agent?.name || shortId(agentId);
-        // Require agent to be stopped first
         if (agent?.status === 'running' || agent?.status === 'pending') {
             dieFriction('teams', 'remove-still-running', `Teammate '${display}' is still ${agent.status}. Run 'agents teams stop ${team} ${display}' first.`);
         }
@@ -2543,7 +2100,6 @@ export function registerTeamsCommands(program) {
                 await fs.rm(dir, { recursive: true, force: true });
             }
             catch {
-                // best-effort cleanup
             }
         }
         if (isJsonMode(opts)) {
@@ -2552,7 +2108,6 @@ export function registerTeamsCommands(program) {
         }
         console.log(chalk.green(`Removed ${chalk.cyan(display)} from team ${chalk.cyan(team)}.`));
     });
-    // disband
     teams
         .command('disband [team]')
         .alias('d')
@@ -2574,11 +2129,8 @@ export function registerTeamsCommands(program) {
         const stopRes = await handleStop(mgr, team);
         if ('error' in stopRes)
             dieFriction('teams', 'stop-failed', stopRes.error);
-        // Snapshot the roster once for worktree cleanup + messaging. Purge below
-        // is the terminal removal of teammate records (RUSH-2450).
         const status = await handleStatus(mgr, team, 'all');
         const rosterBefore = status.agents;
-        // Clean up worktrees for all teammates
         const baseCwd = process.cwd();
         const keptWorktrees = [];
         for (const a of rosterBefore) {
@@ -2586,7 +2138,6 @@ export function registerTeamsCommands(program) {
             if (agent?.worktreeName && agent?.worktreePath) {
                 try {
                     if (agent.hostName && agent.hostTarget && agent.repoPath) {
-                        // Distributed teammate: guard + remove the worktree ON THE HOST.
                         const ssh = { extraSshArgs: agent.hostIdentityFile ? ['-i', agent.hostIdentityFile, '-o', 'IdentitiesOnly=yes'] : [] };
                         if (remoteWorktreeDirty(agent.hostTarget, agent.worktreePath, ssh)) {
                             keptWorktrees.push(agent.worktreeName);
@@ -2605,14 +2156,9 @@ export function registerTeamsCommands(program) {
                         }
                     }
                 }
-                catch { /* best-effort */ }
+                catch { }
             }
         }
-        // Drop the registry entry FIRST so any concurrent supervisor's saveMeta
-        // (RUSH-2450) refuses to re-persist teammates for this team, then purge
-        // the durable teammate records + in-memory cache. Order matters: purge
-        // after removeTeam closes the race where a supervisor re-writes meta
-        // between the two steps.
         const existed = await removeTeam(team);
         const removedIds = await mgr.purgeByTask(team, { keepLogs: Boolean(opts.keepLogs) });
         if (isJsonMode(opts)) {
@@ -2626,8 +2172,6 @@ export function registerTeamsCommands(program) {
             return;
         }
         if (!existed && stopRes.stopped.length === 0 && rosterBefore.length === 0 && removedIds.length === 0) {
-            // Second disband on a fully-gone team: clean no-op, not a false success
-            // that claims N logs were cleared again.
             dieFriction('teams', 'team-not-found', `No team called '${team}' (already disbanded or never created)`, 2);
         }
         console.log(chalk.green(`Team ${chalk.cyan(team)} disbanded.`));
@@ -2643,7 +2187,6 @@ export function registerTeamsCommands(program) {
             console.log(chalk.yellow(`  Kept ${keptWorktrees.length} worktree(s) with uncommitted changes: ${keptWorktrees.join(', ')}`));
         }
     });
-    // logs
     teams
         .command('logs [teammate]')
         .alias('log')
@@ -2654,10 +2197,6 @@ export function registerTeamsCommands(program) {
         .option('--teammate <name>', 'Teammate name (alias for the positional arg; useful for scripts)')
         .action(async (ref, opts) => {
         const base = await getAgentsDir();
-        // Resolve teammate identity. Precedence:
-        //   1. positional `[teammate]` arg (back-compat, most common)
-        //   2. --teammate <name> flag (script-friendly alias)
-        //   3. interactive picker (TTY only)
         const teammateRef = ref ?? opts.teammate;
         let agentId;
         if (!teammateRef) {
@@ -2679,9 +2218,6 @@ export function registerTeamsCommands(program) {
             }
             agentId = resolved.agentId;
         }
-        // Concise by default: a teammate's agentId IS its agent session id (passed
-        // as --session-id at launch), so render the same summary digest as
-        // `agents sessions <id>`. --full / -n <lines> opt into the raw stdout.log.
         if (!opts.full && !opts.tail) {
             const all = await discoverSessions({ all: true, limit: 5000 });
             const matches = resolveSessionById(all, agentId);
@@ -2689,8 +2225,6 @@ export function registerTeamsCommands(program) {
                 await renderSessionLog(matches[0], 'summary');
                 return;
             }
-            // No resolvable session (e.g. a non-Claude teammate) — fall through to a
-            // bounded tail of raw stdout rather than dumping the whole file.
         }
         const logPath = path.join(base, agentId, 'stdout.log');
         try {
@@ -2699,7 +2233,6 @@ export function registerTeamsCommands(program) {
                 process.stdout.write(content);
                 return;
             }
-            // Default tail size keeps an un-resolvable teammate's glance bounded too.
             const n = opts.tail ? Math.max(1, parseInt(opts.tail, 10) || 50) : 40;
             const lines = content.split('\n');
             process.stdout.write(lines.slice(-n).join('\n'));
@@ -2708,7 +2241,6 @@ export function registerTeamsCommands(program) {
             dieFriction('teams', 'teammate-notes-not-found', `No notes on record for teammate '${teammateRef ?? agentId}' (looked in ${logPath})`, 2);
         }
     });
-    // doctor
     teams
         .command('doctor')
         .alias('dr')