@phnx-labs/agents-cli 1.22.33 → 1.22.34

package/dist/commands/teams.js

@@ -15,7 +15,7 @@ import { runPrWatch, DEFAULT_MAX_WAVES, } from '../lib/teams/pr-watch.js';
 import { handleSpawn, handleStatus, handleStop, toTaskStatusSummary, } from '../lib/teams/api.js';
 import { createTeam, ensureTeam, getTeam, loadTeams, removeTeam, teamExists, } from '../lib/teams/registry.js';
 import { setHelpSections } from '../lib/help.js';
-import { createWorktree, isGitRepo, hasUncommittedChanges, removeWorktree, } from '../lib/teams/worktree.js';
+import { createWorktree, isGitRepo, hasUncommittedChanges, removeWorktree, worktreeCheckoutExists, worktreeExists, } from '../lib/teams/worktree.js';
 import { resolveHost } from '../lib/hosts/registry.js';
 import { isDeviceAuto, resolveDeviceAuto } from '../lib/smart-launch.js';
 import { sshTargetFor } from '../lib/hosts/types.js';
@@ -251,6 +251,54 @@ 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))
+            return;
+    }
+    catch {
+        warnOrphanWorktree(baseCwd, name, 'the teammate record could not be read');
+        return;
+    }
+    try {
+        await removeWorktree(baseCwd, name);
+    }
+    catch (cleanupErr) {
+        warnOrphanWorktree(baseCwd, name, cleanupErr.message);
+    }
+}
+function warnOrphanWorktree(baseCwd, name, reason) {
+    process.stderr.write(chalk.yellow(`\nWarning: the worktree '${name}' from this failed add is still on disk — ${reason}.\n` +
+        `  Remove it manually: git -C ${baseCwd} worktree remove --force .agents/worktrees/${name} ` +
+        `&& git -C ${baseCwd} branch -D agents/${name}\n`));
+}
 /**
  * Register the generic cloud dispatcher — staged cloud teammates get
  * dispatched when their --after deps resolve, using repo/branch stored on
@@ -476,7 +524,27 @@ async function reactWithTeammate(mgr, team, action, prompt) {
             cwd = baseCwd;
         }
     }
-    const result = await handleSpawn(mgr, team, 'claude', prompt, cwd, 'edit', 'medium', null, cwd, null, name, after, null, null, taskType, null, null, null, null, worktreeName, worktreePath);
+    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);
+    }
+    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
@@ -1489,6 +1557,31 @@ export function registerTeamsCommands(program) {
         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);
+        }
+        // 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)
+                return;
+            const { baseCwd, name } = createdWorktree;
+            createdWorktree = null;
+            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
@@ -1539,12 +1632,43 @@ 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;
                 worktreePath = await createWorktree(baseCwd, worktreeName);
+                createdWorktree = { baseCwd, name: worktreeName };
             }
             catch (err) {
-                dieFriction('teams', 'worktree-create-failed', `Failed to create worktree '${opts.worktree}': ${err.message}`);
+                // `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;
+                const hint = /already exists/.test(detail)
+                    ? `\n  Another teammate already owns the worktree '${opts.worktree}'. Pick a different --worktree name,` +
+                        ` or free this one: agents teams status ${team}`
+                    : '';
+                dieFriction('teams', 'worktree-create-failed', `Failed to create worktree '${opts.worktree}': ${detail}${hint}`);
             }
         }
         else if (opts.worktree) {
@@ -1554,7 +1678,6 @@ export function registerTeamsCommands(program) {
         // host (repoPath / the remote worktree). Local teammates default to the
         // worktree path, then --cwd, then the current directory.
         const cwd = hostName ? null : (worktreePath ?? opts.cwd ?? process.cwd());
-        const mgr = mkManager();
         // 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
@@ -1586,20 +1709,28 @@ export function registerTeamsCommands(program) {
         if (cloudProviderId && !isStaged) {
             // Ready to run now: dispatch to the cloud provider before registering
             // the teammate so we have the remote session id up front.
-            const prov = resolveProvider(cloudProviderId);
-            const dispatchOpts = {
-                prompt: effectiveTask,
-                agent,
-                repo: opts.repo,
-                branch: opts.branch,
-                model: opts.model,
-                env: shareRuntimeEnv(),
-            };
+            //
+            // resolveProvider() and shareRuntimeEnv() are INSIDE the try on purpose:
+            // both read config (the cloud registry; `agents.yaml`'s share block) and
+            // both throw on a malformed one, and by this point the worktree already
+            // exists — leaving them outside stranded the branch with no catch at all.
             try {
+                const prov = resolveProvider(cloudProviderId);
+                const dispatchOpts = {
+                    prompt: effectiveTask,
+                    agent,
+                    repo: opts.repo,
+                    branch: opts.branch,
+                    model: opts.model,
+                    env: shareRuntimeEnv(),
+                };
                 const cloudTask = await prov.dispatch(dispatchOpts);
                 cloudSessionId = cloudTask.id;
             }
             catch (err) {
+                // Same orphan class as a failed spawn: this add already created its
+                // worktree, so a dispatch failure must not strand the branch either.
+                await tearDownCreatedWorktree();
                 dieFriction('teams', 'cloud-dispatch-failed', `Cloud dispatch failed: ${err.message}`);
             }
         }
@@ -1654,6 +1785,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}`);
         }
     });

package/dist/commands/upgrade.d.ts

@@ -0,0 +1,7 @@
+import type { Command } from 'commander';
+export interface UpgradeOptions {
+    yes?: boolean;
+}
+export type UpgradeAction = (version: string | undefined, options: UpgradeOptions) => Promise<void>;
+/** Register the public self-upgrade surface; the entry point supplies its runtime action. */
+export declare function registerUpgradeCommand(program: Command, action?: UpgradeAction): Command;

