@phnx-labs/agents-cli 1.22.59 → 1.22.60

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 1.22.60
+
+- **Detect stranded uncommitted work in `agents teams status` (PHNX-2951).** A teammate that exits `COMPLETED` with no PR and uncommitted changes in its local worktree now reports `STRANDED` instead of `done`, and the status line names the worktree path so the work can be rescued before cleanup. The stranded count is computed over the full team even when `--filter` narrows the displayed agents, so `agents teams status <team> --filter running` still surfaces stranded completed teammates. Team rollups and `teams list --status` classify these teams as `stranded`, not `done`. Source: `cli/src/lib/teams/delivery.ts`, `cli/src/lib/teams/api.ts`, `cli/src/commands/teams.ts`.
+
+- **Track agent-launch boot cost: persist + surface the `startup` phase (PHNX-3468).** `agent.run` already timed a `startup` phase (entering `spawnAgent` → child spawn) but only the total run duration reached the perf warehouse, so boot cost was untrackable across the fleet. The timer now persists its sub-phase marks into each `perf.timing` sample's `meta_json`, `aggregateSamples` folds them into a per-label `phases` break-out (p50/p90 over the samples that carried each phase), and `agents insights perf run` renders a `└ startup: p50 …  p90 …  (n=…)` sub-line under `agent.run`. This is the measurement the boot-perf work is graded against. Source: `cli/src/lib/feed/events.ts`, `cli/src/lib/perf/db.ts`, `cli/src/lib/perf/types.ts`, `cli/src/commands/perf.ts`.
+
+- **`agents sessions preview <id>` now pulls the transcript digest from the
+  owning device for host-dispatched sessions (PHNX-3481).** A host dispatch
+  leaves a synthetic local index row with `machine = <peer>` and an empty
+  `filePath`, but that row does not carry the live fan-out's `_remote` marker.
+  Full-UUID preview resolved the local row and then treated it as a local live
+  session, rendering "full transcript not indexed here" without making any SSH
+  hop. Transcript reads now follow one file-aware predicate: an explicit remote
+  row still reads on its peer; a row naming another machine also reads there
+  when no transcript exists on this disk; and a synced mirror with a real local
+  file still renders locally. The direct preview, `sessions <id>`, picker view,
+  and picker/browser digest pane all share that rule. Live-registry metadata now
+  also stamps `_remote` when its execution machine differs from this box, and an
+  unreachable owner remains a loud error instead of a local placeholder.
+  Source: `cli/src/commands/sessions-picker.ts`, `cli/src/commands/sessions.ts`,
+  `cli/src/lib/session/live-metadata.ts`.
+
 ## 1.22.59
 
 - **`agents devices disable/prefer` now actually change `--device auto` placement (PHNX-2092).**

package/dist/commands/perf.js

@@ -132,6 +132,16 @@ function renderLabelTable(title, rows, warnMs, limit) {
         formatMs(r.maxMs),
         formatRateColumn(r),
     ]), sliced.map((r) => r.p99Ms > warnMs));
+    // Sub-phase break-out (agent.run's `startup` = spawn overhead before the child
+    // runs, PHNX-3468). Indented under the row so a slow boot is visible next to
+    // the total without adding columns that are empty for phaseless labels.
+    for (const r of sliced) {
+        if (!r.phases)
+            continue;
+        for (const [name, ph] of Object.entries(r.phases)) {
+            console.log(chalk.gray(`  └ ${name}: p50 ${formatMs(ph.p50Ms)}  p90 ${formatMs(ph.p90Ms)}  (n=${ph.n})`));
+        }
+    }
 }
 /**
  * Prefer SQLite samples; fall back to the legacy daily JSONL so existing

package/dist/commands/sessions-picker.d.ts

@@ -3,6 +3,19 @@ import { fetchPeerPreviewDigest } from '../lib/session/remote-list.js';
 import { classifyFileChanges, changeCounts, toolHistogram, detectTestResult } from '../lib/session/digest.js';
 import type { FileChange } from '../lib/session/digest.js';
 import { extractArtifacts, extractHooks, extractLinks, extractSkills } from '../lib/session/highlights.js';
+/** A session whose transcript FILE is on another machine: its `filePath` is on
+ * that peer's disk, so the preview can't parse it locally — it fetches the
+ * peer's digest over SSH and shows metadata + a "resume there" note until that
+ * lands. `_remote` is an explicit signal; a peer `machine` plus no readable
+ * local file covers host-dispatch index rows and live-registry rows that were
+ * synthesized outside the fan-out. A locally-readable synced mirror stays
+ * local even when its recorded owner is another machine.
+ *
+ * This is the READ rule and only the read rule. Whether a session may be
+ * RESUMED here is a different question with a different answer — a mirror is
+ * readable but not resumable — and `sessionOwnerDevice`
+ * (lib/session/resume-owner.ts) is the single place that answers it (RUSH-2022). */
+export declare function transcriptOnPeerOf(session: SessionMeta): string | undefined;
 /**
  * Compact checklist tally for list rows and previews (RUSH-2045).
  * Example: `✓6/8 · A5 wiring runner`. Empty string when there is no list.

package/dist/commands/sessions-picker.js

@@ -25,19 +25,28 @@ import { createMemoryCache } from '../lib/memory-cache.js';
 import { classifyFileChanges, changeCounts, toolHistogram, detectTestResult } from '../lib/session/digest.js';
 import { extractArtifacts, extractHooks, extractLinks, extractRepos, extractSkills, harnessTracksBackgroundShells, isBackgroundShellStart, isSubAgentTool, } from '../lib/session/highlights.js';
 import { getSessionPlugins, readSessionPreviewCache, writeSessionPreviewCache, readSessionContent, readArchivedSessionPreview } from '../lib/session/db.js';
-/** A session whose transcript FILE is on another machine (folded in over the
- * live cross-machine fan-out): its `filePath` is on that peer's disk, so the
- * preview can't parse it locally — it fetches the peer's digest over SSH and
- * shows metadata + a "resume there" note until that lands. Keys off `_remote`,
- * not the machine tag, so locally-readable synced mirrors still parse their
- * file normally.
+import { machineId } from '../lib/session/sync/config.js';
+/** A session whose transcript FILE is on another machine: its `filePath` is on
+ * that peer's disk, so the preview can't parse it locally — it fetches the
+ * peer's digest over SSH and shows metadata + a "resume there" note until that
+ * lands. `_remote` is an explicit signal; a peer `machine` plus no readable
+ * local file covers host-dispatch index rows and live-registry rows that were
+ * synthesized outside the fan-out. A locally-readable synced mirror stays
+ * local even when its recorded owner is another machine.
  *
  * This is the READ rule and only the read rule. Whether a session may be
  * RESUMED here is a different question with a different answer — a mirror is
  * readable but not resumable — and `sessionOwnerDevice`
  * (lib/session/resume-owner.ts) is the single place that answers it (RUSH-2022). */
