@phnx-labs/agents-cli 1.22.33 → 1.22.34

package/dist/lib/secrets/agent.js

@@ -760,6 +760,9 @@ export async function runSecretsAgent(opts = {}) {
     }
     let watcher = null;
     let sweepTimer = null;
+    // Sync cleanup for SIGTERM/SIGINT → process.exit: we cannot await the
+    // server's 'close' event before exit, so fire-and-forget close + unlink.
+    // The public close() path below awaits with a bounded timeout (RUSH-2421).
     cleanupActive = () => {
         store.clear();
         if (sweepTimer)
@@ -806,12 +809,25 @@ export async function runSecretsAgent(opts = {}) {
         watcher = null;
     }
     return {
-        close() {
+        async close() {
             if (shuttingDown)
                 return;
             shuttingDown = true;
             detachSignals();
-            cleanupActive?.();
+            store.clear();
+            if (sweepTimer)
+                clearInterval(sweepTimer);
+            try {
+                watcher?.kill();
+            }
+            catch { /* already gone */ }
+            await closeServerBounded(server);
+            try {
+                fs.unlinkSync(sock);
+            }
+            catch { /* gone */ }
+            releaseBrokerPid();
+            releasePid();
         },
     };
 }
@@ -877,17 +893,18 @@ export async function startHostedBroker() {
         watcher = null;
     }
     return {
-        close() {
+        // RUSH-2421: await net.Server's 'close' (bounded) so a caller relying on
+        // close() cannot proceed past a socket that is not actually released yet.
+        // The daemon may fire-and-forget this promise; tests and any awaiter get
+        // the real release boundary.
+        async close() {
             store.clear();
             clearInterval(sweepTimer);
             try {
                 watcher?.kill();
             }
             catch { /* already gone */ }
-            try {
-                server.close();
-            }
-            catch { /* not listening */ }
+            await closeServerBounded(server);
             try {
                 fs.unlinkSync(sock);
             }
@@ -896,6 +913,34 @@ export async function startHostedBroker() {
         },
     };
 }
+/** How long to wait for net.Server.close()'s 'close' event before giving up. */
+const SERVER_CLOSE_TIMEOUT_MS = 2_000;
+/**
+ * Call Node's net.Server.close() and wait for the 'close' event (or a bounded
+ * timeout). Without this, close() returned while the listen socket could still
+ * be held — a successor bind could race EADDRINUSE against a half-closed server
+ * (RUSH-2421). Pure side-effect helper; never throws.
+ */
+export function closeServerBounded(server, timeoutMs = SERVER_CLOSE_TIMEOUT_MS) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve();
+        };
+        const timer = setTimeout(finish, timeoutMs);
+        try {
+            server.close(() => finish());
+        }
+        catch {
+            // Already closed / not listening — treat as released.
+            finish();
+        }
+    });
+}
 // ─── Client ──────────────────────────────────────────────────────────────────
 /** Open the socket, send one request, resolve the one response. Async path —
  * used by the unlock/lock/status commands, which already run in async actions. */

package/dist/lib/secrets/reaper.d.ts

@@ -31,9 +31,17 @@ export interface KeychainProcessSnapshot {
      * True when this process is a REAP-ELIGIBLE helper invocation — the installed
      * helper binary running a short-lived keychain verb. False for a non-helper
      * process AND for the long-lived `watch-lock` watcher (see
-     * {@link isReapableHelperCommand}), which must never be reaped.
+     * {@link isReapableHelperCommand}).
      */
     isHelper: boolean;
