@phnx-labs/agents-cli 1.22.58 → 1.22.60

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

@@ -13,7 +13,7 @@ import { type ToolScanResumePoint } from './tool-store.js';
 /** Current schema version; bumped when migrations are added. Exported so tests
  * assert against the constant instead of hardcoding a number that every bump
  * then has to chase (docs/sessions.md calls the constant the source of truth). */
-export declare const SCHEMA_VERSION = 43;
+export declare const SCHEMA_VERSION = 44;
 /**
  * Bump to force the content extractor (assistant-answer text, alongside the
  * user-prompt text every harness already accumulates) to re-derive on every
@@ -317,6 +317,16 @@ export declare function getSessionExistenceCacheStats(): {
 };
 /** Query sessions from the database, applying filters and ordering by last-activity descending (default). */
 export declare function querySessions(options?: QueryOptions): SessionMeta[];
+/**
+ * Cheap query for the daemon's deferred tool-index pass (PHNX-3411).
+ *
+ * Returns the most-recently-active sessions whose parseSession reads a large
+ * flat transcript (kimi: wire.jsonl, grok: chat_history.jsonl). Their scanners
+ * produce no events, so upsertSessionsBatch skips them in the warm tick to
+ * avoid wedging the event loop. ensureToolIndex uses tool_scan_ledger stamps
+ * to skip already-current rows and applies byte/file budget caps.
+ */
+export declare function querySessionsForDeferredToolIndex(limit: number): SessionMeta[];
 /** Count sessions matching the given filter options. */
 export declare function countSessions(options?: QueryOptions): number;
 /** One grouped row in a cost/duration rollup. */
@@ -519,14 +529,30 @@ export declare function queryResourceUsageStats(options: QueryOptions & {
     limit?: number;
 }): ResourceStatRow[];
 /**
- * Coverage of the resource-usage signal: how many distinct sessions carry any
- * row in session_resource_usage vs. the total indexed. A low ratio means the
- * historical backfill (`agents sessions backfill resources`) hasn't run — the
- * stats surface uses this to tell the user their zero-counts may just be
- * un-scanned history, not genuine non-use.
+ * Coverage of the resource-usage signal, as three honest facts:
+ *
+ * - `scanned`  — sessions the resource extractor has actually processed, i.e.
+ *   those carrying a `resource_scan_ledger` row at the current
+ *   `RESOURCE_INDEX_VERSION`. This is the true "has the historical backfill run"
+ *   signal: the ledger is stamped for EVERY scanned session, including ones that
+ *   invoked nothing (`resource_count = 0`), so `scanned/total` rises to ~1 after
+ *   `agents sessions backfill resources` regardless of how sparse explicit
+ *   invocations are.
+ * - `covered`  — distinct sessions that carry AT LEAST ONE row in
+ *   `session_resource_usage`, i.e. that actually recorded an explicit invocation.
+ *   This is an ABSOLUTE signal count, not a coverage ratio: it stays small even
+ *   at full scan coverage because most sessions invoke no skill/command, and a
+ *   non-recording harness contributes none by construction.
+ * - `total`    — sessions indexed.
+ *
+ * The two were previously conflated: `covered/total` was framed as coverage and
+ * read ~1.2% even after a full backfill (most sessions genuinely invoke nothing),
+ * so the "run the backfill" hint never cleared. Keying the hint on `scanned/total`
+ * fixes that — see `commands/sessions-stats.ts` (PHNX-2301).
  */
 export declare function resourceUsageCoverage(): {
     covered: number;
+    scanned: number;
     total: number;
 };
 /** Outcome of a resource-usage backfill run. */

package/dist/lib/session/db.js

@@ -27,7 +27,7 @@ const DB_PATH = getSessionsDbPath();
 /** Current schema version; bumped when migrations are added. Exported so tests
  * assert against the constant instead of hardcoding a number that every bump
  * then has to chase (docs/sessions.md calls the constant the source of truth). */