-function transcriptOnPeerOf(session) {
-    return session._remote ? session.machine : undefined;
+export function transcriptOnPeerOf(session) {
+    if (session._remote)
+        return session.machine;
+    if (session.machine
+        && session.machine !== machineId()
+        && (!session.filePath || !fs.existsSync(session.filePath))) {
+        return session.machine;
+    }
+    return undefined;
 }
 /**
  * Compact checklist tally for list rows and previews (RUSH-2045).

package/dist/commands/sessions.js

@@ -55,7 +55,7 @@ import { listInstalledVersions, resolveVersionAliasLoose } from '../lib/installa
 import { getAgentsInvocation } from '../lib/daemon/daemon.js';
 import { sessionRecoveryRunArgs } from '../lib/session/recovery.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
-import { sessionPicker, buildPreview, loadSessionPreviewDigest, formatTodoCompact, githubRepoUrlFromCwd, } from './sessions-picker.js';
+import { sessionPicker, buildPreview, loadSessionPreviewDigest, transcriptOnPeerOf, formatTodoCompact, githubRepoUrlFromCwd, } from './sessions-picker.js';
 import { setHelpSections } from '../lib/help.js';
 import { registerSessionsTailCommand } from './sessions-tail.js';
 import { registerSessionsResumeCommand } from './sessions-resume.js';
@@ -2017,13 +2017,14 @@ export async function renderSessionPreview(query, scope) {
         return;
     }
     const session = outcome.session;
-    if (session._remote && session.machine && session.machine !== machineId()) {
+    const transcriptPeer = transcriptOnPeerOf(session);
+    if (transcriptPeer) {
         const args = ['sessions', 'preview', session.id, '--local'];
         if (scope.json)
             args.push('--json');
-        const rendered = await runOnPeer(args, session.machine);
+        const rendered = await runOnPeer(args, transcriptPeer);
         if (rendered === 'no-target') {
-            console.error(chalk.red(`Session ${session.id} is on ${session.machine}, but that device is not reachable.`));
+            console.error(chalk.red(`Session ${session.id} is on ${transcriptPeer}, but that device is not reachable.`));
             process.exitCode = 1;
         }
         return;
@@ -3873,11 +3874,11 @@ export async function handlePickedSession(picked) {
     }
     // Reading and resuming are on DIFFERENT machines' terms, and conflating them
     // is what RUSH-2022 was. Reading follows the FILE: a synced mirror sits on
-    // this disk, so only a live fan-out row (`_remote`) has to be read on the
-    // peer. Resuming follows the HARNESS STATE, which is on the owning machine
-    // whatever the transcript's location — a mirror included.
+    // this disk, so a peer-owned row with no readable local transcript has to be
+    // read on the peer. Resuming follows the HARNESS STATE, which is on the
+    // owning machine whatever the transcript's location — a mirror included.
     if (picked.action === 'view') {
-        const readFrom = picked.session._remote ? picked.session.machine : undefined;
+        const readFrom = transcriptOnPeerOf(picked.session);
         if (readFrom) {
             const rc = await runOnPeer(['sessions', picked.session.shortId, '--markdown'], readFrom);
             if (rc === 'no-target')
@@ -4503,7 +4504,8 @@ async function renderOneSession(query, mode, scope) {
         }
         if (outcome.kind === 'resolved') {
             const resolved = outcome.session;
-            if (resolved._remote && resolved.machine && resolved.machine !== machineId()) {
+            const transcriptPeer = transcriptOnPeerOf(resolved);
+            if (transcriptPeer) {
                 const args = ['sessions', resolved.id, '--local'];
                 const flag = modeFlag(mode);
                 if (flag)
@@ -4518,9 +4520,9 @@ async function renderOneSession(query, mode, scope) {
                     args.push('--last', String(scope.filter.last));
                 if (scope.redact === false)
                     args.push('--no-redact');
-                const rendered = await runOnPeer(args, resolved.machine);
+                const rendered = await runOnPeer(args, transcriptPeer);
                 if (rendered === 'no-target') {
-                    console.error(chalk.red(`Session ${resolved.id} is on ${resolved.machine}, but that device is not reachable.`));
+                    console.error(chalk.red(`Session ${resolved.id} is on ${transcriptPeer}, but that device is not reachable.`));
                     process.exit(1);
                 }
                 return;

package/dist/commands/teams-picker.js

@@ -9,6 +9,7 @@
 import chalk from 'chalk';
 import { relTime, truncate, humanDuration } from '../lib/format.js';
 import { itemPicker } from '../lib/picker.js';
+import { deliveryDisplayLabel, deliveryColorKey } from '../lib/teams/delivery.js';
 const AGENT_LABEL = {
     claude: 'Claude',
     codex: 'Codex',
@@ -21,6 +22,7 @@ function statusColor(status) {
         case 'pending': return chalk.blue;
         case 'running': return chalk.yellow;
         case 'completed': return chalk.green;
+        case 'stranded': return chalk.yellow;
         case 'failed': return chalk.red;
         case 'stopped': return chalk.gray;
         default: return chalk.white;
@@ -61,10 +63,12 @@ function displayAgent(agent, version) {
 function statusCell(t) {
     if (t.agent_count === 0)
         return chalk.gray('empty');
+    const done = Math.max(0, t.completed - (t.stranded ?? 0));
     const states = [
         [t.pending, chalk.blue, 'pending'],
         [t.running, chalk.yellow, 'working'],
-        [t.completed, chalk.green, 'done'],
+        [done, chalk.green, 'done'],
+        [t.stranded ?? 0, chalk.yellow, 'stranded'],
         [t.failed, chalk.red, 'failed'],
         [t.stopped, chalk.gray, 'stopped'],
     ];
@@ -76,13 +80,16 @@ function statusCell(t) {
     return nonzero.map(([n, color, label]) => color(`${n} ${label}`)).join(chalk.gray(' · '));
 }
 function statusSummaryParts(t) {
+    const done = Math.max(0, t.completed - (t.stranded ?? 0));
     const parts = [];
     if (t.pending)
         parts.push(chalk.blue(`${t.pending} pending`));
     if (t.running)
         parts.push(chalk.yellow(`${t.running} working`));
-    if (t.completed)
-        parts.push(chalk.green(`${t.completed} done`));
+    if (done)
+        parts.push(chalk.green(`${done} done`));
+    if (t.stranded)
+        parts.push(chalk.yellow(`${t.stranded} stranded`));
     if (t.failed)
         parts.push(chalk.red(`${t.failed} failed`));
     if (t.stopped)
@@ -173,7 +180,12 @@ export function buildTeamPreview(row) {
     const nameW = Math.max(6, ...row.agents.map((a) => displayHandle(a).length));
     const agentW = Math.max(8, ...row.agents.map((a) => displayAgent(a.agent_type, a.version).length));
     for (const a of row.agents) {
-        const stat = statusColor(a.status)(a.status);
+        const delivery = a.delivery;
+        const colorKey = delivery ? deliveryColorKey(delivery, a.status) : a.status;
+        const label = delivery
+            ? deliveryDisplayLabel(delivery, a.status)
+            : a.status.toUpperCase();
+        const stat = statusColor(colorKey)(label);
         const metaParts = [];
         if (a.task_type)
             metaParts.push(chalk.magenta(a.task_type));
@@ -244,8 +256,8 @@ function searchHaystack(row) {
         parts.push(a.status);
     }
     // Also include team-level status words exposed in the row ("done",
-    // "working", "pending", "failed", "stopped", "empty") so the search matches
-    // what the user sees on screen.
+    // "working", "pending", "stranded", "failed", "stopped", "empty") so the
+    // search matches what the user sees on screen.
     const t = row.team;
     if (t.agent_count === 0)
         parts.push('empty');
@@ -255,6 +267,8 @@ function searchHaystack(row) {
         parts.push('working', 'running');
     if (t.completed)
         parts.push('done', 'completed');
+    if (t.stranded)
+        parts.push('stranded');
     if (t.failed)
         parts.push('failed');
     if (t.stopped)

package/dist/commands/teams.d.ts

@@ -120,11 +120,11 @@ export declare function cloudDispatchOptions(agent: Pick<AgentProcess, 'prompt'
 export declare function runOneWave(mgr: AgentManager, team: string, json: boolean): Promise<void>;
 export declare function buildTeamRowsFromSnapshots(registry: TeamRegistry, agents: TeamListAgentSnapshot[], 
 /** team name -> the session that spawned it (see teamSpawners). */
-spawners?: Map<string, TeamSpawner>): {
+spawners?: Map<string, TeamSpawner>): Promise<{
     rows: TeamRow[];
     teams: TaskInfo[];
     names: string[];
-};
+}>;
 /**
  * `teams add --remote-cwd` is a no-op trap. `--remote-cwd` comes from the shared
  * `--device` option family (option.ts) and is meaningful for commands that *route*

package/dist/commands/teams.js

@@ -62,6 +62,7 @@ function statusColor(status) {
         case 'running': return chalk.yellow;
         case 'completed': return chalk.green;
         case 'pr_open': return chalk.magenta; // RUSH-2380: process done, PR not merged
+        case 'stranded': return chalk.yellow; // PHNX-2951: done but work not committed
         case 'failed': return chalk.red;
         case 'stopped': return chalk.gray;
         default: return chalk.white;
@@ -150,6 +151,7 @@ function snapshotToStatusDetail(agent) {
         after: agent.after,
         task_type: agent.task_type,
         host: agent.host,
+        workspace_dir: agent.workspace_dir,
     };
 }
 function fullName(type, version) {
@@ -784,6 +786,9 @@ function printAgentDetail(a, session) {
     }
     if (a.has_errors)
         console.log(`    ${chalk.red('! reported an error')}`);
+    if (delivery === 'stranded' && a.workspace_dir) {
+        console.log(`    ${chalk.yellow('! stranded')} uncommitted work at ${a.workspace_dir}`);
+    }
     if (a.pr_url)
         console.log(`    ${chalk.gray('PR  ')}${a.pr_url}`);
 }
@@ -864,17 +869,34 @@ function printAgentSummary(s) {
                 console.log(`      ${chalk.gray('>')} ${truncate(firstLine, 96)}`);
         }
     }
+    if (delivery === 'stranded' && s.workspace_dir) {
+        console.log(`    ${chalk.yellow('! stranded')} uncommitted work at ${s.workspace_dir}`);
+    }
     if (s.pr_url)
         console.log(`    ${chalk.gray('PR      ')} ${chalk.cyan(s.pr_url)}`);
 }
+function formatTeamStatusSummary(summary) {
+    const done = Math.max(0, summary.completed - summary.stranded);
+    const parts = [];
+    if (summary.pending > 0)
+        parts.push(`${summary.pending} pending`);
+    if (summary.running > 0 || parts.length === 0)
+        parts.push(`${summary.running} working`);
+    if (done > 0 || summary.stranded === 0)
+        parts.push(`${done} done`);
+    if (summary.stranded > 0)
+        parts.push(`${summary.stranded} stranded`);
+    if (summary.failed > 0 || parts.length === 0)
+        parts.push(`${summary.failed} failed`);
+    if (summary.stopped > 0 || parts.length === 0)
+        parts.push(`${summary.stopped} stopped`);
+    return `(${parts.join(', ')})`;
+}
 // Render a team's status in the same format the `status` subcommand uses, so
 // the interactive picker's Enter action drops the user into a familiar view.
 async function printTeamStatus(team, result) {
     const { summary, agents } = result;
-    console.log(chalk.bold(`Team ${chalk.cyan(team)}  `) +
-        chalk.gray(summary.pending > 0
-            ? `(${summary.pending} pending, ${summary.running} working, ${summary.completed} done, ${summary.failed} failed, ${summary.stopped} stopped)`
-            : `(${summary.running} working, ${summary.completed} done, ${summary.failed} failed, ${summary.stopped} stopped)`));
+    console.log(chalk.bold(`Team ${chalk.cyan(team)}  `) + chalk.gray(formatTeamStatusSummary(summary)));
     if (agents.length === 0) {
         console.log(chalk.gray('  (no teammates yet — add one with `agents teams add`)'));
     }
@@ -900,10 +922,7 @@ async function printTeamStatus(team, result) {
 // verbose/legacy layout.
 function printTeamSummary(team, result) {
     const { summary, agents } = result;
-    console.log(chalk.bold(`Team ${chalk.cyan(team)}  `) +
-        chalk.gray(summary.pending > 0
-            ? `(${summary.pending} pending, ${summary.running} working, ${summary.completed} done, ${summary.failed} failed, ${summary.stopped} stopped)`
-            : `(${summary.running} working, ${summary.completed} done, ${summary.failed} failed, ${summary.stopped} stopped)`));
+    console.log(chalk.bold(`Team ${chalk.cyan(team)}  `) + chalk.gray(formatTeamStatusSummary(summary)));
     if (agents.length === 0) {
         console.log(chalk.gray('  (no teammates yet — add one with `agents teams add`)'));
     }
@@ -925,12 +944,13 @@ function printTeamSummary(team, result) {
     console.log(chalk.gray('Raw log:     agents teams logs --team ' + team + ' --teammate <name>'));
 }
 // Classify a team into a single bucket for --status filtering.
-//  - empty:   no teammates (created but nobody added yet)
-//  - waiting: only staged teammates — call `teams start` to kick them off
-//  - working: at least one teammate still running
-//  - failed:  at least one teammate failed or was stopped (any failure wins —
-//             even if others finished, you want to know about the failure)
-//  - done:    everyone finished successfully, no failures
+//  - empty:    no teammates (created but nobody added yet)
+//  - waiting:  only staged teammates — call `teams start` to kick them off
+//  - working:  at least one teammate still running
+//  - failed:   at least one teammate failed or was stopped (any failure wins —
+//              even if others finished, you want to know about the failure)
+//  - stranded: everyone finished, but at least one has uncommitted work and no PR
+//  - done:     everyone finished successfully, no failures, no stranded work
 function classifyTeamStatus(t) {
     if (t.agent_count === 0)
         return 'empty';
@@ -943,6 +963,10 @@ function classifyTeamStatus(t) {
     const accounted = t.running + t.completed + t.failed + t.stopped;
     if (accounted < t.agent_count)
         return 'waiting';
+    // Completed-without-delivery is not "done": the work is still in the worktree
+    // and will be lost on cleanup (PHNX-2951).
+    if ((t.stranded ?? 0) > 0)
+        return 'stranded';
     return 'done';
 }
 // Merge persistent team registry with tasks derived from live agents so empty
@@ -959,6 +983,7 @@ function mergeTeams(registry, tasks) {
                 pending: 0,
                 running: 0,
                 completed: 0,
+                stranded: 0,
                 failed: 0,
                 stopped: 0,
                 workspace_dir: null,
@@ -969,7 +994,7 @@ function mergeTeams(registry, tasks) {
     }
     return Array.from(byName.values()).sort((a, b) => new Date(b.modified_at).getTime() - new Date(a.modified_at).getTime());
 }
-function buildTasksFromSnapshots(agents) {
+async function buildTasksFromSnapshots(agents) {
     const byTeam = new Map();
     for (const agent of agents) {
         const teamAgents = byTeam.get(agent.task_name) || [];
@@ -981,6 +1006,7 @@ function buildTasksFromSnapshots(agents) {
         let pending = 0;
         let running = 0;
         let completed = 0;
+        let stranded = 0;
         let failed = 0;
         let stopped = 0;
         let earliestStart = null;
@@ -998,6 +1024,16 @@ function buildTasksFromSnapshots(agents) {
                 failed++;
             else if (status === AgentStatus.STOPPED)
                 stopped++;
+            // Stranded = completed with no PR and a dirty local worktree (PHNX-2951).
+            if (status === AgentStatus.COMPLETED &&
+                !agent.pr_url?.trim() &&
+                !agent.host &&
+                agent.workspace_dir) {
+                const dirty = await hasUncommittedChanges(agent.workspace_dir);
+                if (dirty) {
+                    stranded++;
+                }
+            }
             const startedAt = parseTimestamp(agent.started_at);
             if (startedAt && (!earliestStart || startedAt < earliestStart)) {
                 earliestStart = startedAt;
@@ -1017,6 +1053,7 @@ function buildTasksFromSnapshots(agents) {
             pending,
             running,
             completed,
+            stranded,
             failed,
             stopped,
             workspace_dir: workspaceDir,
@@ -1026,7 +1063,7 @@ function buildTasksFromSnapshots(agents) {
     }
     return tasks.sort((a, b) => new Date(b.modified_at).getTime() - new Date(a.modified_at).getTime());
 }
-export function buildTeamRowsFromSnapshots(registry, agents, 
+export async function buildTeamRowsFromSnapshots(registry, agents, 
 /** team name -> the session that spawned it (see teamSpawners). */
 spawners) {
     const byTeam = new Map();
@@ -1035,7 +1072,26 @@ spawners) {
         details.push(snapshotToStatusDetail(agent));
         byTeam.set(agent.task_name, details);
     }