+    /**
+     * True when this process is the deliberately long-lived `watch-lock` watcher
+     * (auto-lock-on-sleep). Mutually exclusive with {@link isHelper}:
+     * {@link isReapableHelperCommand} keeps live-parent watch-locks out of the
+     * stuck-helper path, and a SEPARATE orphan path in {@link planKeychainReap}
+     * reaps them only once the owning daemon is provably dead (RUSH-2419).
+     */
+    isWatchLock?: boolean;
 }
 /**
  * Tracked state for a stuck `agents` parent that has a live helper child.
@@ -59,7 +67,7 @@ export interface ReapPlan {
  * Pure predicate: decide which processes to kill given a `ps`-like snapshot.
  *
  * Mirrors the shape of {@link isExpiredPoolStray} in `lib/crabbox/lease.ts`:
- * a side-effect-free classifier that the impure driver shells `ps` for. Two
+ * a side-effect-free classifier that the impure driver shells `ps` for. Three
  * conservative reap classes:
  *
  *   1. Orphaned helper: PPID == 1, path-matches the helper, alive longer than
@@ -68,9 +76,15 @@ export interface ReapPlan {
  *      {@link STUCK_GRACE_SEC}. Recorded on first sight, child killed on the
  *      second consecutive sweep with the same PID + startTime, parent killed on
  *      the third sweep if the helper child is still present.
+ *   3. Orphaned `watch-lock` watcher (RUSH-2419): the long-lived auto-lock
+ *      child whose owning daemon is provably dead. {@link isReapableHelperCommand}
+ *      still excludes live-parent watch-locks from class 1/2; this path only
+ *      reaps when the parent is gone from the snapshot (Unix reparents to init
+ *      after daemon death) and the watcher itself has a start-time fingerprint.
  *
  * Never reaps a process whose start time could not be captured, whose path does
- * not match the helper, or whose parent is no longer in the snapshot.
+ * not match the helper, or (for stuck parents) whose parent is no longer in the
+ * snapshot. A watch-lock whose parent IS still in the snapshot is never touched.
  */
 export declare function planKeychainReap(snapshots: KeychainProcessSnapshot[], now: number, prevCandidates: ReadonlyMap<number, StuckParentCandidate>): ReapPlan;
 /**
@@ -92,6 +106,13 @@ export declare function parseEtimeToSeconds(raw: string): number | null;
  * mistaken for a stuck read and killed. Pure; unit-tested.
  */
 export declare function isReapableHelperCommand(command: string, helperPath: string): boolean;
+/**
+ * Whether a `ps` command line is the deliberately long-lived `watch-lock`
+ * watcher (auto-lock-on-sleep). Inverse of {@link isReapableHelperCommand} for
+ * the watch-lock verb only — used by the orphaned-watch-lock reaper path
+ * (RUSH-2419). Pure; unit-tested.
+ */
+export declare function isWatchLockHelperCommand(command: string, helperPath: string): boolean;
 /** Test seam: reset the persisted candidate state. */
 export declare function resetKeychainReaperCandidatesForTest(): void;
 /**

package/dist/lib/secrets/reaper.js

@@ -23,7 +23,7 @@ export const STUCK_GRACE_SEC = 90;
  * Pure predicate: decide which processes to kill given a `ps`-like snapshot.
  *
  * Mirrors the shape of {@link isExpiredPoolStray} in `lib/crabbox/lease.ts`:
- * a side-effect-free classifier that the impure driver shells `ps` for. Two
+ * a side-effect-free classifier that the impure driver shells `ps` for. Three
  * conservative reap classes:
  *
  *   1. Orphaned helper: PPID == 1, path-matches the helper, alive longer than
@@ -32,9 +32,15 @@ export const STUCK_GRACE_SEC = 90;
  *      {@link STUCK_GRACE_SEC}. Recorded on first sight, child killed on the
  *      second consecutive sweep with the same PID + startTime, parent killed on
  *      the third sweep if the helper child is still present.
+ *   3. Orphaned `watch-lock` watcher (RUSH-2419): the long-lived auto-lock
+ *      child whose owning daemon is provably dead. {@link isReapableHelperCommand}
+ *      still excludes live-parent watch-locks from class 1/2; this path only
+ *      reaps when the parent is gone from the snapshot (Unix reparents to init
+ *      after daemon death) and the watcher itself has a start-time fingerprint.
  *
  * Never reaps a process whose start time could not be captured, whose path does
- * not match the helper, or whose parent is no longer in the snapshot.
+ * not match the helper, or (for stuck parents) whose parent is no longer in the
+ * snapshot. A watch-lock whose parent IS still in the snapshot is never touched.
  */
 export function planKeychainReap(snapshots, now, prevCandidates) {
     const pidMap = new Map(snapshots.map((s) => [s.pid, s]));
@@ -88,6 +94,34 @@ export function planKeychainReap(snapshots, now, prevCandidates) {
             stage: 'watch',
         });
     }
