@phnx-labs/agents-cli 1.22.33 → 1.22.35

package/dist/lib/teams/agents.js

@@ -129,6 +129,46 @@ export var AgentStatus;
     AgentStatus["FAILED"] = "failed";
     AgentStatus["STOPPED"] = "stopped";
 })(AgentStatus || (AgentStatus = {}));
+/**
+ * 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 const TERMINAL_STATUSES = new Set([
+    AgentStatus.COMPLETED,
+    AgentStatus.FAILED,
+    AgentStatus.STOPPED,
+]);
+/** True when a teammate has reached a terminal (completed/failed/stopped) status. */
+export function isTerminalStatus(status) {
+    return TERMINAL_STATUSES.has(status);
+}
+/**
+ * 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 function remoteLivenessSnippet(id, exitFile, pid) {
+    return (`printf '%s ' ${shellQuote(id)}; ` +
+        `if [ -f ${exitFile} ]; then printf 'EXITED '; cat ${exitFile} 2>/dev/null | tr -d '\\n'; printf '\\n'; ` +
+        `elif kill -0 ${pid} 2>/dev/null; then printf 'ALIVE\\n'; ` +
+        `else printf 'GONE\\n'; fi`);
+}
+/** Parse one `<STATE> <codeOrEmpty>` reading into a snapshot. */
+export function parseRemoteLivenessState(state, code) {
+    if (state === 'ALIVE')
+        return { alive: true, exit: null, exitFilePresent: false };
+    if (state === 'EXITED')
+        return { alive: false, exit: code ?? '', exitFilePresent: true };
+    // GONE (or an unrecognised token): process not alive, no sentinel recorded.
+    return { alive: false, exit: null, exitFilePresent: false };
+}
 export const VALID_TASK_TYPES = [
     'plan', 'implement', 'test', 'review', 'bugfix', 'docs',
 ];
@@ -705,36 +745,60 @@ export class AgentProcess {
                 // best-effort mirror — leave the offset unadvanced so we retry next poll
             }
         }
-        // Resolve terminal status from the remote `.exit` sentinel (mirror
-        // reapProcess). Prefer this wave's batched snapshot; else fetch the exit file
-        // directly. The snapshot is left in place (refreshed each wave by prefetch),
-        // so a second poll pass within the same wave reuses it.
-        let exit = null;
-        const snap = this.remotePollSnapshot;
-        if (snap) {
-            exit = snap.exit;
-        }
-        else if (this.remoteExit) {
-            // UNQUOTED so `$HOME` in the dispatch exit path expands on the remote shell.
-            const res = sshExec(this.hostTarget, `cat ${this.remoteExit} 2>/dev/null`, {
-                timeoutMs: 8000,
-                multiplex: true,
-                extraSshArgs: this.hostIdentityFile ? ['-i', this.hostIdentityFile, '-o', 'IdentitiesOnly=yes'] : [],
-            });
-            exit = res.code === 0 && res.stdout.trim() !== '' ? res.stdout.trim() : null;
-        }
+        // Resolve terminal status from the host. Prefer this wave's batched snapshot;
+        // else probe this teammate directly. The snapshot is left in place (refreshed
+        // each wave by prefetch), so a second poll pass within the same wave reuses it.
+        const snap = this.remotePollSnapshot ?? (await this.probeRemoteLiveness());
+        if (!snap)
+            return; // transient ssh failure — leave RUNNING, retry next poll
         // Only latch terminal on a PARSEABLE exit code. A `.exit` that exists but is
         // momentarily empty (created, not yet written) or garbage must NOT force a
         // spurious FAILED — leave the teammate RUNNING and let the next poll resolve