package/dist/commands/upgrade.js

@@ -0,0 +1,10 @@
+/** Register the public self-upgrade surface; the entry point supplies its runtime action. */
+export function registerUpgradeCommand(program, action) {
+    const command = program.command('upgrade')
+        .description('Upgrade agents-cli to the latest version (or a specific [version])')
+        .argument('[version]', 'Target version or dist-tag to install (default: latest)')
+        .option('-y, --yes', 'Install without an interactive confirmation prompt');
+    if (action)
+        command.action(action);
+    return command;
+}

package/dist/commands/watchdog.d.ts

@@ -17,5 +17,7 @@
  * persisted state; it never runs a tick.
  */
 import type { Command } from 'commander';
+import { type WatchdogTickResult } from '../lib/watchdog/runner.js';
+export declare function formatWatchdogTickLines(result: WatchdogTickResult, willInject: boolean, verbose?: boolean): string[];
 /** Register the `agents watchdog` command tree. */
 export declare function registerWatchdogCommand(program: Command): void;

package/dist/commands/watchdog.js

@@ -25,6 +25,8 @@ import { getConfigValue, setConfigValue } from '../lib/device-config.js';
 import { writePolicySentinel, DEFAULT_THRESHOLDS, } from '../lib/watchdog/runner.js';
 import { isWatchdogRotateEnabled, listRotateStates, setWatchdogRotateEnabled } from '../lib/watchdog/rotate.js';
 import { loadWatchdogSessions, runWatchdogPass } from '../lib/watchdog/service.js';