+    // Separate path for orphaned watch-lock watchers (RUSH-2419). Does NOT
+    // weaken {@link isReapableHelperCommand}: a watch-lock with a live parent
+    // stays isHelper=false and is skipped above. Here we only kill when the
+    // owning daemon is provably absent from the process table.
+    for (const s of snapshots) {
+        if (!s.isWatchLock)
+            continue;
+        // Fail closed: no start-time fingerprint → refuse to kill (pid-reuse guard
+        // for the process we are about to target, same as orphan helpers).
+        if (s.startTime == null)
+            continue;
+        if (s.elapsedSec <= ORPHAN_GRACE_SEC)
+            continue;
+        // Live parent in this snapshot → owning daemon is still up. Leave it alone
+        // (this is the property isReapableHelperCommand protects for stuck-helper
+        // reaping; re-assert it here so a mis-tagged row cannot be killed either).
+        if (s.ppid !== 1) {
+            const parent = pidMap.get(s.ppid);
+            if (parent)
+                continue;
+            // Parent pid not listed: the process occupying that slot is gone. On Unix
+            // a dead parent reparents the child to init; a missing parent with a
+            // non-1 ppid is the race window before reparenting. Either way the owner
+            // is dead — safe to reap after grace + fingerprint.
+        }
+        // ppid===1 (reparented to init/launchd) or parent missing → orphaned.
+        kill.push(s.pid);
+    }
     return { kill, nextCandidates };
 }
 /**
@@ -159,6 +193,18 @@ export function isReapableHelperCommand(command, helperPath) {
     const firstArg = command.slice(helperPath.length + 1).trimStart().split(/\s+/)[0];
     return firstArg !== HELPER_WATCH_LOCK_VERB;
 }
+/**
+ * Whether a `ps` command line is the deliberately long-lived `watch-lock`
+ * watcher (auto-lock-on-sleep). Inverse of {@link isReapableHelperCommand} for
+ * the watch-lock verb only — used by the orphaned-watch-lock reaper path
+ * (RUSH-2419). Pure; unit-tested.
+ */
+export function isWatchLockHelperCommand(command, helperPath) {
+    if (!command.startsWith(`${helperPath} `))
+        return false;
+    const firstArg = command.slice(helperPath.length + 1).trimStart().split(/\s+/)[0];
+    return firstArg === HELPER_WATCH_LOCK_VERB;
+}
 /** Module-state for the two-sweep stuck-parent debounce. */
 let stuckParentCandidates = new Map();
 /** Test seam: reset the persisted candidate state. */