-    const teams = mergeTeams(registry, buildTasksFromSnapshots(agents));
+    const teams = mergeTeams(registry, await buildTasksFromSnapshots(agents));
+    // Recompute delivery for cached snapshots so `teams list` reflects stranded
+    // work discovered by probing the real worktree (PHNX-2951).
+    for (const details of byTeam.values()) {
+        for (const a of details) {
+            const snapshot = agents.find((s) => s.agent_id === a.agent_id);
+            if (snapshot &&
+                normalizeTeamListStatus(a.status) === AgentStatus.COMPLETED &&
+                !snapshot.pr_url?.trim() &&
+                !snapshot.host &&
+                snapshot.workspace_dir) {
+                const dirty = await hasUncommittedChanges(snapshot.workspace_dir);
+                a.delivery = resolveTeammateDelivery({
+                    status: a.status,
+                    prUrl: snapshot.pr_url,
+                    hasUncommittedChanges: dirty,
+                });
+            }
+        }
+    }
     return {
         teams,
         rows: teams.map((team) => ({
@@ -1107,7 +1163,7 @@ async function loadTeamRows(_mgr) {
     catch {
         // The index is an enrichment here — a missing/locked DB just drops the column.
     }
-    return buildTeamRowsFromSnapshots(registry, agents, spawners);
+    return await buildTeamRowsFromSnapshots(registry, agents, spawners);
 }
 // Picker fallback for `teams logs` when the teammate ref is omitted. Shows a
 // flat list of every teammate with their team context; Enter picks one.
@@ -1271,7 +1327,7 @@ export function registerTeamsCommands(program) {
         .alias('ls')
         .description('List your teams, most recent activity first')
         .option('-a, --agent <agent>', 'Filter: only teams with this agent (e.g. claude or claude@2.1.112)')
-        .option('--status <status>', 'Filter: only teams with this status (working, done, failed, or empty)')
+        .option('--status <status>', 'Filter: only teams with this status (working, done, stranded, failed, or empty)')
         .option('--since <time>', 'Filter: teams active after this time (e.g. "2h", "7d", or ISO date)')
         .option('--until <time>', 'Filter: teams active before this time (e.g. "30d", or ISO date)')
         .option('-n, --limit <n>', 'Show at most this many teams (default: 20)', '20')
@@ -1298,7 +1354,7 @@ export function registerTeamsCommands(program) {
         catch {
             // The session index is an enrichment here; a missing one drops the column.
         }
-        let rows = buildTeamRowsFromSnapshots(registry, everyAgent, spawners).rows;
+        let rows = (await buildTeamRowsFromSnapshots(registry, everyAgent, spawners)).rows;
         // --- query: substring match on team name ---
         if (query) {
             const q = query.toLowerCase();
@@ -1318,7 +1374,7 @@ export function registerTeamsCommands(program) {
         // --- --status: classify each team, filter ---
         if (opts.status) {
             const want = opts.status.toLowerCase();
-            const validStatuses = ['working', 'done', 'failed', 'empty'];
+            const validStatuses = ['working', 'done', 'stranded', 'failed', 'empty'];
             if (!validStatuses.includes(want)) {
                 dieFriction('teams', 'invalid-status-filter', `Invalid --status '${opts.status}'. Use one of: ${validStatuses.join(', ')}`);
             }

package/dist/lib/accounting/rotate.js

@@ -313,7 +313,7 @@ export function pickBalancedCandidate(candidates, nowMs = Date.now()) {
         if (!deduped.has(c))
             excluded.push(c);
     }
-    const { picked, usageUnverified } = preferVerified(sorted, nowMs, weightedRandomByCapacity, 'representative');
+    const { picked, usageUnverified } = preferVerified(sorted, nowMs, (from) => weightedRandomByCapacity(from, nowMs), 'representative');
     return { picked, healthy: sorted, excluded, usageUnverified };
 }
 /**
@@ -376,8 +376,16 @@ export { PROJECTION_HORIZON_MIN, capacityWeight };
  * routing capacity (see {@link capacityWeight}). Floor each weight at 1 so a
  * near-exhausted-but-still-eligible candidate can still be picked occasionally.
  */
-function weightedRandomByCapacity(sorted) {
-    const weights = sorted.map((c) => capacityWeight(getRoutingUsedPercent(c.usageSnapshot), c.usageMinutesToLimit));
+function weightedRandomByCapacity(sorted, nowMs = Date.now()) {
+    const weights = sorted.map((c) => capacityWeight(
+    // An unverified (stale or absent) snapshot carries no trustworthy number,
+    // so it weights as UNVERIFIED_WEIGHT (the floor) instead of by its frozen
+    // usedPercent. Otherwise a day-old "45% used" competes as if it were live
+    // headroom and can win the draw over a verified-healthy account — which is
+    // exactly how balanced launched into an account already at its weekly cap
+    // on a worker whose usage refresh had stalled (PHNX-3479). A verified
+    // snapshot keeps its real remaining-headroom weight.
+    isUsageVerified(c, nowMs) ? getRoutingUsedPercent(c.usageSnapshot) : null, c.usageMinutesToLimit));
     const total = weights.reduce((sum, w) => sum + w, 0);
     if (total <= 0)
         return sorted[0];
@@ -485,7 +493,7 @@ export function pickHarnessWeighted(byHarness, nowMs = Date.now()) {
     const excluded = summaries.filter((s) => s.best === null);
     if (healthy.length === 0)
         return null;
-    const pickedBest = weightedRandomByCapacity(healthy.map((s) => s.best));
+    const pickedBest = weightedRandomByCapacity(healthy.map((s) => s.best), nowMs);
     const picked = healthy.find((s) => s.best === pickedBest);
     return { picked, healthy, excluded };
 }

package/dist/lib/accounting/usage-sync.d.ts

@@ -1,9 +1,18 @@
 import { type DeviceProfile } from '../devices/registry.js';
 import { type ConfiguredDeviceRole } from '../device-config.js';
-import { type CachedUsageSnapshot, type UsageSnapshot } from './usage.js';
+import { type CachedUsageSnapshot } from './usage.js';
 /** How long a single peer push may take before it is abandoned for this tick. */
 export declare const USAGE_PUSH_DEADLINE_MS = 20000;
 export declare const USAGE_PULL_DEADLINE_MS = 20000;
+/**
+ * A worker's newest local usage row older than this triggers a pull from the
+ * primary. A worker cannot self-read usage (setup-token lacks `user:profile`,
+ * RUSH-2392), so its only source of a fresh row is the daemon push every
+ * `USAGE_SYNC_TICK_MS` (15m); this cutoff is 2× that tick, so one missed push
+ * cycle is tolerated before the worker actively pulls. Bounds worker staleness
+ * to ~30m instead of the days-old caches this replaces.
+ */
+export declare const USAGE_SYNC_MAX_AGE_MS: number;
 /** The stdin envelope the `__usage-ingest` verb reads. `v` guards the shape. */
 export interface UsageSyncPayload {
     v: 1;
@@ -75,8 +84,9 @@ export interface UsagePullDeps {
     listRoles?: () => Record<string, ConfiguredDeviceRole>;
     isPinned?: (name: string) => boolean;
     exportRows?: () => Record<string, CachedUsageSnapshot>;
-    readRow?: (usageKey: string) => Pick<UsageSnapshot, 'windows'> | null;
     ingestRows?: (rows: Record<string, CachedUsageSnapshot>) => number;
+    /** Injectable clock for the staleness gate; defaults to `Date.now`. */
+    now?: () => number;
     /** Read the versioned payload from the primary. Default: ssh `__usage-export`. */
     pull?: (device: DeviceProfile) => {
         ok: boolean;

package/dist/lib/accounting/usage-sync.js

@@ -32,10 +32,26 @@ import { sshTargetFor } from '../devices/connect.js';
 import { isHostPinned } from '../devices/known-hosts.js';
 import { machineId, normalizeHost } from '../session/sync/config.js';
 import { isHeadedDeviceRole, listConfiguredDeviceRoles, selfConfiguredDeviceRole, } from '../device-config.js';
-import { exportClaudeUsageCacheRows, ingestPeerClaudeUsageRows, readClaudeUsageCache, } from './usage.js';
+import { exportClaudeUsageCacheRows, ingestPeerClaudeUsageRows, } from './usage.js';
 /** How long a single peer push may take before it is abandoned for this tick. */
 export const USAGE_PUSH_DEADLINE_MS = 20_000;
 export const USAGE_PULL_DEADLINE_MS = 20_000;
+/**
+ * A worker's newest local usage row older than this triggers a pull from the
+ * primary. A worker cannot self-read usage (setup-token lacks `user:profile`,
+ * RUSH-2392), so its only source of a fresh row is the daemon push every
+ * `USAGE_SYNC_TICK_MS` (15m); this cutoff is 2× that tick, so one missed push
+ * cycle is tolerated before the worker actively pulls. Bounds worker staleness
+ * to ~30m instead of the days-old caches this replaces.
+ */
+export const USAGE_SYNC_MAX_AGE_MS = 30 * 60_000;
+/** Epoch ms of a cache row's capture time, or null when unparseable/absent. */
+function capturedAtMs(capturedAt) {
+    if (!capturedAt)
+        return null;
+    const ms = Date.parse(capturedAt);
+    return Number.isFinite(ms) ? ms : null;
+}
 /**
  * Decide, per peer, whether to push the local usage snapshot. Pure.
  *
@@ -109,12 +125,24 @@ export function pullUsageFromPrimary(deps = {}) {
         return result;
     }
     const localRows = (deps.exportRows ?? exportClaudeUsageCacheRows)();
-    const readRow = deps.readRow ?? readClaudeUsageCache;
     const localEntries = Object.entries(localRows);
-    if (localEntries.length > 0 && localEntries.every(([key, row]) => {
-        const fresh = readRow(key);
-        return fresh !== null && fresh.windows.length === row.windows.length;
-    })) {
+    // Fresh means RECENT, not "the cache equals itself". The prior check read the
+    // SAME on-disk cache twice (exportRows() and readRow()) and compared window
+    // COUNT, so `fresh.windows.length === row.windows.length` was always true and
+    // any non-empty worker cache skipped the pull forever — which is how a worker
+    // served a days-old snapshot indefinitely and balanced launched into an
+    // account already at its weekly cap. A worker cannot self-read usage, so any
+    // row older than the sync cadence is stale and must trigger a pull; the merge
+    // is newest-wins + idempotent, so pulling when the primary is no fresher is a
+    // harmless no-op.
+    const now = (deps.now ?? Date.now)();
+    const staleCutoff = now - USAGE_SYNC_MAX_AGE_MS;
+    const allFresh = localEntries.length > 0 &&
+        localEntries.every(([, row]) => {
+            const ms = capturedAtMs(row.capturedAt);
+            return ms !== null && ms >= staleCutoff;
+        });
+    if (allFresh) {
         result.skipped = 'local usage cache is fresh';
         return result;
     }

package/dist/lib/feed/events.js

@@ -22,6 +22,8 @@ import { stampProvenance, resetEventProvenanceForTest } from '../event-provenanc
 /** Lazy perf warehouse write — avoids a hard cycle at module load. */
 function recordPerfTiming(payload) {
     try {
+        const phases = payload.phases && Object.keys(payload.phases).length > 0 ? payload.phases : undefined;
+        const metaJson = phases ? JSON.stringify({ phases }) : undefined;
         // Dynamic import keeps events.ts free of a load-time dependency on perf/db.
         void import('../perf/spool.js').then(({ recordSample }) => {
             recordSample({
@@ -33,6 +35,7 @@ function recordPerfTiming(payload) {
                 agentVersion: payload.version,
                 sessionId: payload.sessionId,
                 cwd: payload.cwd,
+                metaJson,
             });
         }).catch(() => { });
     }
@@ -693,6 +696,7 @@ export function createTimer(label, payload = {}) {
                 version: merged.version,
                 sessionId: merged.sessionId,
                 cwd: merged.cwd,
+                phases: marks,
             });
         },
     };

package/dist/lib/perf/db.d.ts

@@ -6,7 +6,7 @@
  */
 import Database from '../sqlite.js';
 import type { AggregateOptions, PerfAggregateRow } from './types.js';
-export type { AggregateOptions, PerfAggregateRow, PerfSample } from './types.js';
+export type { AggregateOptions, PerfAggregateRow, PerfPhaseStat, PerfSample } from './types.js';
 export { recordSample, shortSessionId, resolveSpoolPath } from './spool.js';
 export { percentile } from '../percentile.js';
 export declare const PERF_SCHEMA_VERSION = 1;

package/dist/lib/perf/db.js

@@ -12,6 +12,31 @@ import { localMachineId } from '../origin-machine.js';
 import { resolveProjectKey } from '../project-key.js';
 import { percentile } from '../percentile.js';
 import { resolveSpoolPath, shortSessionId, _resetPerfSpoolForTest } from './spool.js';
+/**
+ * Parse the `phases` map from a sample's meta_json. Fail-soft: a row with no
+ * meta_json, malformed JSON, or a non-numeric phase value contributes nothing
+ * rather than throwing (the warehouse must survive any writer's shape).
+ */
+function parsePhases(metaJson) {
+    if (!metaJson)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(metaJson);
+    }
+    catch {
+        return undefined;
+    }
+    const phases = parsed?.phases;
+    if (!phases || typeof phases !== 'object')
+        return undefined;
+    const out = {};
+    for (const [name, val] of Object.entries(phases)) {
+        if (typeof val === 'number' && Number.isFinite(val))
+            out[name] = val;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
 export { recordSample, shortSessionId, resolveSpoolPath } from './spool.js';
 export { percentile } from '../percentile.js';
 export const PERF_SCHEMA_VERSION = 1;
@@ -222,7 +247,7 @@ export function aggregateSamples(opts = {}) {
         clauses.push('agent = ?');
         params.push(opts.agent);
     }
-    const rows = db.prepare(`SELECT kind, label, duration_ms, cache, exit_code, status, cwd
+    const rows = db.prepare(`SELECT kind, label, duration_ms, cache, exit_code, status, cwd, meta_json
      FROM samples WHERE ${clauses.join(' AND ')}`).all(...params);
     // Memoize cwd -> project key: resolveProjectKey walks the filesystem for
     // a repo root, and many rows in one warehouse query share the same cwd.
@@ -244,10 +269,21 @@ export function aggregateSamples(opts = {}) {
         const key = `${r.kind}\0${r.label}`;
         let b = map.get(key);
         if (!b) {
-            b = { kind: r.kind, label: r.label, durations: [], hits: 0, stale: 0, misses: 0, errors: 0, blocks: 0, timeouts: 0 };
+            b = { kind: r.kind, label: r.label, durations: [], hits: 0, stale: 0, misses: 0, errors: 0, blocks: 0, timeouts: 0, phases: new Map() };
             map.set(key, b);
         }
         b.durations.push(Number(r.duration_ms));
+        const phases = parsePhases(r.meta_json);
+        if (phases) {
+            for (const [name, ms] of Object.entries(phases)) {
+                let arr = b.phases.get(name);
+                if (!arr) {
+                    arr = [];
+                    b.phases.set(name, arr);
+                }
+                arr.push(ms);
+            }
+        }
         if (r.cache === 'hit')
             b.hits++;
         else if (r.cache === 'stale-prefetch')
@@ -301,6 +337,21 @@ export function aggregateSamples(opts = {}) {
         }
         if (b.timeouts > 0)
             row.timeoutRate = Math.round((b.timeouts / n) * 1000) / 1000;
+        if (b.phases.size > 0) {
+            const phases = {};
+            for (const [name, durs] of b.phases) {
+                if (durs.length === 0)
+                    continue;
+                const ps = durs.slice().sort((a, c) => a - c);
+                phases[name] = {
+                    n: ps.length,
+                    p50Ms: Math.round(percentile(ps, 50)),
+                    p90Ms: Math.round(percentile(ps, 90)),
+                };
+            }
+            if (Object.keys(phases).length > 0)
+                row.phases = phases;
+        }
         if (opts.project)
             row.project = opts.project;
         out.push(row);

package/dist/lib/perf/types.d.ts

@@ -21,6 +21,13 @@ export interface PerfSample {
     status?: string;
     metaJson?: string;
 }
+/** Percentiles for one sub-phase (e.g. agent.run's `startup`) across a bucket. */
+export interface PerfPhaseStat {
+    /** Samples that carried this phase (may be < the row's `n`). */
+    n: number;
+    p50Ms: number;
+    p90Ms: number;
+}
 export interface PerfAggregateRow {
     kind: string;
     label: string;
@@ -31,6 +38,13 @@ export interface PerfAggregateRow {
     meanMs: number;
     maxMs: number;
     minMs: number;
+    /**
+     * Per-sub-phase percentiles parsed from each sample's meta_json `phases`.
+     * Present only when at least one sample in the bucket recorded a phase
+     * (agent.run records `startup` — time from spawnAgent entry to child spawn —
+     * so boot cost is trackable independently of the total run, PHNX-3468).
+     */
+    phases?: Record<string, PerfPhaseStat>;
     cacheHitPct?: number;
     cacheStalePct?: number;
     cacheMissPct?: number;

package/dist/lib/session/live-metadata.js

@@ -15,7 +15,8 @@
 // exist. It parses no transcript and renders nothing — it only reshapes process
 // state the live registry already computed. When the transcript IS on disk, the
 // synthesized row carries its path, so the downstream `buildPreview` renders the
-// real digest; otherwise it renders the header + a "not indexed here" note.
+// real digest. Without a path, a peer-owned row fetches its digest from that peer;
+// a genuinely local row renders the header + a "not indexed here" note.
 import { deriveShortId } from '../text/short-id.js';
 import { isSessionTrackedAgent } from './types.js';
 /**
@@ -50,9 +51,8 @@ export function activeSessionToSessionMeta(active, self, nowMs) {
         topic: active.topic,
         version: active.version,
         messageCount: undefined,
-        // The row runs HERE — the local live registry is machine-local, so a match
-        // resolves without an SSH hop back to a peer.
         machine: active.machine ?? self,
+        _remote: (active.machine ?? self) !== self,
         ticketId: active.ticket?.id,
         prUrl: active.pr?.url,
         prNumber: active.pr?.number,

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

@@ -62,6 +62,8 @@ export interface AgentStatusDetail {
     task_type?: TaskType | null;
     /** Device name the teammate runs on for a distributed (--on) teammate; null for local. */
     host?: string | null;
+    /** Absolute path to the teammate's worktree, when known. */
+    workspace_dir?: string | null;
     /** Sanitized evidence observed at the lifecycle boundary that failed. */
     failure?: TeammateFailure | null;
 }
@@ -73,6 +75,7 @@ export interface TaskStatusResult {
         pending: number;
         running: number;
         completed: number;
+        stranded: number;
         failed: number;
         stopped: number;
     };
@@ -126,6 +129,8 @@ export interface AgentStatusSummary {
     /** Device name for a distributed (--on) teammate; null for local. */
     host: string | null;
     failure: TeammateFailure | null;
+    /** Absolute path to the teammate's worktree, when known. */
+    workspace_dir?: string | null;
     /** ISO timestamp — feed back via --since for delta polling. */
     cursor: string;
 }
@@ -137,6 +142,7 @@ export interface TaskStatusSummaryResult {
         pending: number;
         running: number;
         completed: number;
+        stranded: number;
         failed: number;
         stopped: number;
     };
@@ -164,6 +170,8 @@ export interface TaskInfo {
     pending: number;
     running: number;
     completed: number;
+    /** Completed teammates with uncommitted work and no PR (PHNX-2951). */
+    stranded: number;
     failed: number;
     stopped: number;
     workspace_dir: string | null;

package/dist/lib/teams/api.js

@@ -3,6 +3,7 @@ import { getDelta } from './summarizer.js';
 import { debug } from './debug.js';
 import { buildClaudeLabelMap } from '../session/discover.js';
 import { resolveTeammateDelivery } from './delivery.js';
+import { hasUncommittedChanges } from './worktree.js';
 /**
  * Truncate a bash command for status output.
  * Handles heredocs specially - shows the redirect target instead of contents.
@@ -126,6 +127,7 @@ export function toAgentStatusSummary(detail) {
             .map((m) => trimMessage(m)),
         host: detail.host ?? null,
         failure: detail.failure ?? null,
+        workspace_dir: detail.workspace_dir ?? null,
         cursor: detail.cursor,
     };
 }
@@ -207,7 +209,7 @@ parentSessionId) {
         ? allAgents
         : allAgents.filter((a) => a.status === effectiveFilter);
     const agentStatuses = [];
-    const counts = { pending: 0, running: 0, completed: 0, failed: 0, stopped: 0 };
+    const counts = { pending: 0, running: 0, completed: 0, stranded: 0, failed: 0, stopped: 0 };
     // Count ALL agents for summary (not just filtered)
     for (const agent of allAgents) {
         if (agent.status === AgentStatus.PENDING)
@@ -221,6 +223,30 @@ parentSessionId) {
         else if (agent.status === AgentStatus.STOPPED)
             counts.stopped++;
     }
+    // Stranded count is computed over ALL agents, not the filter-narrowed view,
+    // so a `--filter running` status still reports teammates that completed dirty.
+    // Cache the probe result so we can reuse it when building details for the
+    // filtered subset without probing the worktree twice.
+    const uncommittedCache = new Map();
+    for (const agent of allAgents) {
+        if (agent.status !== AgentStatus.COMPLETED)
+            continue;
+        const shouldProbeWorktree = !agent.prUrl?.trim() &&
+            !agent.hostName &&
+            Boolean(agent.workspaceDir);
+        const hasUncommitted = shouldProbeWorktree
+            ? await hasUncommittedChanges(agent.workspaceDir)
+            : false;
+        uncommittedCache.set(agent.agentId, hasUncommitted);
+        const delivery = resolveTeammateDelivery({
+            status: agent.status,
+            prUrl: agent.prUrl,
+            hasUncommittedChanges: hasUncommitted,
+        });
+        if (delivery === 'stranded') {
+            counts.stranded++;
+        }
+    }
     // Build details only for filtered agents
     let maxTimestamp = since || new Date(0).toISOString(); // Track max timestamp for cursor
     const claudeLabels = allAgents.some((agent) => agent.agentType === 'claude')
@@ -237,6 +263,12 @@ parentSessionId) {
         if (agentTimestamp > maxTimestamp) {
             maxTimestamp = agentTimestamp;
         }
+        const hasUncommitted = uncommittedCache.get(agent.agentId) ?? false;
+        const delivery = resolveTeammateDelivery({
+            status: agent.status,
+            prUrl: agent.prUrl,
+            hasUncommittedChanges: hasUncommitted,
+        });
         const detail = {
             agent_id: agent.agentId,
             agent_type: agent.agentType,
@@ -254,15 +286,13 @@ parentSessionId) {
             after: agent.after,
             task_type: agent.taskType,
             host: agent.hostName,
+            workspace_dir: agent.workspaceDir,
             failure: agent.failure,
             mode: agent.mode,
             cloud_session_id: agent.cloudSessionId,
             cloud_provider: agent.cloudProvider,
             pr_url: agent.prUrl,
-            delivery: resolveTeammateDelivery({
-                status: agent.status,
-                prUrl: agent.prUrl,
-            }),
+            delivery,
             files_created: delta.new_files_created,
             files_modified: delta.new_files_modified,
             files_read: delta.new_files_read,
@@ -297,7 +327,7 @@ export async function handleTasks(manager, limit = 10) {
     }
     const tasks = [];
     for (const [taskName, agents] of taskMap) {
-        let pending = 0, running = 0, completed = 0, failed = 0, stopped = 0;
+        let pending = 0, running = 0, completed = 0, stranded = 0, failed = 0, stopped = 0;
         let earliestStart = null;
         let latestActivity = null;
         let workspaceDir = null;
@@ -313,6 +343,19 @@ export async function handleTasks(manager, limit = 10) {
                 failed++;
             else if (agent.status === AgentStatus.STOPPED)
                 stopped++;
+            // Stranded = completed, no PR, local worktree still dirty. Probes the real
+            // worktree so `teams tasks` and `teams list --status` don't classify lost
+            // work as done (PHNX-2951).
+            if (agent.status === AgentStatus.COMPLETED && !agent.prUrl?.trim() && !agent.hostName && agent.workspaceDir) {
+                const delivery = resolveTeammateDelivery({
+                    status: agent.status,
+                    prUrl: agent.prUrl,
+                    hasUncommittedChanges: await hasUncommittedChanges(agent.workspaceDir),
+                });
+                if (delivery === 'stranded') {
+                    stranded++;
+                }
+            }
             // Track earliest start (created_at)
             if (!earliestStart || agent.startedAt < earliestStart) {
                 earliestStart = agent.startedAt;
@@ -336,6 +379,7 @@ export async function handleTasks(manager, limit = 10) {
             pending,
             running,
             completed,
+            stranded,
             failed,
             stopped,
             workspace_dir: workspaceDir,

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

@@ -12,13 +12,17 @@
  */
 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';
+export type TeammateDelivery = 'pending' | 'in_progress' | 'pr_open' | 'pr_merged' | 'no_pr' | 'stranded' | '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".
+ *
+ * When the process completed with no PR and uncommitted changes remain in the
+ * worktree, delivery is `stranded` — the work exists only locally and will be
+ * lost if the worktree is cleaned up (PHNX-2951).
  */
 export declare function resolveTeammateDelivery(opts: {
     status: AgentStatus | string;
@@ -28,14 +32,20 @@ export declare function resolveTeammateDelivery(opts: {
      * `null`/`undefined` = unknown; with a `prUrl` that means `pr_open`.
      */
     prMerged?: boolean | null;
+    /**
+     * Whether the teammate's worktree has uncommitted changes. Only consulted
+     * when the process completed without a PR URL.
+     */
+    hasUncommittedChanges?: boolean | null;
 }): TeammateDelivery;
 /**
  * Human label for `teams status` rows. Replaces bare COMPLETED with PR OPEN
- * when delivery is still pending merge.
+ * when delivery is still pending merge, and with STRANDED when uncommitted
+ * work is stranded in the worktree.
  */
 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.
+ * Color key for statusColor-style switches. `pr_open` and `stranded` get their
+ * own keys so the rows are visually distinct from green COMPLETED.
  */
 export declare function deliveryColorKey(delivery: TeammateDelivery, processStatus: string): string;

package/dist/lib/teams/delivery.js

@@ -17,6 +17,10 @@ import { AgentStatus } from './agents.js';
  * 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".
+ *
+ * When the process completed with no PR and uncommitted changes remain in the
+ * worktree, delivery is `stranded` — the work exists only locally and will be
+ * lost if the worktree is cleaned up (PHNX-2951).
  */
 export function resolveTeammateDelivery(opts) {
     const status = String(opts.status);
@@ -30,8 +34,9 @@ export function resolveTeammateDelivery(opts) {
         return 'stopped';
     if (status === AgentStatus.COMPLETED || status === 'completed') {
         const prUrl = opts.prUrl?.trim();
-        if (!prUrl)
-            return 'no_pr';
+        if (!prUrl) {
+            return opts.hasUncommittedChanges ? 'stranded' : 'no_pr';
+        }
         if (opts.prMerged === true)
             return 'pr_merged';
         return 'pr_open';
@@ -40,21 +45,26 @@ export function resolveTeammateDelivery(opts) {
 }
 /**
  * Human label for `teams status` rows. Replaces bare COMPLETED with PR OPEN
- * when delivery is still pending merge.
+ * when delivery is still pending merge, and with STRANDED when uncommitted
+ * work is stranded in the worktree.
  */
 export function deliveryDisplayLabel(delivery, processStatus) {
     if (delivery === 'pr_open')
         return 'PR OPEN';
     if (delivery === 'pr_merged')
         return 'COMPLETED';
+    if (delivery === 'stranded')
+        return 'STRANDED';
     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.
+ * Color key for statusColor-style switches. `pr_open` and `stranded` get their
+ * own keys so the rows are visually distinct from green COMPLETED.
  */
 export function deliveryColorKey(delivery, processStatus) {
     if (delivery === 'pr_open')
         return 'pr_open';
+    if (delivery === 'stranded')
+        return 'stranded';
     return String(processStatus);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.59",
+  "version": "1.22.60",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",