+import { readWatchdogEvents, WATCHDOG_LOG_PATH } from '../lib/watchdog/log.js';
+import { selectWatchdogHistory } from '../lib/watchdog/history.js';
 /** Default state dir the runner and these subcommands share. */
 function stateDir() {
     return path.join(getRuntimeStateDir(), 'watchdog');
@@ -57,39 +59,75 @@ function humanMs(ms) {
         return `${Math.round(ms / 60_000)}m`;
     return `${Math.round(ms / 1000)}s`;
 }
-function colorForOutcome(o) {
-    if (o.injected)
-        return chalk.green;
-    if (o.decision === 'rotate')
-        return chalk.magenta;
-    if (o.addressable === false)
-        return chalk.yellow;
-    if (o.stall === 'stalled' && o.decision === 'nudge')
-        return chalk.cyan;
-    return chalk.dim;
-}
 /** Render one tick's outcomes as a human status block. */
-function printTick(result, willInject) {
+function elapsedLabel(atMs, eventMs) {
+    const seconds = Math.max(0, Math.round((atMs - eventMs) / 1000));
+    if (seconds < 60)
+        return `${seconds} second${seconds === 1 ? '' : 's'} ago`;
+    const minutes = Math.round(seconds / 60);
+    if (minutes < 60)
+        return `${minutes} minute${minutes === 1 ? '' : 's'} ago`;
+    const hours = Math.round(minutes / 60);
+    if (hours < 48)
+        return `${hours} hour${hours === 1 ? '' : 's'} ago`;
+    const days = Math.round(hours / 24);
+    return `${days} day${days === 1 ? '' : 's'} ago`;
+}
+function isAttentionOutcome(outcome) {
+    return !outcome.sessionId
+        || outcome.lastActivityMs === undefined
+        || outcome.stall === 'stalled'
+        || outcome.decision !== 'skip'
+        || outcome.injected === true
+        || outcome.addressable === false
+        || outcome.rotatePhase === 'failed';
+}
+export function formatWatchdogTickLines(result, willInject, verbose = false) {
     const { counts } = result;
-    const mode = willInject ? chalk.green('nudge') : chalk.dim('dry');
-    console.log(`${chalk.bold('watchdog')} ${mode}  ` +
-        `${counts.total} live · ${counts.stalled} stalled · ` +
-        `${chalk.green(String(counts.nudged))} nudged · ` +
-        `${chalk.yellow(String(counts.unaddressable))} un-addressable` +
-        (counts.rotating > 0 ? ` · ${chalk.magenta(String(counts.rotating))} rotating` : ''));
-    for (const o of result.outcomes) {
+    const mode = willInject ? 'nudge' : 'dry';
+    const lines = [
+        `watchdog ${mode} · checked ${new Date(result.atMs).toLocaleString()} · ` +
+            `${counts.total} live · ${counts.stalled} stalled · ` +
+            `${counts.nudged} nudged · ${counts.unaddressable} un-addressable` +
+            (counts.rotating > 0 ? ` · ${counts.rotating} rotating` : ''),
+    ];
+    const visible = verbose ? result.outcomes : result.outcomes.filter(isAttentionOutcome);
+    for (const o of visible) {
         const tag = o.injected ? 'NUDGED'
             : o.decision === 'rotate' ? (o.rotatePhase === 'failed' ? 'ROTATE-FAIL' : 'ROTATE')
                 : o.addressable === false ? 'FLAGGED'
                     : o.decision === 'nudge' ? 'WOULD-NUDGE'
                         : 'skip';
-        const c = colorForOutcome(o);
-        const who = o.label || o.sessionId?.slice(0, 8) || o.kind;
-        const where = o.host ? chalk.dim(`[${o.host}]`) : '';
-        const rail = o.rail ? chalk.dim(`→${o.rail}`) : '';
-        console.log(`  ${c(tag.padEnd(11))} ${chalk.bold(who)} ${where} ${rail}`);
-        console.log(`    ${chalk.dim(o.reason)}`);
+        const id = o.sessionId?.slice(0, 8) ?? 'no-session-id';
+        const title = o.label || o.name || o.topic;
+        lines.push(`  ${tag.padEnd(11)} ${id}${title ? ` · ${title}` : ''}`);
+        const metadata = [
+            o.kind,
+            o.host,
+            o.machine ?? 'local',
+            o.project ?? (o.cwd ? path.basename(o.cwd) : undefined),
+            o.activity ?? o.status,
+            o.origin === 'routine' ? `routine ${o.routineName ?? 'unknown'}` : undefined,
+            o.owner ? `owner ${o.owner}` : undefined,
+            o.startedAtMs ? `started ${elapsedLabel(result.atMs, o.startedAtMs)}` : undefined,
+            o.lastActivityMs ? `activity ${elapsedLabel(result.atMs, o.lastActivityMs)}` : undefined,
+            o.rail ? `rail ${o.rail}` : undefined,
+        ].filter((value) => Boolean(value));
+        lines.push(`    ${metadata.join(' · ')}`);
+        if (o.cwd)
+            lines.push(`    cwd ${o.cwd}`);
+        if (o.preview)
+            lines.push(`    latest ${o.preview.replace(/\s+/g, ' ').slice(0, 140)}`);
+        lines.push(`    reason ${o.reason}`);
     }
+    const omitted = result.outcomes.length - visible.length;
+    if (omitted > 0)
+        lines.push(`  ${omitted} healthy/non-actionable session${omitted === 1 ? '' : 's'} omitted · use --verbose or --json to inspect all`);
+    return lines;
+}
+function printTick(result, willInject, verbose) {
+    for (const line of formatWatchdogTickLines(result, willInject, verbose))
+        console.log(line);
 }
 async function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
@@ -109,6 +147,7 @@ export function registerWatchdogCommand(program) {
         .option('--smart', 'Use the LLM decider (agents run) instead of the deterministic path (non-reproducible)')
         .option('--smart-agent <agent>', 'Agent the --smart decider runs as', 'claude')
         .option('--allow-ghostty-focus', 'Permit the coarse, focus-stealing Ghostty path (off by default)')
+        .option('--verbose', 'Show healthy and non-actionable session inspections too')
         .option('--json', 'Emit the tick result as JSON (for the menu-bar / scripts)')
         .action(async (opts) => {
         const thresholds = {
@@ -139,7 +178,7 @@ export function registerWatchdogCommand(program) {
             if (opts.json)
                 console.log(JSON.stringify(result, null, 2));
             else
-                printTick(result, willInject);
+                printTick(result, willInject, opts.verbose === true);
             return;
         }
         // Manual poll loop for ad-hoc use; the daemon owns the automatic cadence.
@@ -157,7 +196,7 @@ export function registerWatchdogCommand(program) {
             if (opts.json)
                 console.log(JSON.stringify(result));
             else
-                printTick(result, willInject);
+                printTick(result, willInject, opts.verbose === true);
             await sleep(intervalMs);
         }
     });
@@ -181,6 +220,12 @@ export function registerWatchdogCommand(program) {
       # Show device enablement, rotate config, and in-flight rotates
       agents watchdog status
 
+      # Show what Watchdog decided and acted on during the last day
+      agents watchdog history --since 24h
+
+      # Follow one session's Watchdog decisions
+      agents watchdog history <sessionId>
+
       # Leave one session detected-but-untouched
       agents watchdog policy <sessionId> handsoff
 
@@ -302,6 +347,46 @@ export function registerWatchdogCommand(program) {
             console.log(`  ${chalk.magenta(r.phase.padEnd(12))} ${chalk.bold(r.sessionId.slice(0, 8))} → ${r.newSessionId.slice(0, 8)}${r.error ? chalk.red(`  ${r.error}`) : ''}`);
         }
         console.log(`state dir: ${chalk.dim(stateDir())}`);
+        console.log(`history: ${chalk.dim('agents watchdog history')}`);
+    });
+    cmd.command('history [sessionId]')
+        .description('Show persisted Watchdog decisions and actions, newest first.')
+        .option('--limit <count>', 'Maximum events to show', '50')
+        .option('--since <duration>', 'Only events within a duration such as 2h or 7d')
+        .option('--all', 'Include heartbeat tick events')
+        .option('--json', 'Emit safe structured history (transcript content is excluded)')
+        .action((sessionId, opts, command) => {
+        const globals = command.optsWithGlobals();
+        const limit = Number.parseInt(opts.limit, 10);
+        if (!Number.isInteger(limit) || limit < 1) {
+            throw new Error('--limit must be a positive integer');
+        }
+        const sinceSeconds = opts.since === undefined ? undefined : parseDuration(opts.since);
+        if (sinceSeconds !== undefined && (sinceSeconds === null || sinceSeconds <= 0)) {
+            throw new Error('--since must be a positive duration such as 2h or 7d');
+        }
+        const sinceMs = sinceSeconds == null ? undefined : sinceSeconds * 1000;
+        const entries = selectWatchdogHistory(readWatchdogEvents(), {
+            limit,
+            sinceMs,
+            sessionId,
+            includeTicks: opts.all === true,
+        });
+        if (globals.json === true) {
+            console.log(JSON.stringify({ logPath: WATCHDOG_LOG_PATH, events: entries }, null, 2));
+            return;
+        }
+        if (entries.length === 0) {
+            console.log(chalk.dim(`No Watchdog events found in ${WATCHDOG_LOG_PATH}`));
+            return;
+        }
+        for (const entry of entries) {
+            const when = new Date(entry.ts).toLocaleString();
+            const session = entry.sessionId ? entry.sessionId.slice(0, 8) : '-';
+            const reason = entry.reason ? ` · ${entry.reason}` : '';
+            console.log(`${chalk.dim(when)}  ${entry.kind.padEnd(8)}  ${chalk.bold(session)}  ${entry.agent ?? '-'}  ${entry.message}${reason}`);
+        }
+        console.log(chalk.dim(`${entries.length} event${entries.length === 1 ? '' : 's'} · ${WATCHDOG_LOG_PATH}`));
     });
     // --- per-session policy ----------------------------------------------------
     cmd.command('policy <sessionId> <policy>')

package/dist/index.js

@@ -11,6 +11,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
 import { detectDevBuild } from './lib/startup/dev-build.js';
+import { configureRootCommand } from './lib/startup/root-command.js';
 // `ora`, `@inquirer/prompts`, `./commands/utils.js`, and the agents/versions/shims
 // modules are imported dynamically at their use sites: they are needed only on
 // interactive / update / shim-repair paths, never for fast commands like
@@ -71,6 +72,7 @@ if (process.argv[2] === SYNC_GET_CMD ||
     process.exit(code);
 }
 import { NPM_PACKAGE_NAME, deriveGlobalPrefix, detectPackageManager, installPackageIntoPrefix, installPackageWithBun, verifyInstalledVersion, refreshAliasShims, downloadVerifiedTarball, } from './lib/self-update.js';
+import { registerUpgradeCommand } from './commands/upgrade.js';
 // Detect dev/working-tree builds and default the noisy startup steps off.
 // Three cases trip this:
 //   1. Dev install (scripts/install.sh) — package.json version stamped 0.0.0-dev.<sha>
@@ -140,14 +142,7 @@ if (process.argv[2] === '__daemon-tick') {
 // CLI presents its own name/help/errors as the brand. Unbranded (AGENTS_BRAND
 // unset) resolves to 'agents' and everything below is byte-identical to before.
 const BRAND = resolveBrandName();
-const program = new Command();
-program
-    .name(BRAND)
-    .description('Environment manager for AI agents')
-    .version(VERSION)
-    .option('--verbose', 'Show startup self-heal details on stderr')
-    .helpOption('-h, --help', 'Show help')
-    .addHelpCommand(false);
+const program = configureRootCommand(new Command(), BRAND, VERSION);
 // ─── Audit backbone ────────────────────────────────────────────────────────────
 // One choke point logs every `agents <module> <cmd>` invocation to the structured
 // event log — so team create/disband, agent run, secrets access, and everything
@@ -805,59 +800,56 @@ function registerInternalCommand(p) {
         process.exit(0);
     });
 }
-/** Self-upgrade command (`agents upgrade [version]`). */
-function registerUpgradeCommand(p) {
-    p.command('upgrade')
-        .description('Upgrade agents-cli to the latest version (or a specific [version])')
-        .argument('[version]', 'Target version or dist-tag to install (default: latest)')
-        .option('-y, --yes', 'Install without an interactive confirmation prompt')
-        .action(async (version, options) => {
-        const { default: ora } = await import('ora');
-        const { confirm } = await import('@inquirer/prompts');
-        const { isInteractiveTerminal, isPromptCancelled } = await import('./commands/utils.js');
-        const target = version ?? 'latest';
-        let spinner = ora(version ? `Resolving ${NPM_PACKAGE_NAME}@${target}...` : 'Checking for updates...').start();
-        try {
-            const metadata = await fetchNpmPackageMetadata(target);
-            const resolvedVersion = metadata.version;
-            if (resolvedVersion === VERSION) {
-                spinner.succeed(`Already on ${VERSION}`);
-                return;
-            }
-            // For `latest` (no explicit version) skip when already ahead. When a
-            // version is named explicitly, honor it even if it's a downgrade.
-            if (!version && compareVersions(resolvedVersion, VERSION) <= 0) {
-                spinner.succeed(`Already ahead of latest (${VERSION} >= ${resolvedVersion})`);
+/** Runtime action for the shared `agents upgrade [version]` command definition. */
+async function runUpgrade(version, options) {
+    const { default: ora } = await import('ora');
+    const { confirm } = await import('@inquirer/prompts');
+    const { isInteractiveTerminal, isPromptCancelled } = await import('./commands/utils.js');
+    const target = version ?? 'latest';
+    let spinner = ora(version ? `Resolving ${NPM_PACKAGE_NAME}@${target}...` : 'Checking for updates...').start();
+    try {
+        const metadata = await fetchNpmPackageMetadata(target);
+        const resolvedVersion = metadata.version;
+        if (resolvedVersion === VERSION) {
+            spinner.succeed(`Already on ${VERSION}`);
+            return;
+        }
+        // For `latest` (no explicit version) skip when already ahead. When a
+        // version is named explicitly, honor it even if it's a downgrade.
+        if (!version && compareVersions(resolvedVersion, VERSION) <= 0) {
+            spinner.succeed(`Already ahead of latest (${VERSION} >= ${resolvedVersion})`);
+            return;
+        }
+        const direction = compareVersions(resolvedVersion, VERSION) < 0 ? 'Downgrade' : 'Upgrade';
+        spinner.succeed(`Resolved ${NPM_PACKAGE_NAME}@${resolvedVersion}`);
+        printResolvedPackage(metadata);
+        if (isInteractiveTerminal() && !options.yes) {
+            const approved = await confirm({
+                message: `Install ${NPM_PACKAGE_NAME}@${resolvedVersion}?`,
+                default: false,
+            });
+            if (!approved) {
+                console.log(chalk.gray('Upgrade cancelled'));
                 return;
             }
-            const direction = compareVersions(resolvedVersion, VERSION) < 0 ? 'Downgrade' : 'Upgrade';
-            spinner.succeed(`Resolved ${NPM_PACKAGE_NAME}@${resolvedVersion}`);
-            printResolvedPackage(metadata);
-            if (isInteractiveTerminal() && !options.yes) {
-                const approved = await confirm({
-                    message: `Install ${NPM_PACKAGE_NAME}@${resolvedVersion}?`,
-                    default: false,
-                });
-                if (!approved) {
-                    console.log(chalk.gray('Upgrade cancelled'));
-                    return;
-                }
-            }
-            spinner = ora(`${direction === 'Downgrade' ? 'Downgrading' : 'Upgrading'} ${VERSION} -> ${resolvedVersion}...`).start();
-            await installResolvedPackage(metadata);
-            spinner.succeed(`${direction}d to ${resolvedVersion}`);
-            // Only show the changelog for a genuine upgrade range.
-            if (compareVersions(resolvedVersion, VERSION) > 0) {
-                await showWhatsNew(VERSION, resolvedVersion);
-            }
         }
-        catch (err) {
-            if (isPromptCancelled(err))
-                return;
-            spinner.fail(`Upgrade failed: ${err instanceof Error ? err.message : String(err)}`);
-            console.log(chalk.gray(`Run manually: agents upgrade ${version ? version + ' ' : ''}--yes`));
+        spinner = ora(`${direction === 'Downgrade' ? 'Downgrading' : 'Upgrading'} ${VERSION} -> ${resolvedVersion}...`).start();
+        await installResolvedPackage(metadata);
+        spinner.succeed(`${direction}d to ${resolvedVersion}`);
+        // Only show the changelog for a genuine upgrade range.
+        if (compareVersions(resolvedVersion, VERSION) > 0) {
+            await showWhatsNew(VERSION, resolvedVersion);
         }
-    });
+    }
+    catch (err) {
+        if (isPromptCancelled(err))
+            return;
+        spinner.fail(`Upgrade failed: ${err instanceof Error ? err.message : String(err)}`);
+        console.log(chalk.gray(`Run manually: agents upgrade ${version ? version + ' ' : ''}--yes`));
+    }
+}
+function registerUpgradeRuntimeCommand(p) {
+    registerUpgradeCommand(p, runUpgrade);
 }
 // --- Lazy registration orchestration -----------------------------------------
 /** Import a command module via its loader and register it on the program. */
@@ -905,7 +897,7 @@ async function registerEagerForRequest(name) {
             registerInternalCommand(program);
             return true;
         case 'upgrade':
-            registerUpgradeCommand(program);
+            registerUpgradeRuntimeCommand(program);
             return true;
     }
     const loaders = COMMAND_LOADERS[name];
@@ -1008,7 +1000,7 @@ async function registerAllEagerCommands() {
     registerJobsCronAliasCommand(program, 'jobs');
     registerJobsCronAliasCommand(program, 'cron');
     registerInternalCommand(program);
-    registerUpgradeCommand(program);
+    registerUpgradeRuntimeCommand(program);
     await reg(loadPull);
     await reg(loadPush);
     await reg(loadRepo);

package/dist/lib/agents.js

@@ -1351,6 +1351,12 @@ const CREDENTIAL_FILE_SEGMENTS = {
     // Muse Code stores OAuth / API credentials at ~/.config/muse/auth.json
     // (or META_API_KEY in the environment, which is not a file).
     muse: [['.config', 'muse', 'auth.json']],
+    // Cursor's OAuth token — the login gate — is at $XDG_CONFIG_HOME/cursor/auth.json
+    // (~/.config/cursor/auth.json by default). cli-config.json holds only account
+    // metadata; the token file is what a real launch authenticates from, so a
+    // version home with no token of its own is genuinely logged out once runs pin
+    // XDG_CONFIG_HOME per home (see buildExecEnv).
+    cursor: [['.config', 'cursor', 'auth.json']],
 };
 /** Whether an agent's credential file exists under a given home. */
 function credentialFileExistsUnder(agentId, home) {