@phnx-labs/agents-cli 1.22.35 → 1.22.38

package/dist/lib/teams/agents.js

@@ -33,7 +33,7 @@ import { remoteShellFor } from '../hosts/remote-cmd.js';
 import { resolveRemoteOsSync } from '../hosts/remote-os.js';
 import { pullRemoteLogDelta, REMOTE_MIRROR_MAX_BYTES } from '../hosts/progress.js';
 import { createRemoteWorktree, ensureRemoteRepo } from './remoteWorktree.js';
-import { getTeam } from './registry.js';
+import { getTeam, isTeamDisbanded } from './registry.js';
 import { resolvePlacement, classifyExclusions, NoViableDeviceError } from './scheduler.js';
 import { probePoolSignals } from './placement-probe.js';
 import { readMaxConcurrentCaps } from '../device-config.js';
@@ -321,6 +321,24 @@ function extractTimestamp(raw) {
     }
     return null;
 }
+/**
+ * Atomic JSON write: writes to a unique sibling tmp file then renames over the
+ * target. rename(2) is atomic on POSIX, so a process killed mid-write leaves
+ * either the previous valid meta.json or the new one, never a torn,
+ * unparseable file (RUSH-2429). Mirrors the identical pattern already used by
+ * `teams/registry.ts`'s `atomicWriteJson`.
+ */
+async function atomicWriteJson(p, data) {
+    const tmp = `${p}.tmp.${process.pid}.${randomUUID()}`;
+    await fs.writeFile(tmp, JSON.stringify(data, null, 2));
+    try {
+        await fs.rename(tmp, p);
+    }
+    catch (err) {
+        await fs.unlink(tmp).catch(() => { });
+        throw err;
+    }
+}
 /** Resolve a mode string to a validated Mode, falling back to the given default. */
 export function resolveMode(requestedMode, defaultMode = 'plan') {
     const normalizedDefault = normalizeModeValue(defaultMode);
@@ -526,6 +544,13 @@ export class AgentProcess {
     // Worktree isolation: when non-null, this teammate runs in its own git worktree.
     worktreeName = null;
     worktreePath = null;
+    // The team's `--project`, if it has one. Stored as the NAME, not as resolved
+    // directories: an unpinned teammate on a `--devices` pool is placed at LAUNCH
+    // (maybeSchedulePlacement), so grants resolved at add time would carry this
+    // box's absolute paths onto whatever host the scheduler later picked — and
+    // would already have dropped any directory that exists only there. Resolving
+    // per launch is what makes local and remote placement both correct.
+    project = null;
     // Distributed teams: when hostName is non-null, this teammate runs on another
     // machine over SSH (the "remote-host" backend), not as a local process. These
     // are set post-construction (like startTime/pid) — placement config at add
@@ -930,6 +955,18 @@ export class AgentProcess {
         }
     }
     async saveMeta() {
+        // RUSH-2450: a long-lived supervisor (teams start --watch) holds AgentProcess
+        // objects in memory. After another process disbands the team and deletes
+        // every meta.json, the supervisor's next status refresh would re-write those
+        // files via saveMeta — resurrecting PENDING teammates the operator just
+        // disbanded, and making `teams start` re-launch already-merged work. Refuse
+        // when a disband tombstone is present (set by removeTeam / markTeamDisbanded).
+        // Not gated on "team not in registry" alone: tests and mid-add paths write
+        // meta before/without a registry entry, and those must keep working.
+        if (this.taskName && (await isTeamDisbanded(this.taskName))) {
+            debug(`saveMeta: refusing to re-persist ${this.agentId} — team '${this.taskName}' was disbanded`);
+            return;
+        }
         const agentDir = await this.getAgentDir();
         await fs.mkdir(agentDir, { recursive: true });
         const meta = {
@@ -963,6 +1000,7 @@ export class AgentProcess {
             cloud_branch: this.cloudBranch,
             worktree_name: this.worktreeName,
             worktree_path: this.worktreePath,
+            project: this.project,
             host_name: this.hostName,
             host_target: this.hostTarget,
             host_identity_file: this.hostIdentityFile,
@@ -973,20 +1011,61 @@ export class AgentProcess {
             remote_log_offset: this.remoteLogOffset,
         };
         const metaPath = await this.getMetaPath();
-        await fs.writeFile(metaPath, JSON.stringify(meta, null, 2));
+        await atomicWriteJson(metaPath, meta);
+    }
+    /**
+     * Rename an unreadable meta.json out of the way so it stops silently
+     * masquerading as "no record" (RUSH-2429). Before saveMeta() wrote atomically,
+     * a process killed mid-write left a truncated, unparseable meta.json that
+     * loadFromDisk() returned null for -- indistinguishable from ENOENT -- so
+     * retention (loadExistingAgents/rescanFromDisk) never reaped it and
+     * isWorktreeClaimed() (which reads meta.json directly, not through this
+     * method) failed CLOSED on it forever: it scans every record and answers
+     * "claimed" for every worktree name in every team the first time it cannot
+     * read one. Quarantining removes meta.json so the NEXT read of this record
+     * sees ENOENT (genuinely absent) instead of "unreadable" -- that is what lets
+     * isWorktreeClaimed's fail-closed guard recover once the corrupt record is
+     * gone, without weakening the guard itself for a record that is still
+     * present-but-unreadable at decision time.
+     *
+     * Best-effort: if the rename itself fails (e.g. EACCES on the directory),
+     * the record is left in place and the fail-closed guard keeps protecting
+     * worktree removal -- quarantine only ever ADDS a recovery path.
+     */
+    static async quarantineCorruptMeta(metaPath, cause) {
+        const quarantinePath = `${metaPath}.corrupt`;
+        const reason = cause instanceof Error ? cause.message : String(cause);
+        try {
+            await fs.rename(metaPath, quarantinePath);
+            console.warn(`[teams] quarantined unreadable meta.json (${reason}): ${metaPath} -> ${quarantinePath}`);
+        }
+        catch (renameErr) {
+            console.warn(`[teams] found unreadable meta.json but could not quarantine it (${reason}): ${metaPath}: ` +
+                `${renameErr?.message ?? renameErr}`);
+        }
     }
     static async loadFromDisk(agentId, baseDir = null) {
         const base = baseDir || await getAgentsDir();
         const agentDir = path.join(base, agentId);
         const metaPath = path.join(agentDir, 'meta.json');
+        let metaContent;
         try {
-            await fs.access(metaPath);
+            metaContent = await fs.readFile(metaPath, 'utf-8');
         }
-        catch {
+        catch (err) {
+            // A READ error is not a corrupt record. ENOENT proves the record is
+            // genuinely ABSENT; anything else -- EACCES, EIO, a transient EMFILE
+            // under fd pressure -- means the file exists and could not be read THIS
+            // time, but its contents are intact. We MUST NOT quarantine (rename) it:
+            // renaming a valid record away is exactly the fail-open that RUSH-2429
+            // forbids -- isWorktreeClaimed() reads meta.json directly and fails
+            // CLOSED on the same read error (safe), but a rename here would delete
+            // the record it relies on and turn a live teammate's worktree into
+            // "unclaimed", re-arming `git worktree remove --force` over uncommitted
+            // work. Return null (skip this scan); the file stays for the next read.
             return null;
         }
         try {
-            const metaContent = await fs.readFile(metaPath, 'utf-8');
             const meta = JSON.parse(metaContent);
             // Legacy teammates may have mode='ralph', 'cloud', or 'full' from before
             // modes were narrowed/renamed. Coerce to the closest current mode so they
@@ -1026,9 +1105,15 @@ export class AgentProcess {
             agent.remoteLog = meta.remote_log || null;
             agent.remoteExit = meta.remote_exit || null;
             agent.remoteLogOffset = typeof meta.remote_log_offset === 'number' ? meta.remote_log_offset : 0;
+            // The team's project. Absent on every teammate added before `--project`.
+            agent.project = typeof meta.project === 'string' ? meta.project : null;
             return agent;
         }
-        catch {
+        catch (err) {
+            // The file exists but is not valid JSON (or fails a constructor
+            // invariant) -- most likely a torn write from before saveMeta() became
+            // atomic. Quarantine it; see quarantineCorruptMeta() above.
+            await AgentProcess.quarantineCorruptMeta(metaPath, err);
             return null;
         }
     }
@@ -1262,6 +1347,34 @@ export class AgentProcess {
         }
     }
 }
+/**
+ * The directories, beyond its cwd, a teammate may reach because of the team's
+ * `--project`. Resolved at LAUNCH, from the project name on the record.
+ *
+ * Resolving here rather than at `teams add` is load-bearing for a pooled team:
+ * an unpinned teammate has no host until `maybeSchedulePlacement` runs, so add
+ * time cannot know whether to produce absolute local paths or `~/…` — and the
+ * local form would additionally have dropped any directory that exists only on
+ * the host it later landed on.
+ *
+ * A project that no longer resolves (renamed, definition deleted) yields no
+ * grants rather than failing the launch: the teammate still gets its cwd.
+ */
+async function resolveTeammateGrants(agent, opts) {
+    if (!agent.project)
+        return [];
+    try {
+        const { resolveProjectDirs } = await import('../project-root.js');
+        const { extraDirs } = await resolveProjectDirs(agent.project, opts);
+        return extraDirs;
+    }
+    catch (err) {
+        // Degrading is deliberate, but silently degrading is not: a teammate that
+        // lost its grants to a renamed or deleted definition should leave a trace.
+        debug(`teammate ${agent.agentId}: project '${agent.project}' did not resolve, no grants: ${err.message}`);
+        return [];
+    }
+}
 export async function beginResumeLogTransaction(agent) {
     const stdoutPath = await agent.getStdoutPath();
     const backupPath = `${stdoutPath}.resume-backup-${randomUUID()}`;
@@ -1608,7 +1721,7 @@ export class AgentManager {
         }
         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) {
+    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, project = null) {
         await this.initialize();
         const resolvedMode = resolveMode(mode, this.defaultMode);
         // Lineage (RUSH-2019): when the caller didn't name a parent, inherit the
@@ -1666,6 +1779,10 @@ export class AgentManager {
         agent.hostName = hostName;
         agent.hostTarget = hostTarget;
         agent.repoPath = repoPath;
+        // Must be set BEFORE the launch below — this method launches inline for a
+        // teammate with no unmet --after deps, so assigning it after spawn()
+        // returns would miss the only launch that matters.
+        agent.project = project;
         const agentDir = await agent.getAgentDir();
         try {
             await fs.mkdir(agentDir, { recursive: true });
@@ -1818,7 +1935,7 @@ export class AgentManager {
         // forwarded). Effort is a separate knob wired into buildReasoningFlags
         // inside buildCommand.
         const resolvedModel = agent.model ?? null;
-        const cmd = this.buildCommand(agent.agentType, agent.prompt, agent.mode, resolvedModel, agent.cwd, agent.agentId, effort, agent.version, agent.profileName, resume);
+        const cmd = this.buildCommand(agent.agentType, agent.prompt, agent.mode, resolvedModel, agent.cwd, agent.agentId, effort, agent.version, agent.profileName, resume, await resolveTeammateGrants(agent, { forRemote: false }));
         debug(`Launching ${agent.agentType} agent ${agent.agentId} [${agent.mode}]${resume ? ' (resume)' : ''}: ${cmd.slice(0, 3).join(' ')}...`);
         let childProcess = null;
         let stdoutFile = null;
@@ -1954,6 +2071,15 @@ export class AgentManager {
         // — the supervisor polls the host, we don't block here.
         const effort = agent.effort ?? 'medium';
         const forwardedArgs = this.buildRunArgv(agent.agentType, agent.prompt, agent.mode, agent.model ?? null, effort, agent.version, agent.profileName, resume);
+        // Project grants for a remote teammate, resolved HERE rather than at add
+        // time: an unpinned teammate only learns its host from the scheduler, which
+        // runs at launch. `forRemote: true` keeps them `~/…` and skips this box's
+        // existence check — the host has its own checkouts. The remote `agents run`
+        // expands `~` against the host's HOME before handing it to the harness.
+        for (const dir of await resolveTeammateGrants(agent, { forRemote: true })) {
+            if (dir !== remoteCwd)
+                forwardedArgs.push('--add-dir', dir);
+        }
         let dispatchedTask = null;
         let resumeLog = null;
         try {
@@ -2305,7 +2431,7 @@ export class AgentManager {
         args.push('--env', 'AGENTS_RUNTIME=teams');
         return args;
     }
-    buildCommand(agentType, prompt, mode, model, cwd = null, sessionId = null, effort = 'medium', version = null, profileName = null, resume) {
+    buildCommand(agentType, prompt, mode, model, cwd = null, sessionId = null, effort = 'medium', version = null, profileName = null, resume, addDirs = []) {
         // Route through getAgentsInvocation so a teammate launched by the compiled
         // standalone binary (#315) doesn't relaunch as `agents /$bunfs/root/agents …`
         // (process.argv[1] is the bun virtual entry there) → "unknown command".
@@ -2326,6 +2452,14 @@ export class AgentManager {
         if (agentType === 'claude' && cwd) {
             cmd.push('--add-dir', cwd);
         }
+        // The team's project directories, beyond the one the teammate sits in.
+        // `agents run` re-dedupes, but skipping cwd here keeps the launch line
+        // readable. Codex folds these into its workspace_roots; other harnesses
+        // ignore --add-dir entirely.
+        for (const dir of new Set(addDirs)) {
+            if (dir !== cwd)
+                cmd.push('--add-dir', dir);
+        }
         // Codex's workspace-write sandbox blocks writes outside cwd. Factory
         // teammates need to run further `agents teams add` commands, which
         // write to ~/.agents/. Grant that root so subprocess-issued
@@ -2407,6 +2541,50 @@ export class AgentManager {
         const all = await this.listAll();
         return all.filter(a => a.taskName === taskName);
     }
+    /**
+     * Terminal removal of every teammate record for a team (RUSH-2450).
+     *
+     * `teams disband` used to delete log dirs and the registry entry, but left
+     * the in-memory AgentProcess cache intact. A concurrent `teams start --watch`
+     * supervisor then re-persisted those records via saveMeta, so a second
+     * disband still found N logs to clear and `teams start` could re-launch
+     * PENDING work that had already merged.
+     *
+     * This drops every matching record from the manager map AND removes its
+     * durable state. With `keepLogs`, only `meta.json` is removed so the
+     * teammate is no longer discoverable/startable while stdout/stderr logs
+     * remain for postmortem.
+     *
+     * Returns the agent_ids that were purged.
+     */
+    async purgeByTask(taskName, opts) {
+        await this.initialize();
+        const roster = await this.listByTask(taskName);
+        const purged = [];
+        const base = this.agentsDir || (await getAgentsDir());
+        for (const agent of roster) {
+            this.agents.delete(agent.agentId);
+            const agentDir = path.join(base, agent.agentId);
+            try {
+                if (opts?.keepLogs) {
+                    // Keep log files; remove only the record that makes the teammate
+                    // reappear in list/status/start.
+                    await fs.rm(path.join(agentDir, 'meta.json'), { force: true });
+                }
+                else {
+                    await fs.rm(agentDir, { recursive: true, force: true });
+                }
+                purged.push(agent.agentId);
+            }
+            catch (err) {
+                debug(`purgeByTask: failed to remove ${agent.agentId}: ${err}`);
+                // Still count as purged from the roster — the in-memory drop above is
+                // the load-bearing half against same-process resurrection.
+                purged.push(agent.agentId);
+            }
+        }
+        return purged;
+    }
     async listByParentSession(parentSessionId) {
         const all = await this.listAll();
         return all.filter(a => a.parentSessionId === parentSessionId);

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

@@ -46,6 +46,12 @@ export interface AgentStatusDetail {
     cloud_session_id?: string | null;
     cloud_provider?: string | null;
     pr_url?: string | null;
+    /**
+     * Delivery postcondition (RUSH-2380), distinct from process `status`.
+     * `pr_open` when the process completed but left an unmerged PR — orchestrators
+     * must not treat that as "work landed on main".
+     */
+    delivery?: string;
     version?: string | null;
     remote_session_id?: string | null;
     session_label?: string | null;
@@ -84,6 +90,8 @@ export interface AgentStatusSummary {
     name: string | null;
     agent_type: string;
     status: string;
+    /** Delivery postcondition — see {@link AgentStatusDetail.delivery}. */
+    delivery?: string;
     duration: string | null;
     tool_count: number;
     has_errors: boolean;
@@ -162,7 +170,9 @@ export interface TasksResult {
     tasks: TaskInfo[];
 }
 /** Spawn a new teammate in a task and return its initial metadata. */
-export declare function handleSpawn(manager: AgentManager, taskName: string, agentType: AgentType, prompt: string, cwd: string | null, mode: string | null, effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto' | null, 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<SpawnResult>;
+export declare function handleSpawn(manager: AgentManager, taskName: string, agentType: AgentType, prompt: string, cwd: string | null, mode: string | null, effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto' | null, 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, 
+/** The team's `--project`; grants resolve from it at launch. */
+project?: string | null): Promise<SpawnResult>;
 /** Retrieve the current status of all teammates in a task, with optional timestamp-based delta filtering. */
 export declare function handleStatus(manager: AgentManager, taskName: string | null | undefined, filter?: string, since?: string, // Optional ISO timestamp - return only events after this time
 parentSessionId?: string | null): Promise<TaskStatusResult>;

package/dist/lib/teams/api.js

@@ -2,6 +2,7 @@ import { AgentStatus, resolveMode } from './agents.js';
 import { getDelta } from './summarizer.js';
 import { debug } from './debug.js';
 import { buildClaudeLabelMap } from '../session/discover.js';
+import { resolveTeammateDelivery } from './delivery.js';
 /**
  * Truncate a bash command for status output.
  * Handles heredocs specially - shows the redirect target instead of contents.
@@ -107,6 +108,8 @@ export function toAgentStatusSummary(detail) {
         name: detail.name ?? null,
         agent_type: detail.agent_type,
         status: detail.status,
+        delivery: detail.delivery ??
+            resolveTeammateDelivery({ status: detail.status, prUrl: detail.pr_url }),
         duration: detail.duration,
         tool_count: detail.tool_count,
         has_errors: detail.has_errors,
@@ -135,7 +138,9 @@ export function toTaskStatusSummary(result) {
     };
 }
 /** Spawn a new teammate in a task and return its initial metadata. */
-export async function handleSpawn(manager, taskName, agentType, prompt, cwd, mode, 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) {
+export async function handleSpawn(manager, taskName, agentType, prompt, cwd, mode, 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, 
+/** The team's `--project`; grants resolve from it at launch. */
+project = null) {
     const defaultMode = manager.getDefaultMode();
     const resolvedMode = resolveMode(mode, defaultMode);
     const resolvedEffort = effort ?? 'medium';
@@ -160,7 +165,7 @@ export async function handleSpawn(manager, taskName, agentType, prompt, cwd, mod
             throw new Error(`[budget] BLOCKED teammate "${taskName}" (${agentType}): ${gate.decision.reason}`);
         }
     }
-    const agent = await manager.spawn(taskName, agentType, prompt, cwd, resolvedMode, resolvedEffort, parentSessionId, workspaceDir, version, name, after, model, envOverrides, taskType, cloudProvider, cloudSessionId, cloudRepo, cloudBranch, worktreeName, worktreePath, profileName, hostName, hostTarget, repoPath);
+    const agent = await manager.spawn(taskName, agentType, prompt, cwd, resolvedMode, resolvedEffort, parentSessionId, workspaceDir, version, name, after, model, envOverrides, taskType, cloudProvider, cloudSessionId, cloudRepo, cloudBranch, worktreeName, worktreePath, profileName, hostName, hostTarget, repoPath, project);
     debug(`[spawn] Spawned ${agentType} agent ${agent.agentId} for task "${taskName}"`);
     return {
         task_name: taskName,
@@ -252,6 +257,10 @@ parentSessionId) {
             cloud_session_id: agent.cloudSessionId,
             cloud_provider: agent.cloudProvider,
             pr_url: agent.prUrl,
+            delivery: resolveTeammateDelivery({
+                status: agent.status,
+                prUrl: agent.prUrl,
+            }),
             files_created: delta.new_files_created,
             files_modified: delta.new_files_modified,
             files_read: delta.new_files_read,

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

@@ -0,0 +1,41 @@
+/**
+ * Teammate *delivery* vs process *lifecycle* (RUSH-2380).
+ *
+ * `AgentStatus.COMPLETED` means the process exited 0 — not that the PR merged.
+ * Orchestrators that treat COMPLETED as "work landed on main" compose on top of
+ * unmerged PRs. This module derives a delivery signal from process status +
+ * whether a PR URL is still open, so `teams status` can surface `PR OPEN`
+ * instead of bare COMPLETED.
+ *
+ * Process status still drives the DAG (`--after` deps): a finished process
+ * unblocks dependents. Delivery is the postcondition for "done end-to-end".
+ */
+import { AgentStatus } from './agents.js';
+/** Postcondition-facing delivery of a teammate's work. */
+export type TeammateDelivery = 'pending' | 'in_progress' | 'pr_open' | 'pr_merged' | 'no_pr' | 'failed' | 'stopped';
+/**
+ * Derive delivery from process status and PR state.
+ *
+ * When the process completed with a `prUrl` and merge is unknown or false,
+ * delivery is `pr_open` — pessimistic: assume open until proven merged so an
+ * orchestrator never mistakes "agent stopped" for "work on main".
+ */
+export declare function resolveTeammateDelivery(opts: {
+    status: AgentStatus | string;
+    prUrl?: string | null;
+    /**
+     * When known from a probe or meta: true = merged, false = still open.
+     * `null`/`undefined` = unknown; with a `prUrl` that means `pr_open`.
+     */
+    prMerged?: boolean | null;
+}): TeammateDelivery;
+/**
+ * Human label for `teams status` rows. Replaces bare COMPLETED with PR OPEN
+ * when delivery is still pending merge.
+ */
+export declare function deliveryDisplayLabel(delivery: TeammateDelivery, processStatus: AgentStatus | string): string;
+/**
+ * Color key for statusColor-style switches. `pr_open` is its own key so the
+ * row is visually distinct from green COMPLETED.
+ */
+export declare function deliveryColorKey(delivery: TeammateDelivery, processStatus: string): string;

package/dist/lib/teams/delivery.js

@@ -0,0 +1,60 @@
+/**
+ * Teammate *delivery* vs process *lifecycle* (RUSH-2380).
+ *
+ * `AgentStatus.COMPLETED` means the process exited 0 — not that the PR merged.
+ * Orchestrators that treat COMPLETED as "work landed on main" compose on top of
+ * unmerged PRs. This module derives a delivery signal from process status +
+ * whether a PR URL is still open, so `teams status` can surface `PR OPEN`
+ * instead of bare COMPLETED.
+ *
+ * Process status still drives the DAG (`--after` deps): a finished process
+ * unblocks dependents. Delivery is the postcondition for "done end-to-end".
+ */
+import { AgentStatus } from './agents.js';
+/**
+ * Derive delivery from process status and PR state.
+ *
+ * When the process completed with a `prUrl` and merge is unknown or false,
+ * delivery is `pr_open` — pessimistic: assume open until proven merged so an
+ * orchestrator never mistakes "agent stopped" for "work on main".
+ */
+export function resolveTeammateDelivery(opts) {
+    const status = String(opts.status);
+    if (status === AgentStatus.PENDING || status === 'pending')
+        return 'pending';
+    if (status === AgentStatus.RUNNING || status === 'running')
+        return 'in_progress';
+    if (status === AgentStatus.FAILED || status === 'failed')
+        return 'failed';
+    if (status === AgentStatus.STOPPED || status === 'stopped')
+        return 'stopped';
+    if (status === AgentStatus.COMPLETED || status === 'completed') {
+        const prUrl = opts.prUrl?.trim();
+        if (!prUrl)
+            return 'no_pr';
+        if (opts.prMerged === true)
+            return 'pr_merged';
+        return 'pr_open';
+    }
+    return 'in_progress';
+}
+/**
+ * Human label for `teams status` rows. Replaces bare COMPLETED with PR OPEN
+ * when delivery is still pending merge.
+ */
+export function deliveryDisplayLabel(delivery, processStatus) {
+    if (delivery === 'pr_open')
+        return 'PR OPEN';
+    if (delivery === 'pr_merged')
+        return 'COMPLETED';
+    return String(processStatus).toUpperCase();
+}
+/**
+ * Color key for statusColor-style switches. `pr_open` is its own key so the
+ * row is visually distinct from green COMPLETED.
+ */
+export function deliveryColorKey(delivery, processStatus) {
+    if (delivery === 'pr_open')
+        return 'pr_open';
+    return String(processStatus);
+}

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

@@ -18,6 +18,12 @@ export interface TeamMeta {
      * `origin` at create time. Used by `ensureRemoteRepo` to provision the repo.
      */
     repo?: string;
+    /**
+     * The project (`agents projects`) this team works on. Its primary directory
+     * is a local teammate's base cwd when neither `--cwd` nor a worktree gives
+     * one, and its other bound directories become `--add-dir` grants.
+     */
+    project?: string;
 }
 /** Map of team name to team metadata. */
 export type TeamRegistry = Record<string, TeamMeta>;
@@ -37,11 +43,19 @@ export interface CreateTeamOptions {
     devices?: string[];
     /** How each device gets the code (git URL to clone, or a path on the host). */
     repo?: string;
+    /** The `agents projects` project this team works on. */
+    project?: string;
 }
 /** Create a new team. Throws if a team with the same name already exists. */
 export declare function createTeam(name: string, options?: CreateTeamOptions): Promise<TeamMeta>;
 /** Return existing team metadata or create a new team if it does not exist. */
 export declare function ensureTeam(name: string): Promise<TeamMeta>;
+/** Mark a team as disbanded so saveMeta will not resurrect its teammates. */
+export declare function markTeamDisbanded(name: string): Promise<void>;
+/** Clear a disband tombstone — called when the name is re-created. */
+export declare function clearTeamDisbanded(name: string): Promise<void>;
+/** True when the team was disbanded and has not been re-created since. */
+export declare function isTeamDisbanded(name: string): Promise<boolean>;
 /** Remove a team from the registry. Returns false if the team did not exist. */
 export declare function removeTeam(name: string): Promise<boolean>;
 /** Check whether a team with the given name exists in the registry. */

package/dist/lib/teams/registry.js

@@ -111,11 +111,15 @@ export async function createTeam(name, options) {
             ...(options?.useWorktree ? { use_worktree: options.useWorktree } : {}),
             ...(options?.devices && options.devices.length ? { devices: options.devices } : {}),
             ...(options?.repo ? { repo: options.repo } : {}),
+            ...(options?.project ? { project: options.project } : {}),
         };
         reg[name] = m;
         await saveTeams(reg);
         return m;
     });
+    // A re-created name is a fresh team — drop any prior disband tombstone so
+    // saveMeta will persist new teammates again (RUSH-2450).
+    await clearTeamDisbanded(name);
     // Audit the lifecycle boundary, not the CLI shell — captures every creation
     // path (create + ensure) with team metadata the generic command log lacks.
     emit('teams.create', { module: 'teams', team: name, worktrees: Boolean(options?.enableWorktrees || options?.useWorktree) });
@@ -137,10 +141,52 @@ export async function ensureTeam(name) {
     });
     // `teams add` auto-creates the team on first teammate — audit that creation
     // too, but only when it actually happened (not the get-existing path).
-    if (created)
+    if (created) {
+        await clearTeamDisbanded(name);
         emit('teams.create', { module: 'teams', team: name, worktrees: false });
+    }
     return meta;
 }
+/**
+ * Tombstone dir for disbanded teams (RUSH-2450). Lives next to the registry so
+ * a long-lived supervisor can see that a team was deliberately removed and
+ * refuse to re-persist its in-memory AgentProcess objects via saveMeta.
+ * Cleared on create/ensure so a re-used name is a fresh team.
+ */
+function disbandedDir() {
+    return path.join(path.dirname(getTeamsRegistryPath()), 'disbanded');
+}
+function disbandedPath(name) {
+    // Encode the name so a team called `../x` cannot escape the dir.
+    const safe = Buffer.from(name, 'utf8').toString('base64url');
+    return path.join(disbandedDir(), `${safe}.json`);
+}
+/** Mark a team as disbanded so saveMeta will not resurrect its teammates. */
+export async function markTeamDisbanded(name) {
+    const dir = disbandedDir();
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(disbandedPath(name), JSON.stringify({ team: name, disbanded_at: new Date().toISOString() }), 'utf-8');
+}
+/** Clear a disband tombstone — called when the name is re-created. */
+export async function clearTeamDisbanded(name) {
+    try {
+        await fs.unlink(disbandedPath(name));
+    }
+    catch (err) {
+        if (err?.code !== 'ENOENT')
+            throw err;
+    }
+}
+/** True when the team was disbanded and has not been re-created since. */
+export async function isTeamDisbanded(name) {
+    try {
+        await fs.access(disbandedPath(name));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /** Remove a team from the registry. Returns false if the team did not exist. */
 export async function removeTeam(name) {
     const p = await registryPath();
@@ -152,6 +198,10 @@ export async function removeTeam(name) {
         await saveTeams(reg);
         return true;
     });
+    // Always stamp the tombstone when removeTeam is invoked from disband — even
+    // if the registry entry was already gone, so a concurrent supervisor still
+    // sees the disband. Idempotent.
+    await markTeamDisbanded(name);
     // "Disband" — only fires when a real team was removed, not a no-op.
     if (existed)
         emit('teams.disband', { module: 'teams', team: name });

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

@@ -34,6 +34,25 @@ export declare function remoteDefaultBranch(target: string, repoPath: string, op
  * teammate off old code.
  */
 export declare function createRemoteWorktree(target: string, repoPath: string, worktreeName: string, opts?: RemoteSshOptions): string;
+/**
+ * How many commits the host checkout at `repoPath` is behind `origin/<default>` —
+ * the remote analog of the local {@link commitsBehindDefault} staleness probe, and
+ * the exact case from the incident this guard exists for (a distributed team
+ * pointed at a 71-commit-stale checkout on another box).
+ *
+ * `ensureRemoteRepo` already fetched `origin` when it provisioned/reused the
+ * checkout right before this runs, so the remote-tracking ref is usually fresh and
+ * this reads it WITHOUT a second fetch: resolve the default branch, then
+ * `rev-list --count HEAD..origin/<default>`. (That reuse fetch is best-effort —
+ * an offline host leaves the ref stale, so this under-reports rather than blocks;
+ * `createRemoteWorktree` re-fetches at launch so the teammate's base is still
+ * fresh regardless.) Returns null on any git/ssh error (unreachable host, non-repo
+ * path) — the caller treats null as "can't tell, don't block".
+ */
+export declare function remoteCommitsBehindDefault(target: string, repoPath: string, opts?: RemoteSshOptions): {
+    behind: number;
+    base: string;
+} | null;
 /**
  * Ensure the team's repo is present on the host and return its absolute git
  * root. The canonical location is `~/.agents/repos/<slug>` (slug = sanitized