-export const SCHEMA_VERSION = 43;
+export const SCHEMA_VERSION = 44;
 /**
  * Bump to force the content extractor (assistant-answer text, alongside the
  * user-prompt text every harness already accumulates) to re-derive on every
@@ -1205,6 +1205,32 @@ function migrateSchema(db, fromVersion) {
         if (!cols.has('end_timestamp'))
             db.exec(`ALTER TABLE tool_calls ADD COLUMN end_timestamp TEXT`);
     }
+    if (fromVersion < 44) {
+        // v43 -> v44: backfill duration_ms for sessions whose harness scan extractor
+        // never derived it (PHNX-3457). rush/grok/kimi/cursor/muse/antigravity/hermes/
+        // openclaw left duration_ms NULL — 52% of the corpus, 100% of rush — so the
+        // console median was computed over only the ~48% that carried it, skewing it
+        // short. Going forward resolveDurationMs() populates it at every upsert; this
+        // repairs already-indexed rows in place from the timestamps they already store
+        // (last_activity, itself resolved from the last-message time else file mtime,
+        // minus the creation timestamp), so no transcript is re-parsed. julianday is
+        // avoided because it does not accept a trailing 'Z'; the arithmetic is done in
+        // JS with the exact Date.parse resolveDurationMs uses, keeping the backfill and
+        // the live path consistent. Only rows with a positive span are touched; a NULL
+        // that cannot be resolved stays NULL rather than becoming a fabricated 0.
+        const nullDurationRows = db.prepare(`SELECT id, timestamp, last_activity FROM sessions
+       WHERE duration_ms IS NULL AND last_activity IS NOT NULL`).all();
+        // Runs inside migrateSchema's own transaction (db.ts:1468), so no nested
+        // db.transaction() here — that would raise "transaction within a transaction".
+        const update = db.prepare(`UPDATE sessions SET duration_ms = ? WHERE id = ?`);
+        for (const row of nullDurationRows) {
+            const startMs = Date.parse(row.timestamp);
+            const lastMs = Date.parse(row.last_activity);
+            if (Number.isFinite(startMs) && Number.isFinite(lastMs) && lastMs > startMs) {
+                update.run(lastMs - startMs, row.id);
+            }
+        }
+    }
 }
 /**
  * Stamp `account_key` / `account_org` / `account` on every Claude row from its
@@ -2075,7 +2101,7 @@ export function upsertSession(meta, content, scan, assistantContent = '') {
         cache_write_tokens: meta.cacheWriteTokens ?? null,
         cost_usd: meta.costUsd ?? null,
         cost_usd_nocache: meta.costUsdNoCache ?? null,
-        duration_ms: meta.durationMs ?? null,
+        duration_ms: resolveDurationMs(meta, scan),
         model: meta.model ?? null,
         tool_call_count: meta.toolCallCount ?? null,
         file_path: meta.filePath,
@@ -2163,6 +2189,23 @@ export function upsertSessionsBatch(entries) {
                 ? { ...entry, meta: { ...entry.meta, ...fanOutCounts(entry.events, entry.meta.agent) } }
                 : entry;
         }
+        // Harnesses whose scanners produce no events AND whose parseSession reads a
+        // potentially large flat transcript file (not a compact SQLite DB). Calling
+        // parseSession on the warm tick for an active large session wedges the Node
+        // event loop for seconds, making browser IPC miss its connection window
+        // (PHNX-3411). Defer their tool-call indexing to runDeferredToolIndex, which
+        // uses ensureToolIndex with tool_scan_ledger stamps and byte/file budget caps.
+        // NOT opencode — parseOpenCode issues a targeted SQLite query, so it is fast
+        // even for large sessions and its results populate recentDirectoriesTouched.
+        const LARGE_TRANSCRIPT_AGENTS = new Set(['kimi', 'grok']);
+        if (!entry.events && LARGE_TRANSCRIPT_AGENTS.has(entry.meta.agent)) {
+            return entry;
+        }
+        // Enrich the entry. When the scanner already provided events, use them
+        // directly (no transcript re-read). When it didn't — e.g. OpenCode whose
+        // scanner produces only metadata but whose parseOpenCode is a fast SQLite
+        // query — fall back to parseSession. Agents that would call an expensive
+        // flat-file parse already returned above.
         try {
             const toolSourcePath = toolEvidenceSourcePath(entry.meta.filePath, entry.meta.agent);
             const toolScan = toolSourcePath === entry.meta.filePath
@@ -2171,9 +2214,6 @@ export function upsertSessionsBatch(entries) {
                     const stat = fs.statSync(toolSourcePath);
                     return { fileMtimeMs: stat.mtimeMs, fileSize: stat.size };
                 })();
-            // Some non-resumable scanners already normalized the transcript while
-            // deriving metadata. Reuse those events; scanners that only read summary
-            // metadata fall back to exactly one normalized parse here.
             const events = entry.events ?? parseSession(entry.meta.filePath, entry.meta.agent);
             writeResourceUsage(entry.meta.id, events, entry.meta.cwd);
             // Resume the tool index from the last scan of this append-only stream when
@@ -2302,7 +2342,7 @@ export function upsertSessionsBatch(entries) {
                     cache_write_tokens: meta.cacheWriteTokens ?? null,
                     cost_usd: meta.costUsd ?? null,
                     cost_usd_nocache: meta.costUsdNoCache ?? null,
-                    duration_ms: meta.durationMs ?? null,
+                    duration_ms: resolveDurationMs(meta, scan),
                     model: meta.model ?? null,
                     tool_call_count: meta.toolCallCount ?? null,
                     file_path: meta.filePath,
@@ -2599,6 +2639,36 @@ function resolveLastActivity(meta, scan) {
         return new Date(scan.fileMtimeMs).toISOString();
     return meta.timestamp;
 }
+/**
+ * The persisted wall-clock span for a session (PHNX-3457).
+ *
+ * `durationMs` is canonically `lastTs − firstTs`. Some harness scan extractors
+ * derive it themselves from per-event timestamps (claude/codex/droid/gemini/
+ * opencode set `meta.durationMs`); the rest (rush/grok/kimi/cursor/muse/
+ * antigravity/hermes/openclaw) never did, so `duration_ms` landed NULL for them —
+ * 52% of the corpus, including 100% of the dominant `rush` usage — and the
+ * console median was computed over only the ~48% that happened to carry it,
+ * skewing it short and misleading.
+ *
+ * This closes the gap at the single write boundary every harness funnels
+ * through, so parity is automatic rather than per-extractor: when the extractor
+ * already computed a precise span, keep it; otherwise derive it from the same
+ * `timestamp` (creation) and `resolveLastActivity` (last event, itself resolved
+ * from the harness's last-message time, else file mtime) that the row already
+ * stores. Returns null only when no positive span can be established (a single
+ * timestamped event, or a clock that runs backwards), which reads as NULL rather
+ * than a fabricated 0.
+ */
+function resolveDurationMs(meta, scan) {
+    if (meta.durationMs != null)
+        return meta.durationMs;
+    const startMs = Date.parse(meta.timestamp);
+    const lastMs = Date.parse(resolveLastActivity(meta, scan));
+    if (Number.isFinite(startMs) && Number.isFinite(lastMs) && lastMs > startMs) {
+        return lastMs - startMs;
+    }
+    return null;
+}
 export function isSessionActivityFresh(row, maxAgeMs, nowMs) {
     const parsedActivityMs = Date.parse(row.last_activity ?? row.timestamp);
     const activityMs = Number.isFinite(parsedActivityMs) ? parsedActivityMs : row.file_mtime_ms ?? undefined;
@@ -2892,6 +2962,26 @@ export function querySessions(options = {}) {
     const trimmed = options.limit ? live.slice(0, options.limit) : live;
     return trimmed.map(rowToMeta);
 }
+/**
+ * Cheap query for the daemon's deferred tool-index pass (PHNX-3411).
+ *
+ * Returns the most-recently-active sessions whose parseSession reads a large
+ * flat transcript (kimi: wire.jsonl, grok: chat_history.jsonl). Their scanners
+ * produce no events, so upsertSessionsBatch skips them in the warm tick to
+ * avoid wedging the event loop. ensureToolIndex uses tool_scan_ledger stamps
+ * to skip already-current rows and applies byte/file budget caps.
+ */
+export function querySessionsForDeferredToolIndex(limit) {
+    const db = getDB();
+    const rows = db.prepare(`
+    SELECT * FROM sessions
+    WHERE file_path IS NOT NULL
+      AND agent IN ('kimi', 'grok')
+    ORDER BY last_activity DESC, timestamp DESC
+    LIMIT ?
+  `).all(limit);
+    return rows.map(rowToMeta);
+}
 /** Count sessions matching the given filter options. */
 export function countSessions(options = {}) {
     const db = getDB();
@@ -3333,17 +3423,43 @@ export function queryResourceUsageStats(options) {
     return db.prepare(sql).all(...allParams);
 }
 /**
- * Coverage of the resource-usage signal: how many distinct sessions carry any
- * row in session_resource_usage vs. the total indexed. A low ratio means the
- * historical backfill (`agents sessions backfill resources`) hasn't run — the
- * stats surface uses this to tell the user their zero-counts may just be
- * un-scanned history, not genuine non-use.
+ * Coverage of the resource-usage signal, as three honest facts:
+ *
+ * - `scanned`  — sessions the resource extractor has actually processed, i.e.
+ *   those carrying a `resource_scan_ledger` row at the current
+ *   `RESOURCE_INDEX_VERSION`. This is the true "has the historical backfill run"
+ *   signal: the ledger is stamped for EVERY scanned session, including ones that
+ *   invoked nothing (`resource_count = 0`), so `scanned/total` rises to ~1 after
+ *   `agents sessions backfill resources` regardless of how sparse explicit
+ *   invocations are.
+ * - `covered`  — distinct sessions that carry AT LEAST ONE row in
+ *   `session_resource_usage`, i.e. that actually recorded an explicit invocation.
+ *   This is an ABSOLUTE signal count, not a coverage ratio: it stays small even
+ *   at full scan coverage because most sessions invoke no skill/command, and a
+ *   non-recording harness contributes none by construction.
+ * - `total`    — sessions indexed.
+ *
+ * The two were previously conflated: `covered/total` was framed as coverage and
+ * read ~1.2% even after a full backfill (most sessions genuinely invoke nothing),
+ * so the "run the backfill" hint never cleared. Keying the hint on `scanned/total`
+ * fixes that — see `commands/sessions-stats.ts` (PHNX-2301).
  */
 export function resourceUsageCoverage() {
     const db = getDB();
     const covered = db.prepare(`SELECT COUNT(DISTINCT session_id) AS n FROM session_resource_usage`).get().n;
+    // JOIN sessions so a ledger row for a since-vanished transcript (dropped from
+    // `sessions` but not yet from the ledger) can't inflate scan coverage past the
+    // indexed set. Only rows at the current extractor version count as scanned —
+    // a stale-version row is re-derived on the next backfill, so it is not yet
+    // "covered" for this extractor.
+    const scanned = db.prepare(`
+    SELECT COUNT(*) AS n
+    FROM resource_scan_ledger l
+    JOIN sessions s ON s.id = l.session_id
+    WHERE l.extractor_version = ?
+  `).get(RESOURCE_INDEX_VERSION).n;
     const total = db.prepare(`SELECT COUNT(*) AS n FROM sessions`).get().n;
-    return { covered, total };
+    return { covered, scanned, total };
 }
 /** Has this session's resource usage been derived at the current extractor version for this exact file? */
 function needsResourceIndex(db, sessionId, stamp) {

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/smart-launch.d.ts

@@ -95,6 +95,12 @@ export declare function resolveDeviceAuto(agent?: string, opts?: {
     /** Route only to devices with a row the interactive account picker can launch. */
     accountPicker?: boolean;
     probe?: (pool: string[], agent?: AgentType) => Promise<Map<string, DevicePlacementSignal>>;
+    /**
+     * Preferred hosts (`auto-launch.preferred`) that get the ranking boost.
+     * Defaults to the stored fleet block resolved over the candidate pool;
+     * injectable so a test pins it without touching disk.
+     */
+    preferred?: ReadonlySet<string>;
 }): Promise<DeviceAutoPlan>;
 /**
  * Resolve host for `--device auto`. Does NOT pick harness or accounts.

package/dist/lib/smart-launch.js

@@ -8,7 +8,7 @@
 import { queryAffinityRollup } from './session/db.js';
 import { localMachineId } from './session/origin-machine.js';
 import { loadDevicesSync } from './devices/registry.js';
-import { describeAutoPool, filterAutoPool, isAutoPoolMember } from './devices/pool.js';
+import { autoLaunchPreferredSet, describeAutoPool, filterAutoPool, isAutoPoolMember } from './devices/pool.js';
 import { normalizeHost } from './machine-id.js';
 import { probePoolSignals } from './teams/placement-probe.js';
 import { pickBestDevice } from './teams/scheduler.js';
@@ -153,7 +153,10 @@ export async function resolveDeviceAuto(agent, opts = {}) {
     if (eligiblePool.length === 0) {
         throw new Error(formatNoHealthyDeviceError(pool, signals, agent));
     }
-    const picked = pickBestDevice(eligiblePool, [], { signals, agentLabel: agent });
+    // `agents devices prefer <name>` boosts a device in the ranking — resolved
+    // over the same pool so a fleet default reaches a doc-less box.
+    const preferred = opts.preferred ?? autoLaunchPreferredSet(pool, { roster: pool });
+    const picked = pickBestDevice(eligiblePool, [], { signals, agentLabel: agent, preferred });
     return {
         host: picked === local ? null : picked,
         pickedDeviceKey: picked,

package/dist/lib/staleness/writers/plugins.js

@@ -8,8 +8,11 @@ function buildPluginsWriter(agent) {
         write({ version, versionHome, selection }) {
             const all = discoverPlugins();
             const map = new Map(all.map(p => [p.name, p]));
-            // Clean orphan plugin-skills from plugins that no longer exist.
-            cleanOrphanedPluginSkills(agent, versionHome, new Set(all.map(p => p.name)));
+            // Clean orphan plugin-skills from plugins that no longer exist. Pass the
+            // discovered plugins (not just names) so a stale install under one
+            // marketplace is trashed even when another marketplace still ships that
+            // name — the PHNX-2618 shadow `code` plugin.
+            cleanOrphanedPluginSkills(agent, versionHome, all);
             const synced = [];
             for (const name of selection) {
                 const plugin = map.get(name);

package/dist/lib/staleness/writers/subagents.js

@@ -25,10 +25,16 @@ function buildSubagentsWriter(agent) {
             const dir = target.dir(versionHome);
             const synced = [];
             const paths = [];
+            const errors = [];
             for (const name of selection) {
                 const sub = map.get(name);
-                if (!sub)
+                if (!sub) {
+                    // Requested but not discoverable as an installed central subagent —
+                    // e.g. its AGENT.md failed to parse. Say so instead of silently
+                    // dropping it, which read as an unactionable doctor "hold" (PHNX-3187).
+                    errors.push(`subagent '${name}': no parseable AGENT.md in ~/.agents/subagents`);
                     continue;
+                }
                 try {
                     target.write(dir, sub);
                     synced.push(sub.name);
@@ -39,9 +45,13 @@ function buildSubagentsWriter(agent) {
                             paths.push(entry.path);
                     }
                 }
-                catch { /* per-item sync failure: skip */ }
+                catch (e) {
+                    // A genuine fs/transform failure must surface with its reason, not
+                    // vanish behind a bare `catch` (RUSH-2677 / PHNX-3187).
+                    errors.push(`subagent '${sub.name}': ${e.message}`);
+                }
             }
-            return { synced, paths };
+            return errors.length > 0 ? { synced, paths, errors } : { synced, paths };
         },
     };
 }