@@ -206,16 +252,18 @@ export function reapOrphanedKeychainProcesses() {
         // Reap-eligible = the helper binary running a short-lived keychain verb. The
         // full-argv match excludes the deliberately long-lived `watch-lock` watcher,
         // whose live-parent child would otherwise be killed as if it were stuck
-        // (RUSH-2232 — that silently disabled auto-lock-on-sleep).
+        // (RUSH-2232 — that silently disabled auto-lock-on-sleep). Orphaned
+        // watch-locks are tracked separately via isWatchLock (RUSH-2419).
         const isHelper = isReapableHelperCommand(command, helperPath);
-        rows.push({ pid, ppid, elapsedSec, isHelper, startTime: null });
+        const isWatchLock = isWatchLockHelperCommand(command, helperPath);
+        rows.push({ pid, ppid, elapsedSec, isHelper, isWatchLock, startTime: null });
     }
     const rowByPid = new Map(rows.map((r) => [r.pid, r]));
     for (const row of rows) {
-        if (!row.isHelper)
+        if (!row.isHelper && !row.isWatchLock)
             continue;
         row.startTime = captureProcessStartTime(row.pid);
-        if (row.ppid !== 1 && row.elapsedSec > STUCK_GRACE_SEC) {
+        if (row.isHelper && row.ppid !== 1 && row.elapsedSec > STUCK_GRACE_SEC) {
             const parent = rowByPid.get(row.ppid);
             if (parent && parent.startTime === null) {
                 parent.startTime = captureProcessStartTime(row.ppid);
@@ -228,6 +276,7 @@ export function reapOrphanedKeychainProcesses() {
         elapsedSec: r.elapsedSec,
         startTime: r.startTime,
         isHelper: r.isHelper,
+        isWatchLock: r.isWatchLock,
     }));
     const plan = planKeychainReap(snapshots, Date.now(), stuckParentCandidates);
     stuckParentCandidates = plan.nextCandidates;

package/dist/lib/session/discover.js

@@ -442,6 +442,18 @@ function normalizeCwd(cwd) {
     if (process.platform === 'win32' && /^\//.test(cwd) && !/^[a-zA-Z]:/.test(cwd)) {
         return stripTrailingSep(path.posix.normalize(cwd));
     }
+    // The mirror case (RUSH-2358): a Windows-rooted path (`C:\...`, `C:/...`, or a
+    // UNC `\\server\share\...`) read on POSIX belongs to another machine too, but
+    // `path.isAbsolute()` here uses POSIX rules and doesn't recognize a drive
+    // letter — without this branch such a cwd falls into the `path.resolve()` arm
+    // below and gets silently prefixed with THIS process's own cwd, corrupting the
+    // path (and, via WORKTREE_RE, can misattribute the worktree slug to whatever
+    // worktree the reading process happens to be running in). Normalize with
+    // win32 rules so separators survive; never realpath it, for the same
+    // cross-drive reason as the mirror branch above.
+    if (process.platform !== 'win32' && /^([a-zA-Z]:[\\/]|\\\\)/.test(cwd)) {
+        return stripTrailingSep(path.win32.normalize(cwd));
+    }
     const normalized = path.isAbsolute(cwd) ? stripTrailingSep(path.normalize(cwd)) : path.resolve(cwd);
     return safeRealpathSync(normalized) || normalized;
 }

package/dist/lib/session/render.d.ts

@@ -67,6 +67,8 @@ export interface SessionStats {
 export declare function computeSummaryStats(events: SessionEvent[]): SessionStats;
 /** Strip the 'claude-' prefix and date suffix from a model identifier. */
 export declare function shortenModel(model: string): string;
+/** Format a token count as a human-readable string (e.g. 67.5K, 1.2M). */
+export declare function formatTokenCount(n: number): string;
 /** Format a duration in milliseconds as a human-readable string (e.g. '12 min', '2h 30min'). */
 export declare function formatDuration(ms: number): string;
 /**

package/dist/lib/session/render.js

@@ -219,7 +219,7 @@ export function shortenModel(model) {
     return model.replace(/^claude-/, '').replace(/-\d{8}$/, '');
 }
 /** Format a token count as a human-readable string (e.g. 67.5K, 1.2M). */
-function formatTokenCount(n) {
+export function formatTokenCount(n) {
     if (n === 0)
         return '0';
     if (n < 1000)

package/dist/lib/shims.js

@@ -933,7 +933,7 @@ function assertSafeVersion(version) {
  * KEEP IN SYNC with the `managedEnv` switch in `generateVersionedAliasScript`.
  * The colocated test `shims.isolation-capability.test.ts` enforces this.
  */
-export const CONFIG_ENV_ISOLATED_AGENTS = ['claude', 'codex', 'copilot', 'grok', 'kimi', 'opencode', 'muse'];
+export const CONFIG_ENV_ISOLATED_AGENTS = ['claude', 'codex', 'copilot', 'cursor', 'grok', 'kimi', 'opencode', 'muse'];
 /**
  * Whether an agent supports a clean `--isolated` install — i.e. its config
  * location can be redirected by an env var so the isolated copy stays fully
@@ -999,7 +999,14 @@ export KIMI_CODE_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/
 export XDG_CONFIG_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/.config"
 export XDG_DATA_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/.local/share"
 `
-                                : '';
+                                : agent === 'cursor'
+                                    ? `
+# Cursor: no config-dir env var. Its OAuth token (the login gate) lives at
+# $XDG_CONFIG_HOME/cursor/auth.json, so pin XDG_CONFIG_HOME at the version home
+# to isolate each account's login for direct aliases (parity with buildExecEnv).
+export XDG_CONFIG_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/.config"
+`
+                                    : '';
     const launchArgs = agent === 'codex' ? ` ${codexShimLaunchArgs()}` : '';
     // Resolve the binary the same way the main shim does (see generateShimScript).
     // Grok and Droid do NOT ship into node_modules/.bin — Grok downloads a native

package/dist/lib/startup/command-registry.d.ts

@@ -98,6 +98,7 @@ export declare const loadPush: ModuleLoader;
 export declare const loadRepo: ModuleLoader;
 export declare const loadSetup: ModuleLoader;
 export declare const loadUninstall: ModuleLoader;
+export declare const loadUpgrade: ModuleLoader;
 export declare const loadSessions: ModuleLoader;
 export declare const loadTeams: ModuleLoader;
 export declare const loadCloud: ModuleLoader;

package/dist/lib/startup/command-registry.js

@@ -19,6 +19,9 @@
  * `cleanup` subcommand to it), in that order — see commands/prune.ts.
  */
 import { Command } from 'commander';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { configureRootCommand } from './root-command.js';
 // One loader per command module. Each dynamically imports the module and hands
 // back its register function. Kept as named consts so src/index.ts can compose
 // them into the exact main-branch registration order for the slow path.
@@ -98,6 +101,7 @@ export const loadPush = async () => (await import('../../commands/push.js')).reg
 export const loadRepo = async () => (await import('../../commands/repo.js')).registerRepoCommands;
 export const loadSetup = async () => (await import('../../commands/setup.js')).registerSetupCommand;
 export const loadUninstall = async () => (await import('../../commands/uninstall.js')).registerUninstallCommands;
+export const loadUpgrade = async () => (await import('../../commands/upgrade.js')).registerUpgradeCommand;
 export const loadSessions = async () => (await import('../../commands/sessions.js')).registerSessionsCommands;
 export const loadTeams = async () => (await import('../../commands/teams.js')).registerTeamsCommands;
 export const loadCloud = async () => (await import('../../commands/cloud.js')).registerCloudCommands;
@@ -247,6 +251,7 @@ export const COMMAND_LOADERS = {
     repo: [loadRepo],
     setup: [loadSetup],
     uninstall: [loadUninstall],
+    upgrade: [loadUpgrade],
     sessions: [loadSessions],
     // Observe-umbrella alias of sessions --active (same lazy module).
     roster: [loadSessions],
@@ -272,7 +277,7 @@ export const COMMAND_LOADERS = {
 /**
  * Top-level names that {@link COMMAND_LOADERS} does not carry because they are
  * registered inline in src/index.ts — closures over entry-point state (the
- * deprecated aliases and tombstones) plus the internal/upgrade commands. They are
+ * deprecated aliases and tombstones) plus the internal command. They are
  * real commands, so anything that asks "does this command exist?" must count them.
  */
 const INLINE_COMMAND_NAMES = [
@@ -284,7 +289,6 @@ const INLINE_COMMAND_NAMES = [
     'resources', // tombstone -> view --merged
     'hq', // tombstone
     '_internal',
-    'upgrade',
 ];
 /**
  * Every top-level command name the CLI answers to — the loader table plus the
@@ -318,7 +322,8 @@ export function isKnownTopLevelCommand(name) {
  * are closures over entry-point state that src/index.ts registers directly.
  */
 export async function buildFullCommandTree() {
-    const program = new Command();
+    const packageJson = JSON.parse(readFileSync(fileURLToPath(new URL('../../../package.json', import.meta.url)), 'utf8'));
+    const program = configureRootCommand(new Command(), 'agents', packageJson.version);
     const done = new Set();
     for (const loaders of Object.values(COMMAND_LOADERS)) {
         for (const loader of loaders) {

package/dist/lib/startup/root-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+/** Configure the public root surface shared by the live CLI and reference generator. */
+export declare function configureRootCommand(program: Command, name: string, version: string): Command;

package/dist/lib/startup/root-command.js

@@ -0,0 +1,10 @@
+/** Configure the public root surface shared by the live CLI and reference generator. */
+export function configureRootCommand(program, name, version) {
+    return program
+        .name(name)
+        .description('Environment manager for AI agents')
+        .version(version)
+        .option('--verbose', 'Show startup self-heal details on stderr')
+        .helpOption('-h, --help', 'Show help')
+        .addHelpCommand(false);
+}

package/dist/lib/teams/agents.d.ts

@@ -15,6 +15,45 @@ export declare enum AgentStatus {
     FAILED = "failed",
     STOPPED = "stopped"
 }
+/**
+ * The statuses a teammate can never leave — its process has run and finished
+ * (or been stopped). Everything else (pending, running) is still live work.
+ *
+ * This is the ONLY set that retention (cleanupOldAgents) may reap: a `pending`
+ * teammate has not launched yet and a `running` one is doing work, so deleting
+ * either is data loss. Treating "not running" as "completed" was the RUSH-2356
+ * bug — it swept live `pending` `--after` teammates past the 50-record cap.
+ */
+export declare const TERMINAL_STATUSES: ReadonlySet<AgentStatus>;
+/** True when a teammate has reached a terminal (completed/failed/stopped) status. */
+export declare function isTerminalStatus(status: AgentStatus): boolean;
+/**
+ * One remote teammate's liveness, resolved by a single host probe. Three states,
+ * kept distinct on purpose (RUSH-2366):
+ *   - alive=true                                → process still running.
+ *   - exitFilePresent=true                      → the `.exit` sentinel exists;
+ *     `exit` is its (possibly empty, mid-write) contents.
+ *   - alive=false && !exitFilePresent  ("GONE") → the process is gone AND the
+ *     wrapper never recorded a sentinel — it was killed / the box died. There is
+ *     no exit code coming, so this MUST resolve terminal instead of "running
+ *     forever". Collapsing GONE into the empty-`.exit` case is exactly the bug
+ *     that left a dead `--device` teammate RUNNING indefinitely.
+ */
+export interface RemoteLivenessSnapshot {
+    alive: boolean;
+    exit: string | null;
+    exitFilePresent: boolean;
+}
+/**
+ * The per-teammate shell that emits `<id> <ALIVE|EXITED|GONE> <codeOrEmpty>`.
+ * Shared by the batched prefetch (many teammates, one round-trip) and the
+ * direct single-teammate probe, so both classify liveness identically.
+ * `exitFile` is interpolated UNQUOTED so `$HOME` in the dispatch path expands on
+ * the remote shell (shellQuote would defeat the `[ -f ]` test).
+ */
+export declare function remoteLivenessSnippet(id: string, exitFile: string, pid: number): string;
+/** Parse one `<STATE> <codeOrEmpty>` reading into a snapshot. */
+export declare function parseRemoteLivenessState(state: string, code: string | undefined): RemoteLivenessSnapshot;
 /** Task type label for Software Factory workflows. Drives planner fan-out. Optional — teammates without a task_type work exactly as before. */
 export type TaskType = 'plan' | 'implement' | 'test' | 'review' | 'bugfix' | 'docs';
 export declare const VALID_TASK_TYPES: readonly TaskType[];
@@ -162,10 +201,7 @@ export declare class AgentProcess {
     remoteLog: string | null;
     remoteExit: string | null;
     remoteLogOffset: number;
-    remotePollSnapshot: {
-        alive: boolean;
-        exit: string | null;
-    } | null;
+    remotePollSnapshot: RemoteLivenessSnapshot | null;
     private eventsCache;
     private lastReadPos;
     private baseDir;
@@ -231,6 +267,13 @@ export declare class AgentProcess {
      * --active --local` take ~4.3s on a box with 30 completed teammates.
      */
     private syncRemoteMirror;
+    /**
+     * One-shot direct liveness probe for a single remote teammate — the fallback
+     * used outside a batched supervisor wave (a bare `teams status`, `mgr.get()`
+     * for `teams resume`). Returns null on a transient ssh failure so the caller
+     * leaves the teammate RUNNING rather than reaping it on a dropped connection.
+     */
+    private probeRemoteLiveness;
     /** Reset the local stdout cursor for a newly truncated resume log. */
     resetLogReadPosition(): number;
     /** Restore the cursor when a resume transaction puts the prior log back. */
@@ -263,6 +306,24 @@ export declare class AgentProcess {
     saveMeta(): Promise<void>;
     static loadFromDisk(agentId: string, baseDir?: string | null): Promise<AgentProcess | null>;
     isProcessAlive(): boolean;
+    /**
+     * Read just the persisted status + completion time from meta.json, without
+     * reconstructing the whole teammate. Returns null when there is no readable
+     * record on disk. Used to detect that ANOTHER process (a `teams stop`, a
+     * sibling supervisor) has already moved this teammate to a terminal status.
+     */
+    private readDiskStatus;
+    /**
+     * If this in-memory teammate is still non-terminal but disk already shows a
+     * terminal status, adopt the disk state. Returns true when it did.
+     *
+     * This is the guard against the stale-manager race (RUSH-2366): a long-lived
+     * supervisor holding a teammate as `running` must never re-persist that stale
+     * `running` over a `stopped`/`failed`/`completed` another process just wrote
+     * (e.g. an explicit `teams stop` in a separate CLI invocation). A terminal
+     * status is a one-way latch, so disk-terminal always wins over memory-running.
+     */
+    private adoptDiskTerminalIfNewer;
     /**
      * @param opts.skipRemote A `--local` caller (RUSH-2118): a distributed
      *   teammate is never dialed — its in-memory state (already loaded from
@@ -333,6 +394,13 @@ export declare class AgentManager {
      */
     private localOnly;
     private constructorAgentsDir;
+    /**
+     * One-shot memo of the last `validateAddPreconditions` result, so the
+     * command-layer pre-worktree call and spawn()'s own call don't each pay a
+     * full `listAll()` status refresh (a round of SSH probes on a `--device`
+     * team). Consumed by the first matching call — see that method.
+     */
+    private validatedAdd;
     constructor(maxAgents?: number, agentsDir?: string | null, defaultMode?: Mode | null, filterByCwd?: string | null, cleanupAgeDays?: number, localOnly?: boolean);
     private initialize;
     private doInitialize;
@@ -350,11 +418,66 @@ export declare class AgentManager {
      * manager is alive — the supervisor loop calls this each wave so
      * dynamically-added teammates get picked up.
      *
-     * Does not modify or re-load agents already in the cache; that path is
-     * covered by updateStatusFromProcess() which re-reads stdout.log.
+     * For a teammate ALREADY cached, refreshes it only when disk has latched it
+     * terminal while the cache still holds it non-terminal — the case where
+     * another process (e.g. `agents teams stop` in a separate CLI invocation)
+     * moved it to `stopped`/`failed` and this long-lived manager would otherwise
+     * never see it and re-persist a stale `running` (RUSH-2366). A still-live
+     * cached teammate is left untouched; updateStatusFromProcess() owns that path.
      */
     rescanFromDisk(): Promise<number>;
     private loadExistingAgents;
+    /**
+     * Validate an add's name uniqueness and `--after` dependency graph, without
+     * any side effects. Throws a user-facing error on: a duplicate name, `--after`
+     * without `--name`, an unknown dependency, or a cycle. Returns the cleaned
+     * (whitespace-filtered) `after` list.
+     *
+     * Extracted from spawn() so the command layer can run it BEFORE creating a
+     * worktree — a rejected add must not leave an orphan `agents/<name>` branch
+     * that then breaks the retry with `fatal: a branch ... already exists`
+     * (RUSH-2356). spawn() calls it too, so validation lives in exactly one place.
+     *
+     * The result is cached for exactly ONE subsequent call with the same
+     * arguments, which spawn() then consumes. `listByTask()` → `listAll()`
+     * refreshes every sibling's status, and on a `--device` team that is a full
+     * round of SSH liveness probes — running it twice per `teams add` would
+     * double that cost for no gain, since the second pass reads the same snapshot
+     * and cannot catch anything the first missed. The cache is single-use so any
+     * later spawn (a `teams start --watch` supervisor launching staged teammates)
+     * still validates against fresh state and still rejects a duplicate name.
+     */
+    validateAddPreconditions(taskName: string, name: string | null, after: string[]): Promise<string[]>;
+    /**
+     * Does any LIVE teammate — in any team — already own `worktreeName`?
+     *
+     * A RAW disk scan: no status probing, no cache, no `listAll()`. The caller is
+     * the `teams add` failure path, where the manager's own status refresh can be
+     * the very thing that threw (`cleanupOldAgents()` → `listAll()` →
+     * `updateStatusFromProcess()` runs AFTER the staged record is saved), so a
+     * check that re-entered that machinery would throw again and answer nothing.
+     *
+     * `teams add` asks this before removing a worktree, to tell an ORPHAN from
+     * someone's live checkout (RUSH-2356). Two deliberate scoping choices:
+     *
+     * - **Any team, not just the one being added to.** Worktree names are global
+     *   to the repo but records are per-team, so a same-named worktree owned by
+     *   another team's teammate must also block the removal.
+     * - **Non-terminal records only.** A completed/failed/stopped teammate's
+     *   worktree was already cleaned up at `teams stop`, and its record lingers
+     *   until retention reaps it — counting those would leave a genuine orphan
+     *   branch stranded forever, which is the bug this all exists to fix.
+     * - **Fails CLOSED.** This guards a `git worktree remove --force`, so the two
+     *   errors are not symmetric: a false "claimed" strands an orphan branch that
+     *   a human can delete, while a false "unclaimed" deletes a live agent's
+     *   checkout and its uncommitted work. Only `ENOENT` proves absence — no
+     *   agents dir means no records, and a record with no `meta.json` is not a
+     *   record. Any other failure (EACCES, EIO, half-written or invalid JSON,
+     *   a race with a writer) means we could not READ the records, which is not
+     *   the same as there being none, so it answers `true`. This is deliberate
+     *   asymmetry, not defensive coding: the caller acts destructively on `false`.
+     */
+    isWorktreeClaimed(worktreeName: string): Promise<boolean>;
     spawn(taskName: string, agentType: AgentType, prompt: string, cwd?: string | null, mode?: Mode | null, effort?: EffortLevel, parentSessionId?: string | null, workspaceDir?: string | null, version?: string | null, name?: string | null, after?: string[], model?: string | null, envOverrides?: Record<string, string> | null, taskType?: TaskType | null, cloudProvider?: string | null, cloudSessionId?: string | null, cloudRepo?: string | null, cloudBranch?: string | null, worktreeName?: string | null, worktreePath?: string | null, profileName?: string | null, hostName?: string | null, hostTarget?: string | null, repoPath?: string | null): Promise<AgentProcess>;
     /**
      * Resume a STOPPED teammate (completed / failed / stopped) by re-entering its
@@ -481,6 +604,13 @@ export declare class AgentManager {
     }>;
     listAll(): Promise<AgentProcess[]>;
     listRunning(): Promise<AgentProcess[]>;
+    /**
+     * Teammates that have reached a terminal status (completed/failed/stopped) —
+     * the ONLY records retention may reap. A `pending` teammate has not launched
+     * and a `running` one is working, so neither is "completed"; classifying them
+     * as such let cleanupOldAgents sweep live `pending` `--after` teammates past
+     * the cap (RUSH-2356). Filter on `isTerminalStatus`, never `!== RUNNING`.
+     */
     listCompleted(): Promise<AgentProcess[]>;
     listByTask(taskName: string): Promise<AgentProcess[]>;
     listByParentSession(parentSessionId: string): Promise<AgentProcess[]>;