-        // it once the code lands. Matches the direct-cat guard above.
-        if (exit !== null && exit.trim() !== '' && this.status === AgentStatus.RUNNING) {
-            const code = Number.parseInt(exit.trim(), 10);
+        // it once the code lands.
+        if (snap.exit !== null && snap.exit.trim() !== '' && this.status === AgentStatus.RUNNING) {
+            const code = Number.parseInt(snap.exit.trim(), 10);
             if (Number.isFinite(code)) {
                 this.status = code === 0 ? AgentStatus.COMPLETED : AgentStatus.FAILED;
                 if (!this.completedAt)
                     this.completedAt = new Date();
+                return;
             }
         }
+        // No exit code resolved it. If the remote process is GONE with NO sentinel at
+        // all, the wrapper died before recording `$?` (killed, box lost, OOM) — it can
+        // never write a code, so this teammate is FAILED, not "running forever"
+        // (RUSH-2366). This is the remote analog of reapProcess()'s "sentinel absent
+        // -> 1 -> FAILED". An EXITED-but-empty `.exit` (wrapper mid-write) is left
+        // RUNNING above precisely so this branch does not misfire on that race.
+        if (this.status === AgentStatus.RUNNING && !snap.alive && !snap.exitFilePresent) {
+            this.status = AgentStatus.FAILED;
+            if (!this.completedAt)
+                this.completedAt = this.getLatestEventTime() || this.startedAt || new Date();
+        }
+    }
+    /**
+     * 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.
+     */
+    async probeRemoteLiveness() {
+        if (!this.hostTarget || !this.remotePid || !this.remoteExit)
+            return null;
+        const res = sshExec(this.hostTarget, remoteLivenessSnippet(this.agentId, this.remoteExit, this.remotePid), {
+            timeoutMs: 8000,
+            multiplex: true,
+            extraSshArgs: this.hostIdentityFile ? ['-i', this.hostIdentityFile, '-o', 'IdentitiesOnly=yes'] : [],
+        });
+        if (res.code === null)
+            return null; // transient ssh failure — don't reap early
+        const trimmed = res.stdout.trim();
+        if (!trimmed)
+            return null;
+        const [, state, code] = trimmed.split(/\s+/);
+        if (!state)
+            return null;
+        return parseRemoteLivenessState(state, code);
     }
     /** Reset the local stdout cursor for a newly truncated resume log. */
     resetLogReadPosition() {
@@ -1015,12 +1079,64 @@ export class AgentProcess {
         }
         return true;
     }