package/dist/lib/state.d.ts

@@ -198,10 +198,13 @@ export declare function getMonitorsDir(): string;
  * Path to built-in monitor definitions shipped in the system repo
  * (`~/.agents/.system/monitors/`). Unioned under the user monitors dir by
  * listMonitors()/readMonitor(): a monitor shipped here is available on every
- * install, and a user monitor of the same name overrides it. A built-in with no
- * `enabled:` field is opt-in — it stays disabled until the user enables it,
- * which materializes a user copy (writes never touch this pull-only mirror). The
- * directory need not exist.
+ * install, and a user monitor of the same name overrides it. A built-in is
+ * enabled by default like every other system-layer resource — it runs on every
+ * install unless the user shadows it with `enabled: false` (via `agents monitors
+ * pause`, which materializes a user copy; writes never touch this pull-only
+ * mirror). A shared-input built-in still carries its own `device:` owner pin in
+ * the shipped YAML so exactly one box fires it (SING-9). The directory need not
+ * exist.
  */
 export declare function getSystemMonitorsDir(): string;
 /** Path to the durable per-monitor state-diff store + fire history

package/dist/lib/state.js

@@ -491,10 +491,13 @@ export function getMonitorsDir() { return process.env.AGENTS_MONITORS_DIR ?? MON
  * Path to built-in monitor definitions shipped in the system repo
  * (`~/.agents/.system/monitors/`). Unioned under the user monitors dir by
  * listMonitors()/readMonitor(): a monitor shipped here is available on every
- * install, and a user monitor of the same name overrides it. A built-in with no
- * `enabled:` field is opt-in — it stays disabled until the user enables it,
- * which materializes a user copy (writes never touch this pull-only mirror). The
- * directory need not exist.
+ * install, and a user monitor of the same name overrides it. A built-in is
+ * enabled by default like every other system-layer resource — it runs on every
+ * install unless the user shadows it with `enabled: false` (via `agents monitors
+ * pause`, which materializes a user copy; writes never touch this pull-only
+ * mirror). A shared-input built-in still carries its own `device:` owner pin in
+ * the shipped YAML so exactly one box fires it (SING-9). The directory need not
+ * exist.
  */
 export function getSystemMonitorsDir() { return process.env.AGENTS_SYSTEM_MONITORS_DIR ?? SYSTEM_MONITORS_DIR; }
 /** Path to the durable per-monitor state-diff store + fire history

package/dist/lib/subagents.js

@@ -23,7 +23,12 @@ export function parseSubagentFrontmatter(filePath) {
     }
     try {
         const content = fs.readFileSync(filePath, 'utf-8');
-        const lines = content.split('\n');
+        // Split on CRLF or LF: git checks text files out with CRLF on Windows
+        // (core.autocrlf), so a plain split('\n') leaves a trailing '\r' on every
+        // line and the frontmatter fence `'---\r' !== '---'` never matches —
+        // silently dropping the subagent from discovery so it can never be
+        // installed or reconciled (PHNX-3187).
+        const lines = content.split(/\r?\n/);
         // Check for YAML frontmatter
         if (lines[0] === '---') {
             const endIndex = lines.slice(1).findIndex((l) => l === '---');
@@ -52,7 +57,8 @@ export function getSubagentBody(filePath) {
         return '';
     }
     const content = fs.readFileSync(filePath, 'utf-8');
-    const lines = content.split('\n');
+    // CRLF-robust for the same reason as parseSubagentFrontmatter (PHNX-3187).
+    const lines = content.split(/\r?\n/);
     // Skip YAML frontmatter
     if (lines[0] === '---') {
         const endIndex = lines.slice(1).findIndex((l) => l === '---');

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;