+    /**
+     * 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.
+     */
+    async readDiskStatus() {
+        let raw;
+        try {
+            raw = await fs.readFile(await this.getMetaPath(), 'utf-8');
+        }
+        catch {
+            return null;
+        }
+        try {
+            const meta = JSON.parse(raw);
+            const validStatuses = Object.values(AgentStatus);
+            const status = validStatuses.includes(meta.status)
+                ? meta.status
+                : AgentStatus.RUNNING;
+            const completedAt = meta.completed_at ? new Date(meta.completed_at) : null;
+            return { status, completedAt };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * 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.
+     */
+    async adoptDiskTerminalIfNewer() {
+        if (isTerminalStatus(this.status))
+            return false;
+        const disk = await this.readDiskStatus();
+        if (!disk || !isTerminalStatus(disk.status))
+            return false;
+        this.status = disk.status;
+        this.completedAt = disk.completedAt ?? this.completedAt ?? new Date();
+        return true;
+    }
     /**
      * @param opts.skipRemote A `--local` caller (RUSH-2118): a distributed
      *   teammate is never dialed — its in-memory state (already loaded from
      *   meta.json) stands as-is, no ssh, no re-save.
      */
     async updateStatusFromProcess(opts = {}) {
+        // Stale-manager guard (RUSH-2366): if disk has already latched this teammate
+        // terminal, adopt that and stop — a poll of a process that no longer exists
+        // must not re-persist `running` over the newer on-disk terminal status.
+        if (await this.adoptDiskTerminalIfNewer())
+            return;
         if (!this.pid) {
             // Distributed (remote-host) teammates have no local PID by design; their
             // lifecycle lives on the host. readNewEvents() mirrors the remote log and
@@ -1030,6 +1146,15 @@ export class AgentProcess {
             if (this.hostName) {
                 if (opts.skipRemote)
                     return;
+                // Staged (--after) distributed teammates also have hostName set but no
+                // PID yet (RUSH-2356 sibling bug): without this guard the `!== RUNNING`
+                // fallback below stamps a completedAt on a teammate that hasn't even
+                // launched, which the age-based reap in loadExistingAgents() would
+                // later delete outright once it aged past cleanupAgeDays. Leave it
+                // alone until startReady() launches it — matches the local-only guard
+                // further below.
+                if (this.status === AgentStatus.PENDING)
+                    return;
                 await this.readNewEvents();
                 if (this.status !== AgentStatus.RUNNING && !this.completedAt) {
                     this.completedAt = this.getLatestEventTime() || this.startedAt || new Date();
@@ -1041,6 +1166,10 @@ export class AgentProcess {
             // Cloud-backed teammates have no local PID by design; their lifecycle
             // is driven by the remote provider instead of a local process.
             if (this.cloudProvider) {
+                // Same staged-teammate guard as the hostName branch above — a staged
+                // cloud teammate is PENDING with no PID until its deps resolve.
+                if (this.status === AgentStatus.PENDING)
+                    return;
                 if (!this.completedAt && this.status !== AgentStatus.RUNNING) {
                     const fallbackCompletion = this.getLatestEventTime() || this.startedAt || new Date();
                     this.completedAt = fallbackCompletion;
@@ -1207,6 +1336,13 @@ export class AgentManager {
      */
     localOnly;
     constructorAgentsDir = null;
+    /**
+     * 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.
+     */
+    validatedAdd = null;
     constructor(maxAgents = 50, agentsDir = null, defaultMode = null, filterByCwd = null, cleanupAgeDays = 7, localOnly = false) {
         this.maxAgents = maxAgents;
         this.constructorAgentsDir = agentsDir;
@@ -1251,8 +1387,12 @@ export 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.
      */
     async rescanFromDisk() {
         await this.initialize();
@@ -1265,12 +1405,23 @@ export class AgentManager {
         const entries = await fs.readdir(this.agentsDir);
         let added = 0;
         for (const entry of entries) {
-            if (this.agents.has(entry))
-                continue;
             const agentDir = path.join(this.agentsDir, entry);
             const stat = await fs.stat(agentDir).catch(() => null);
             if (!stat || !stat.isDirectory())
                 continue;
+            const cached = this.agents.get(entry);
+            if (cached) {
+                // Adopt a disk-terminal status the cache hasn't seen; never overwrite a
+                // cached teammate that is still live with a stale disk read. Terminal is
+                // a one-way latch, so this can only move a teammate forward.
+                if (!isTerminalStatus(cached.status)) {
+                    const fresh = await AgentProcess.loadFromDisk(entry, this.agentsDir);
+                    if (fresh && isTerminalStatus(fresh.status)) {
+                        this.agents.set(entry, fresh);
+                    }
+                }
+                continue;
+            }
             const agent = await AgentProcess.loadFromDisk(entry, this.agentsDir);
             if (!agent)
                 continue;
@@ -1302,7 +1453,13 @@ export class AgentManager {
             const agent = await AgentProcess.loadFromDisk(agentId, this.agentsDir);
             if (!agent)
                 continue;
-            if (agent.completedAt && agent.completedAt < cutoffDate) {
+            // Age-based reap is a SECOND retention mechanism, independent of
+            // cleanupOldAgents()'s cap-based one — and must obey the same invariant
+            // (RUSH-2356): a non-terminal teammate is never a reap candidate,
+            // however old its (possibly spuriously stamped) completedAt is. Belt and
+            // suspenders alongside the PENDING guards above that stop completedAt
+            // from getting set on a staged teammate in the first place.
+            if (agent.completedAt && agent.completedAt < cutoffDate && isTerminalStatus(agent.status)) {
                 try {
                     await fs.rm(agentDir, { recursive: true });
                     cleanedOld++;
@@ -1331,23 +1488,38 @@ export class AgentManager {
         }
         debug(`Loaded ${loadedCount} agents from disk`);
     }
-    async spawn(taskName, agentType, prompt, cwd = null, mode = null, effort = 'medium', parentSessionId = null, workspaceDir = null, version = null, name = null, after = [], model = null, envOverrides = null, taskType = null, cloudProvider = null, cloudSessionId = null, cloudRepo = null, cloudBranch = null, worktreeName = null, worktreePath = null, profileName = null, hostName = null, hostTarget = null, repoPath = null) {
+    /**
+     * 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.
+     */
+    async validateAddPreconditions(taskName, name, after) {
         await this.initialize();
-        const resolvedMode = resolveMode(mode, this.defaultMode);
-        // Lineage (RUSH-2019): when the caller didn't name a parent, inherit the
-        // orchestrator's own session id from its env (exec.ts stamps AGENTS_SESSION_ID
-        // onto every agent process). A team spawned from inside a running agent then
-        // records which session created it, so the spawn chain traces back to a parent
-        // session; a team started outside any agent simply carries none.
-        if (!parentSessionId) {
-            parentSessionId = process.env.AGENTS_SESSION_ID ?? null;
+        const key = JSON.stringify([taskName, name, after]);
+        if (this.validatedAdd?.key === key) {
+            const cached = this.validatedAdd.cleanAfter;
+            this.validatedAdd = null; // single use
+            return cached;
         }
-        // Enforce: teammate names are unique within a team.
         const siblings = await this.listByTask(taskName);
         if (name && siblings.some((a) => a.name === name)) {
             throw new Error(`Team '${taskName}' already has a teammate named '${name}'. Pick another name or leave --name off.`);
         }
-        // --- dependency validation ---
         const cleanAfter = after.filter((s) => s && s.trim());
         if (cleanAfter.length > 0) {
             if (!name) {
@@ -1369,6 +1541,88 @@ export class AgentManager {
                 }
             }
         }
+        this.validatedAdd = { key, cleanAfter };
+        return cleanAfter;
+    }
+    /**
+     * 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`.
+     */
+    async isWorktreeClaimed(worktreeName) {
+        const base = this.agentsDir ?? (await getAgentsDir());
+        let entries;
+        try {
+            entries = await fs.readdir(base);
+        }
+        catch (err) {
+            // ENOENT is the only error that PROVES nothing claims the worktree: there
+            // are no records at all. Every other failure (EACCES, EIO, a transient
+            // races with a writer) means we could not read the records, which is not
+            // the same as there being none — fail closed.
+            if (err?.code === 'ENOENT')
+                return false;
+            return true;
+        }
+        for (const entry of entries) {
+            try {
+                const raw = await fs.readFile(path.join(base, entry, 'meta.json'), 'utf-8');
+                const meta = JSON.parse(raw);
+                if (meta?.worktree_name !== worktreeName)
+                    continue;
+                if (!isTerminalStatus(meta?.status))
+                    return true;
+            }
+            catch (err) {
+                // A record without a meta.json is not a record — skip it. Anything else
+                // (unreadable, half-written, invalid JSON) may be the very record that
+                // claims this worktree, and we cannot tell. Fail closed.
+                if (err?.code === 'ENOENT')
+                    continue;
+                return true;
+            }
+        }
+        return false;
+    }
+    async spawn(taskName, agentType, prompt, cwd = null, mode = null, effort = 'medium', parentSessionId = null, workspaceDir = null, version = null, name = null, after = [], model = null, envOverrides = null, taskType = null, cloudProvider = null, cloudSessionId = null, cloudRepo = null, cloudBranch = null, worktreeName = null, worktreePath = null, profileName = null, hostName = null, hostTarget = null, repoPath = null) {
+        await this.initialize();
+        const resolvedMode = resolveMode(mode, this.defaultMode);
+        // Lineage (RUSH-2019): when the caller didn't name a parent, inherit the
+        // orchestrator's own session id from its env (exec.ts stamps AGENTS_SESSION_ID
+        // onto every agent process). A team spawned from inside a running agent then
+        // records which session created it, so the spawn chain traces back to a parent
+        // session; a team started outside any agent simply carries none.
+        if (!parentSessionId) {
+            parentSessionId = process.env.AGENTS_SESSION_ID ?? null;
+        }
+        // Validate name uniqueness + --after deps. Throws on any violation. The
+        // command layer calls this BEFORE creating a worktree so a rejected add
+        // never leaves an orphan `agents/<name>` branch behind (RUSH-2356).
+        const cleanAfter = await this.validateAddPreconditions(taskName, name, after);
         // Resolve and validate cwd
         let resolvedCwd = null;
         if (cwd !== null) {
@@ -1454,6 +1708,18 @@ export class AgentManager {
                 await this.launchProcess(agent);
         }
         await this.cleanupOldAgents();
+        // Postcondition: the teammate MUST be durably on disk before we report
+        // success. saveMeta() ran above and cleanupOldAgents() can no longer reap a
+        // non-terminal record, but a failed write (full disk, permissions) or any
+        // future retention regression would otherwise let `teams add` print a full
+        // success block for a teammate that does not exist — the RUSH-2356
+        // silent-success class. Assert the outcome, not the exit code.
+        const persisted = await AgentProcess.loadFromDisk(agentId, this.agentsDir);
+        if (!persisted) {
+            this.agents.delete(agentId);
+            throw new Error(`Teammate '${name ?? agentId}' was not durably persisted to disk after add ` +
+                `(no meta.json under ${this.agentsDir}/${agentId}). The add did not take effect.`);
+        }
         return agent;
     }
     /**
@@ -1890,20 +2156,12 @@ export class AgentManager {
             byTarget.set(key, group);
         }
         for (const { target, agents } of byTarget.values()) {
-            // Emit one line per teammate: "<agentId> ALIVE|DEAD <exitOrEmpty>". A single
-            // round-trip over the multiplexed socket, regardless of teammate count.
-            const parts = agents.map((a) => {
-                const id = a.agentId;
-                // remoteExit is a dispatch `$HOME/.agents/.cache/hosts/<hex>.exit` path —
-                // interpolate UNQUOTED so `$HOME` expands (shellQuote would make `[ -f ]`
-                // always miss, so a finished teammate would never resolve terminal).
-                const exitFile = a.remoteExit;
-                // exit code (if the sentinel exists) OR empty, then liveness.
-                return (`printf '%s ' ${shellQuote(id)}; ` +
-                    `if [ -f ${exitFile} ]; then printf 'DEAD '; cat ${exitFile} 2>/dev/null | tr -d '\\n'; printf '\\n'; ` +
-                    `elif kill -0 ${a.remotePid} 2>/dev/null; then printf 'ALIVE\\n'; ` +
-                    `else printf 'DEAD\\n'; fi`);
-            });
+            // Emit one line per teammate: "<agentId> <ALIVE|EXITED|GONE> <codeOrEmpty>".
+            // A single round-trip over the multiplexed socket, regardless of teammate
+            // count. GONE (process gone, no `.exit`) is kept distinct from EXITED so a
+            // teammate killed without recording `$?` resolves terminal instead of
+            // reporting RUNNING forever (RUSH-2366).
+            const parts = agents.map((a) => remoteLivenessSnippet(a.agentId, a.remoteExit, a.remotePid));
             const identityFile = agents[0]?.hostIdentityFile;
             const res = sshExec(target, parts.join('; '), {
                 timeoutMs: 12000,
@@ -1917,13 +2175,10 @@ export class AgentManager {
                 const trimmed = line.trim();
                 if (!trimmed)
                     continue;
-                const [id, state, exit] = trimmed.split(/\s+/);
-                if (!id)
+                const [id, state, code] = trimmed.split(/\s+/);
+                if (!id || !state)
                     continue;
-                snapshots.set(id, {
-                    alive: state === 'ALIVE',
-                    exit: state === 'DEAD' ? (exit ?? '') : null,
-                });
+                snapshots.set(id, parseRemoteLivenessState(state, code));
             }
             for (const a of agents) {
                 const snap = snapshots.get(a.agentId);
@@ -2137,9 +2392,16 @@ export class AgentManager {
         const all = await this.listAll();
         return all.filter(a => a.status === AgentStatus.RUNNING);
     }
+    /**
+     * 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`.
+     */
     async listCompleted() {
         const all = await this.listAll();
-        return all.filter(a => a.status !== AgentStatus.RUNNING);
+        return all.filter(a => isTerminalStatus(a.status));
     }
     async listByTask(taskName) {
         const all = await this.listAll();
@@ -2236,6 +2498,10 @@ export class AgentManager {
         }
     }
     async cleanupOldAgents() {
+        // listCompleted() is terminal-only (isTerminalStatus), so a pending or
+        // running teammate is never a reap candidate — retention can only delete a
+        // record whose process has finished. (RUSH-2356: the old `!== RUNNING`
+        // filter reaped live `pending` `--after` teammates.)
         const completed = await this.listCompleted();
         if (completed.length > this.maxAgents) {
             completed.sort((a, b) => {

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

@@ -34,7 +34,16 @@ export declare function localDefaultBranch(gitRoot: string): Promise<string>;
  * code. Matches `createRemoteWorktree` — local and remote isolation share one
  * base policy.
  *
- * @param repoDir - Directory inside the git repository
+ * Resolves the placement root with {@link getMainRepoRoot}, NOT the local
+ * `getGitRoot`/`--show-toplevel`, on purpose: when `repoDir` (the caller's
+ * ambient cwd) is itself inside another teammate's linked worktree,
+ * `--show-toplevel` returns THAT worktree's own root, so the new worktree
+ * lands nested inside it (observed: `.../worktrees/A/.agents/worktrees/B`,
+ * destroyed along with A's cleanup). `getMainRepoRoot` follows
+ * `--git-common-dir`, which always points at the primary checkout's `.git`
+ * regardless of which worktree the caller is standing in.
+ *
+ * @param repoDir - Directory inside the git repository (main checkout or any linked worktree)
  * @param worktreeName - Name for the worktree (used in path and branch)
  * @returns The absolute path to the created worktree
  */
@@ -42,7 +51,12 @@ export declare function createWorktree(repoDir: string, worktreeName: string): P
 /**
  * Remove a git worktree and optionally its branch.
  *
- * @param repoDir - Directory inside the main git repository (not the worktree)
+ * Resolves via {@link getMainRepoRoot}, same as {@link createWorktree} — a
+ * caller standing inside a DIFFERENT linked worktree (e.g. a `teams stop`
+ * run from within another teammate's checkout) must still target the main
+ * repo's `.agents/worktrees/<name>`, not `--show-toplevel`'s local answer.
+ *
+ * @param repoDir - Directory inside the git repository (main checkout or any linked worktree)
  * @param worktreeName - Name of the worktree to remove
  * @param deleteBranch - Whether to delete the associated branch
  */
@@ -55,3 +69,26 @@ export declare function getWorktreePath(gitRoot: string, worktreeName: string):
  * Get the branch name for a worktree.
  */
 export declare function getWorktreeBranch(worktreeName: string): string;
+/**
+ * Does the CHECKOUT DIRECTORY for this worktree name exist?
+ *
+ * Narrower than {@link worktreeExists}, and the difference is load-bearing:
+ * `teams add` only ever cleans up after a failed create when there is NO
+ * checkout — i.e. when all that can be left is a dangling `agents/<name>`
+ * branch ref. That keeps the cleanup incapable of deleting anybody's files,
+ * including a concurrent add's freshly-created worktree, whatever the
+ * pre-flight probe saw a `git fetch` ago. (RUSH-2356)
+ */
+export declare function worktreeCheckoutExists(repoDir: string, worktreeName: string): Promise<boolean>;
+/**
+ * Does anything already exist under this worktree name — the checkout directory
+ * or its `agents/<name>` branch?
+ *
+ * Answered from git and the filesystem, never from teammate records: it is asked
+ * by `teams add` immediately BEFORE {@link createWorktree}, so that if the create
+ * fails the command can tell "the branch ref I half-created" (safe to remove)
+ * from "something that was already here" (never remove — `teams stop` deliberately
+ * KEEPS a worktree holding uncommitted changes, and its teammate record is
+ * terminal by then, so no record-based check can protect it). (RUSH-2356)
+ */
+export declare function worktreeExists(repoDir: string, worktreeName: string): Promise<boolean>;