@phnx-labs/agents-cli 1.22.26 → 1.22.27

package/dist/lib/session/recovery.js

@@ -1,8 +1,11 @@
-import { AGENTS } from '../agents.js';
+import * as fs from 'fs';
+import * as path from 'path';
+import { AGENTS, agentConfigDirName } from '../agents.js';
 import { isSelfHost } from '../devices/self-host.js';
 import { nativeResume } from '../exec.js';
 import { machineId, normalizeHost } from '../machine-id.js';
 import { collectRunCandidates, formatNoHealthyAccountError, pickBalancedCandidate, readinessFromCandidate, } from '../rotate.js';
+import { getVersionHomePath } from '../versions.js';
 export class SessionRecoveryError extends Error {
     constructor(message) {
         super(message);
@@ -41,6 +44,99 @@ function sourceReason(session, candidates) {
         ? `origin ${session.agent}@${session.version} has no native resume form`
         : `origin ${session.agent}@${session.version} is ${readiness.reason}`;
 }
+function isPathInside(candidate, dir) {
+    const rel = path.relative(dir, candidate);
+    return rel === '' || (!!rel && !rel.startsWith('..') && !path.isAbsolute(rel));
+}
+function existingDirectory(dir) {
+    if (!dir)
+        return undefined;
+    try {
+        return fs.statSync(dir, { throwIfNoEntry: false })?.isDirectory() ? dir : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Read the launch cwd Claude used to choose its projects/<cwd-key> directory.
+ * Claude can record attachment envelopes before the first user turn, and those
+ * envelopes retain the actual launch cwd even after the session changes dirs. */
+function readClaudeLaunchCwd(filePath) {
+    const maxBytes = 2 * 1024 * 1024;
+    let fd;
+    try {
+        fd = fs.openSync(filePath, 'r');
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        const chunk = Buffer.alloc(maxBytes);
+        const bytesRead = fs.readSync(fd, chunk, 0, maxBytes, 0);
+        const lines = chunk.toString('utf8', 0, bytesRead).split('\n');
+        for (const line of lines) {
+            if (!line.trim())
+                continue;
+            try {
+                const parsed = JSON.parse(line);
+                if (typeof parsed?.cwd !== 'string' || !path.isAbsolute(parsed.cwd))
+                    continue;
+                if (existingDirectory(parsed.cwd))
+                    return parsed.cwd;
+            }
+            catch {
+                // A malformed line or vanished cwd cannot identify a usable native home.
+            }
+        }
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    return undefined;
+}
+/**
+ * Prove that the indexed transcript is reachable from the exact active version
+ * home that would receive native resume. Retained trash/backup transcripts are
+ * intentionally rejected here: they remain readable by `/continue`, but a new
+ * installation with the same version number must not native-resume an empty
+ * isolated home.
+ */
+export function inspectNativeResumeSession(session, versionHome) {
+    let realFile;
+    try {
+        realFile = fs.realpathSync(session.filePath);
+    }
+    catch {
+        return { available: false, reason: 'the indexed transcript is no longer present in the origin home' };
+    }
+    const roots = [versionHome, path.join(versionHome, agentConfigDirName(session.agent))];
+    const owned = roots.some((root) => {
+        try {
+            return isPathInside(realFile, fs.realpathSync(root));
+        }
+        catch {
+            return false;
+        }
+    });
+    if (!owned) {
+        return {
+            available: false,
+            reason: `the indexed transcript is retained outside the active ${session.agent}@${session.version ?? 'unknown'} home`,
+        };
+    }
+    if (session.agent === 'claude') {
+        const cwd = readClaudeLaunchCwd(realFile);
+        if (!cwd) {
+            return {
+                available: false,
+                reason: 'the Claude transcript does not identify an existing original project directory',
+            };
+        }
+        return { available: true, cwd };
+    }
+    const cwd = existingDirectory(session.cwd);
+    return { available: true, cwd };
+}
 /**
  * Decide how a durable session resumes on the device that owns it.
  *
@@ -49,7 +145,7 @@ function sourceReason(session, candidates) {
  * same harness and uses `/continue`, whose indexed transcript reader can reach
  * retained version trash. No healthy same-harness account is a loud failure.
  */
-export function resolveSessionRecoveryFromCandidates(session, candidates, supportsNative = nativeResume) {
+export function resolveSessionRecoveryFromCandidates(session, candidates, supportsNative = nativeResume, nativeInspection) {
     const agent = runnableSessionAgent(session);
     const device = sessionOriginDevice(session);
     const source = session.version
@@ -69,11 +165,22 @@ export function resolveSessionRecoveryFromCandidates(session, candidates, suppor
     }
     const version = selection.picked.version;
     if (session.version === version && supportsNative(agent, version)) {
+        const inspection = nativeInspection
+            ?? inspectNativeResumeSession(session, getVersionHomePath(agent, version));
+        if (inspection.available) {
+            return {
+                mode: 'native',
+                agent,
+                version,
+                cwd: inspection.cwd,
+                reason: `origin ${agent}@${version} is installed, healthy, and owns the indexed transcript`,
+            };
+        }
         return {
-            mode: 'native',
+            mode: 'continue',
             agent,
             version,
-            reason: `origin ${agent}@${version} is installed and healthy`,
+            reason: `${inspection.reason}; continuing with healthy ${agent}@${version}`,
         };
     }
     return {

package/dist/lib/session/remote-list.d.ts

@@ -2,20 +2,12 @@ import { type DeviceProfile } from '../devices/registry.js';
 import { type RemoteAgentsJsonParseResult } from '../remote-agents-json.js';
 import type { SessionMeta } from './types.js';
 import { type ToolProgramCountEnvelope, type ToolSearchEnvelope } from './tool-index.js';
-export declare const REMOTE_STDOUT_MAX_BYTES: number;
+export { REMOTE_STDOUT_MAX_BYTES, RemoteUtf8Accumulator } from '../ssh-exec.js';
 export declare const REMOTE_TOOL_AGGREGATE_MAX_BYTES: number;
 export interface RemoteToolByteBudget {
     remainingBytes: number;
     exhausted: boolean;
 }
-/** Preserve UTF-8 code points when SSH splits them across stdout chunks. */
-export declare class RemoteUtf8Accumulator {
-    private readonly decoder;
-    private value;
-    write(chunk: Buffer): void;
-    end(): string;
-    current(): string;
-}
 /** Claim received bytes against one fleet-query budget before retaining them. */
 export declare function consumeRemoteToolByteBudget(budget: RemoteToolByteBudget, bytes: number): boolean;
 /** Charge sanitized, machine-stamped evidence because redaction may expand it. */
@@ -130,7 +122,16 @@ export declare function resolvePeerTarget(machine: string): Promise<{
  * not via a local `--host` hop, which would discover locally and dead-end for a
  * session that exists only on the peer. Resolves 'no-target' when the machine
  * isn't a dialable registered device; the caller surfaces a clear message.
+ *
+ * `opts.env` adds variables to the remote command. It deliberately does NOT
+ * carry `AGENTS_FLEET_REMOTE` the way the `--host` passthrough does: that marker
+ * gates consent-sensitive actions on the far side
+ * (lib/browser/remote-control.ts), and a resumed agent is a long-lived session
+ * that would inherit it for its whole life — `agents browser start` inside it
+ * would then be refused as a cross-machine drive. A one-shot `--host` command
+ * can carry the marker; a session cannot.
  */
 export declare function runOnPeer(args: string[], machine: string, opts?: {
     tty?: boolean;
+    env?: Record<string, string>;
 }): Promise<'ok' | 'no-target'>;

package/dist/lib/session/remote-list.js

@@ -14,13 +14,12 @@
  * never fatal — one asleep laptop must not blank the list.
  */
 import { spawn } from 'child_process';
-import { StringDecoder } from 'string_decoder';
 import chalk from 'chalk';
-import { SSH_OPTS, controlOpts, assertValidSshTarget, shellQuote } from '../ssh-exec.js';
+import { SSH_OPTS, controlOpts, assertValidSshTarget, shellQuote, REMOTE_STDOUT_MAX_BYTES, RemoteUtf8Accumulator, } from '../ssh-exec.js';
 import { sshTargetFor } from '../devices/connect.js';
 import { resolveExplicitTargetSet } from '../devices/resolve-target.js';
 import { loadDevices, isControlDevice, isDialableDevice } from '../devices/registry.js';
-import { remoteShellFor, buildWindowsAgentsCommand } from '../hosts/remote-cmd.js';
+import { remoteShellFor, buildWindowsAgentsCommand, stripClixml } from '../hosts/remote-cmd.js';
 import { gatherRemoteAgentsJson } from '../remote-agents-json.js';
 import { machineId, normalizeHost } from './sync/config.js';
 import { NO_FANOUT_ENV } from './remote-active.js';
@@ -30,23 +29,12 @@ import { mapBounded } from '../concurrency.js';
 import { TOOL_QUERY_MAX_CLAUSE_BYTES, TOOL_QUERY_MAX_CALL_ROWS, TOOL_QUERY_MAX_CLAUSES, TOOL_QUERY_MAX_RESULT_SESSIONS, TOOL_QUERY_MAX_SERIALIZED_BYTES, serializedToolSearchEnvelopeBytes, } from './tool-index.js';
 import { TOOL_ERROR_OUTPUT_MAX_BYTES, TOOL_INPUT_MAX_BYTES, TOOL_SUCCESS_OUTPUT_MAX_BYTES, sanitizeToolEvidenceText, } from './tool-calls.js';
 const REMOTE_TOOL_TIMEOUT_MS = 60_000;
-export const REMOTE_STDOUT_MAX_BYTES = 16 * 1024 * 1024;
+// The per-peer stdout ceiling and the UTF-8-safe accumulator live in ssh-exec.ts
+// (the shared SSH transport both this reader and the top-level `remote-agents-json`
+// fan-out import), so the bound is defined once. Re-exported here for the existing
+// consumers/tests that reach them through this module.
+export { REMOTE_STDOUT_MAX_BYTES, RemoteUtf8Accumulator } from '../ssh-exec.js';
 export const REMOTE_TOOL_AGGREGATE_MAX_BYTES = TOOL_QUERY_MAX_SERIALIZED_BYTES;
-/** Preserve UTF-8 code points when SSH splits them across stdout chunks. */
-export class RemoteUtf8Accumulator {
-    decoder = new StringDecoder('utf8');
-    value = '';
-    write(chunk) {
-        this.value += this.decoder.write(chunk);
-    }
-    end() {
-        this.value += this.decoder.end();
-        return this.value;
-    }
-    current() {
-        return this.value;
-    }
-}
 /** Claim received bytes against one fleet-query budget before retaining them. */
 export function consumeRemoteToolByteBudget(budget, bytes) {
     if (budget.exhausted || bytes > budget.remainingBytes) {
@@ -91,7 +79,7 @@ export function remoteListCommand(forwardedArgs, os) {
 export function parseRemoteList(stdout, machine) {
     let parsed;
     try {
-        parsed = JSON.parse(stdout);
+        parsed = JSON.parse(stripClixml(stdout));
     }
     catch {
         return [];
@@ -117,7 +105,7 @@ function isSafeResolverRow(value) {
 export function parseRemoteListPayload(stdout, machine, safeResolver = false) {
     let parsed;
     try {
-        parsed = JSON.parse(stdout);
+        parsed = JSON.parse(stripClixml(stdout));
     }
     catch {
         return { items: [], valid: false };
@@ -375,6 +363,10 @@ function parseRemoteToolSession(value, machine) {
     };
 }
 export function parseRemoteToolSearch(stdout, machine, expectedClauses) {
+    // The fleet tool-search fan-out reads a raw sshCapture (not the stripped
+    // gatherRemoteAgentsJson wrapper), so a Windows peer's PowerShell CLIXML banner
+    // must be removed here too or the box reads as "no envelope" (RUSH-2286).
+    stdout = stripClixml(stdout);
     if (Buffer.byteLength(stdout) > REMOTE_STDOUT_MAX_BYTES)
         return undefined;
     try {
@@ -540,6 +532,14 @@ export async function resolvePeerTarget(machine) {
  * not via a local `--host` hop, which would discover locally and dead-end for a
  * session that exists only on the peer. Resolves 'no-target' when the machine
  * isn't a dialable registered device; the caller surfaces a clear message.
+ *
+ * `opts.env` adds variables to the remote command. It deliberately does NOT
+ * carry `AGENTS_FLEET_REMOTE` the way the `--host` passthrough does: that marker
+ * gates consent-sensitive actions on the far side
+ * (lib/browser/remote-control.ts), and a resumed agent is a long-lived session
+ * that would inherit it for its whole life — `agents browser start` inside it
+ * would then be refused as a cross-machine drive. A one-shot `--host` command
+ * can carry the marker; a session cannot.
  */
 export async function runOnPeer(args, machine, opts = {}) {
     const peer = await resolvePeerTarget(machine);
@@ -547,9 +547,11 @@ export async function runOnPeer(args, machine, opts = {}) {
         return 'no-target';
     assertValidSshTarget(peer.target); // registry-sourced, but validate like the fan-out does
     const cols = terminalWidth();
+    const env = { ...(cols > 0 ? { COLUMNS: String(cols) } : {}), ...opts.env };
+    const assignments = Object.entries(env).map(([k, v]) => `${k}=${shellQuote(v)}`);
     const remoteCmd = remoteShellFor(peer.os) === 'powershell'
-        ? buildWindowsAgentsCommand({ args, env: cols > 0 ? { COLUMNS: String(cols) } : undefined })
-        : `bash -lc ${shellQuote((cols > 0 ? [`COLUMNS=${cols}`] : []).concat(['agents', ...args].map(shellQuote)).join(' '))}`;
+        ? buildWindowsAgentsCommand({ args, env: assignments.length ? env : undefined })
+        : `bash -lc ${shellQuote(assignments.concat(['agents', ...args].map(shellQuote)).join(' '))}`;
     const sshArgs = [...SSH_OPTS, ...controlOpts()];
     if (opts.tty)
         sshArgs.push('-tt'); // force a PTY so the resumed agent is interactive

package/dist/lib/session/resume-owner.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Where a session may be resumed — the one place that answers "does this
+ * transcript belong to another machine?" and, when it does, runs the resume
+ * THERE instead of here.
+ *
+ * A session's agent state lives on the box that produced it: the harness keeps
+ * its own conversation store under that machine's home, and `machine` on a
+ * SessionMeta records where the transcript originated (see session/types.ts).
+ * A row can reach this box two ways and BOTH are remote-owned:
+ *
+ *  - a **synced mirror** — locally readable at `backups/<agent>/<machine>/…`,
+ *    which is exactly why the old code could not tell: the transcript file is
+ *    right there, so nothing failed until the harness was asked to resume a
+ *    conversation it has never seen;
+ *  - a **live fan-out row** (`_remote`), whose `filePath` is on the peer's disk.
+ *
+ * Resuming either one locally starts the harness against state it does not
+ * have. Before RUSH-2022 that happened silently — `sessions-resume.ts` even fell
+ * back to `process.cwd()` when the recorded cwd did not exist locally, so a
+ * remote session resumed in whatever directory the user happened to be in.
+ *
+ * Callers act on the answer differently, and the difference is deliberate:
+ * `agents resume` and `agents sessions attach` HOP to the owner over SSH, while
+ * `resumeSessionInPlace` — the local takeover every routed caller reaches only
+ * after deciding — REFUSES. The batch `sessions resume` needs no check of its
+ * own: each of its tabs runs the canonical `agents resume <id>`
+ * (lib/session/resume-command.ts), which routes itself.
+ */
+import type { SessionMeta } from './types.js';
+/**
+ * Set on the SSH hop that sends a resume to its owning device: the far side must
+ * run it, never route again.
+ *
+ * An env var rather than a flag, deliberately. The fleet is mixed-version — a
+ * peer on the released CLI would die on an unknown `--here` with
+ * `error: unknown option '--here'`, breaking the very hop this feature adds. An
+ * unrecognized exported variable is inert on every version, so routing works
+ * against old and new peers alike. The far side deletes it after reading
+ * ({@link consumeResumePinned}) so it cannot leak into the agent's own children.
+ */
+export declare const RESUME_PINNED_ENV = "AGENTS_RESUME_PINNED";
+/**
+ * Whether this process was handed a resume by its owner-routing hop — read once,
+ * then cleared so a nested `agents resume` inside the running agent still routes
+ * normally.
+ */
+export declare function consumeResumePinned(): boolean;
+/**
+ * The peer that owns `session`'s state, or `undefined` when this machine does.
+ *
+ * Undefined is also the answer for an untagged row (`machine` unset — a session
+ * obtained outside `discoverSessions`): there is nothing to route to, so the
+ * caller keeps the local behaviour rather than inventing a target.
+ */
+export declare function sessionOwnerDevice(session: Pick<SessionMeta, 'machine'>): string | undefined;

package/dist/lib/session/resume-owner.js

@@ -0,0 +1,69 @@
+/**
+ * Where a session may be resumed — the one place that answers "does this
+ * transcript belong to another machine?" and, when it does, runs the resume
+ * THERE instead of here.
+ *
+ * A session's agent state lives on the box that produced it: the harness keeps
+ * its own conversation store under that machine's home, and `machine` on a
+ * SessionMeta records where the transcript originated (see session/types.ts).
+ * A row can reach this box two ways and BOTH are remote-owned:
+ *
+ *  - a **synced mirror** — locally readable at `backups/<agent>/<machine>/…`,
+ *    which is exactly why the old code could not tell: the transcript file is
+ *    right there, so nothing failed until the harness was asked to resume a
+ *    conversation it has never seen;
+ *  - a **live fan-out row** (`_remote`), whose `filePath` is on the peer's disk.
+ *
+ * Resuming either one locally starts the harness against state it does not
+ * have. Before RUSH-2022 that happened silently — `sessions-resume.ts` even fell
+ * back to `process.cwd()` when the recorded cwd did not exist locally, so a
+ * remote session resumed in whatever directory the user happened to be in.
+ *
+ * Callers act on the answer differently, and the difference is deliberate:
+ * `agents resume` and `agents sessions attach` HOP to the owner over SSH, while
+ * `resumeSessionInPlace` — the local takeover every routed caller reaches only
+ * after deciding — REFUSES. The batch `sessions resume` needs no check of its
+ * own: each of its tabs runs the canonical `agents resume <id>`
+ * (lib/session/resume-command.ts), which routes itself.
+ */
+import { isSelfHost } from '../devices/self-host.js';
+/**
+ * Set on the SSH hop that sends a resume to its owning device: the far side must
+ * run it, never route again.
+ *
+ * An env var rather than a flag, deliberately. The fleet is mixed-version — a
+ * peer on the released CLI would die on an unknown `--here` with
+ * `error: unknown option '--here'`, breaking the very hop this feature adds. An
+ * unrecognized exported variable is inert on every version, so routing works
+ * against old and new peers alike. The far side deletes it after reading
+ * ({@link consumeResumePinned}) so it cannot leak into the agent's own children.
+ */
+export const RESUME_PINNED_ENV = 'AGENTS_RESUME_PINNED';
+/**
+ * Whether this process was handed a resume by its owner-routing hop — read once,
+ * then cleared so a nested `agents resume` inside the running agent still routes
+ * normally.
+ */
+export function consumeResumePinned() {
+    const pinned = process.env[RESUME_PINNED_ENV] === '1';
+    delete process.env[RESUME_PINNED_ENV];
+    return pinned;
+}
+/**
+ * The peer that owns `session`'s state, or `undefined` when this machine does.
+ *
+ * Undefined is also the answer for an untagged row (`machine` unset — a session
+ * obtained outside `discoverSessions`): there is nothing to route to, so the
+ * caller keeps the local behaviour rather than inventing a target.
+ */
+export function sessionOwnerDevice(session) {
+    const owner = session.machine?.trim();
+    if (!owner)
+        return undefined;
+    // `isSelfHost` matches every identity this box answers to — `machineId()`
+    // itself, the tailnet dnsName and its short form, loopback (devices/
+    // self-host.ts `selfAliases`) — so a mirror tagged with this machine's tailnet
+    // name is local, not a peer (cf. RUSH-2114). No separate `machineId()`
+    // comparison: it is one of those aliases.
+    return isSelfHost(owner) ? undefined : owner;
+}

package/dist/lib/session/team-filter.d.ts

@@ -51,3 +51,68 @@ export interface FilterResult {
  * excluded and counted in `hiddenCount`.
  */
 export declare function filterTeamSessions(sessions: SessionMeta[], showTeams: boolean): FilterResult;
+/**
+ * Whether a team-origin session is a real `agents teams` teammate or a bare SDK
+ * spawn with no teammate record. The two share the `sdk-cli` entrypoint that
+ * sets `isTeamOrigin`, so they are told apart by whether a `meta.json` teammate
+ * record backs the origin ({@link TeamOrigin.source} === `'meta'`).
+ *
+ * `source` is newer than the rest of {@link TeamOrigin}, so a row that arrived
+ * from a pre-`source` peer over the `--host` fan-out carries none. There the
+ * meta-only fields settle it: the entrypoint fallback is a bare `{ handle }`, so
+ * any `team` / `mode` / `parentSessionId` / `startedAt` means a real teammate
+ * record produced it — otherwise a genuine teammate from an unupgraded peer
+ * would be misfiled into the no-team bucket, the exact conflation this splits.
+ */
+export declare function teamRowKind(origin: TeamOrigin | undefined): 'teammate' | 'subagent';
+/** A team-origin session with its resolved {@link TeamOrigin} guaranteed present. */
+type TeamSession = SessionMeta & {
+    teamOrigin: TeamOrigin;
+};
+/**
+ * Key/label for the residual bucket — sessions flagged `isTeamOrigin` (an SDK /
+ * `sdk-cli` entrypoint) that carry no teammate `meta.json`. In practice this is
+ * headless `agents run` spawns and teammates whose team record aged out; a true
+ * `Task` sub-agent's transcript is never indexed, so it cannot land here. Named
+ * "(no team)" rather than "(sub-agents)" so the label matches what it holds.
+ */
+export declare const NO_TEAM_GROUP_KEY = "(no team)";
+/** Key/label for teammates whose record carries no team name (`task_name`). */
+export declare const UNNAMED_TEAM_KEY = "(unnamed team)";
+/** One team's sessions, grouped for the `agents sessions --teams` view. */
+export interface TeamSessionGroup {
+    /**
+     * The grouping key: the team name, {@link UNNAMED_TEAM_KEY} for teammates that
+     * carry no `task_name`, or {@link NO_TEAM_GROUP_KEY} for the residual bucket.
+     */
+    key: string;
+    /** A named team of `agents teams` teammates vs the catch-all no-team bucket. */
+    kind: 'team' | 'noTeam';
+    /** Team name when this is a named team, else undefined. */
+    team?: string;
+    /**
+     * The orchestrator session id that spawned this team (`parent_session_id`),
+     * when every teammate agrees on one. Undefined for the no-team bucket, an
+     * unparented team, or a group whose teammates disagree.
+     */
+    spawnerSessionId?: string;
+    /** The team's rows, newest-active first. */
+    sessions: TeamSession[];
+    /** Most-recent activity across the group, for ordering groups. */
+    maxTs: string;
+    /** Earliest spawn time across the group (`started_at`, else `timestamp`). */
+    firstSpawnTs: string;
+}
+/**
+ * Group team-origin sessions for the `--teams` view: each named team becomes one
+ * group of its teammates, and every bare SDK spawn with no teammate record falls
+ * into a single trailing {@link NO_TEAM_GROUP_KEY} bucket, so a real teammate and
+ * a bare spawn are never shown as the same thing.
+ *
+ * Only rows with a resolved {@link TeamOrigin} participate (the caller has
+ * already run {@link filterTeamSessions}); any non-team session is ignored.
+ * Groups are ordered newest-active first; sub-agents always sort last. Pure —
+ * unit-tested.
+ */
+export declare function groupSessionsByTeam(sessions: SessionMeta[]): TeamSessionGroup[];
+export {};

package/dist/lib/session/team-filter.js

@@ -35,7 +35,7 @@ export function classifyTeamSession(session) {
     if (origin)
         return origin;
     if (session.isTeamOrigin) {
-        return { handle: session.id.slice(0, 8) };
+        return { handle: session.id.slice(0, 8), source: 'entrypoint' };
     }
     return null;
 }
@@ -54,12 +54,16 @@ function readTeamOrigin(metaPath, agentId) {
                 mode: str(meta.mode),
                 team: str(meta.task_name),
                 parentSessionId: str(meta.parent_session_id),
+                startedAt: str(meta.started_at),
+                source: 'meta',
             },
             sessionId: str(meta.remote_session_id),
         };
     }
     catch {
-        return { origin: { handle: agentId.slice(0, 8) } };
+        // An unreadable meta.json still lives under the teams agents dir, so the
+        // session IS a teammate — mark the source accordingly, just without fields.
+        return { origin: { handle: agentId.slice(0, 8), source: 'meta' } };
     }
 }
 /**
@@ -133,7 +137,8 @@ export function enrichTeamOrigins(sessions) {
         // here would find no local record and downgrade a named teammate to a bare id.
         if (session.teamOrigin)
             return session;
-        const origin = index.get(session.id) ?? (session.isTeamOrigin ? { handle: session.id.slice(0, 8) } : null);
+        const origin = index.get(session.id) ??
+            (session.isTeamOrigin ? { handle: session.id.slice(0, 8), source: 'entrypoint' } : null);
         return origin ? { ...session, teamOrigin: origin } : session;
     });
 }
@@ -162,3 +167,93 @@ export function filterTeamSessions(sessions, showTeams) {
     }
     return { visible, hiddenCount };
 }
+/**
+ * Whether a team-origin session is a real `agents teams` teammate or a bare SDK
+ * spawn with no teammate record. The two share the `sdk-cli` entrypoint that
+ * sets `isTeamOrigin`, so they are told apart by whether a `meta.json` teammate
+ * record backs the origin ({@link TeamOrigin.source} === `'meta'`).
+ *
+ * `source` is newer than the rest of {@link TeamOrigin}, so a row that arrived
+ * from a pre-`source` peer over the `--host` fan-out carries none. There the
+ * meta-only fields settle it: the entrypoint fallback is a bare `{ handle }`, so
+ * any `team` / `mode` / `parentSessionId` / `startedAt` means a real teammate
+ * record produced it — otherwise a genuine teammate from an unupgraded peer
+ * would be misfiled into the no-team bucket, the exact conflation this splits.
+ */
+export function teamRowKind(origin) {
+    if (!origin)
+        return 'subagent';
+    if (origin.source === 'meta')
+        return 'teammate';
+    if (origin.source === 'entrypoint')
+        return 'subagent';
+    return origin.team || origin.mode || origin.parentSessionId || origin.startedAt
+        ? 'teammate'
+        : 'subagent';
+}
+/**
+ * Key/label for the residual bucket — sessions flagged `isTeamOrigin` (an SDK /
+ * `sdk-cli` entrypoint) that carry no teammate `meta.json`. In practice this is
+ * headless `agents run` spawns and teammates whose team record aged out; a true
+ * `Task` sub-agent's transcript is never indexed, so it cannot land here. Named
+ * "(no team)" rather than "(sub-agents)" so the label matches what it holds.
+ */
+export const NO_TEAM_GROUP_KEY = '(no team)';
+/** Key/label for teammates whose record carries no team name (`task_name`). */
+export const UNNAMED_TEAM_KEY = '(unnamed team)';
+/** Recency signal for a row: last activity, else the creation timestamp. */
+function rowTs(s) {
+    return s.lastActivity ?? s.timestamp;
+}
+/** Spawn time for a row: the meta `started_at`, else the transcript creation time. */
+function spawnTs(s) {
+    return s.teamOrigin.startedAt ?? s.timestamp;
+}
+/**
+ * Group team-origin sessions for the `--teams` view: each named team becomes one
+ * group of its teammates, and every bare SDK spawn with no teammate record falls
+ * into a single trailing {@link NO_TEAM_GROUP_KEY} bucket, so a real teammate and
+ * a bare spawn are never shown as the same thing.
+ *
+ * Only rows with a resolved {@link TeamOrigin} participate (the caller has
+ * already run {@link filterTeamSessions}); any non-team session is ignored.
+ * Groups are ordered newest-active first; sub-agents always sort last. Pure —
+ * unit-tested.
+ */
+export function groupSessionsByTeam(sessions) {
+    const byKey = new Map();
+    for (const s of sessions) {
+        if (!s.teamOrigin)
+            continue;
+        const kind = teamRowKind(s.teamOrigin);
+        const key = kind === 'subagent'
+            ? NO_TEAM_GROUP_KEY
+            : safeTeamText(s.teamOrigin.team) ?? UNNAMED_TEAM_KEY;
+        const ts = s;
+        (byKey.get(key) ?? byKey.set(key, []).get(key)).push(ts);
+    }
+    const groups = [];
+    for (const [key, rows] of byKey) {
+        rows.sort((a, b) => (rowTs(a) < rowTs(b) ? 1 : rowTs(a) > rowTs(b) ? -1 : 0));
+        const kind = key === NO_TEAM_GROUP_KEY ? 'noTeam' : 'team';
+        // A single agreed-on spawner names the orchestrator for the whole team; a
+        // mix (or none) leaves it unset rather than claiming a wrong parent.
+        const parents = new Set(rows.map((r) => r.teamOrigin.parentSessionId).filter((p) => !!p));
+        groups.push({
+            key,
+            kind,
+            team: kind === 'team' && key !== UNNAMED_TEAM_KEY ? key : undefined,
+            spawnerSessionId: parents.size === 1 ? [...parents][0] : undefined,
+            sessions: rows,
+            maxTs: rowTs(rows[0]),
+            firstSpawnTs: rows.map(spawnTs).sort()[0],
+        });
+    }
+    // Newest-active team first; the no-team bucket always sinks to the bottom.
+    groups.sort((a, b) => {
+        if (a.kind !== b.kind)
+            return a.kind === 'noTeam' ? 1 : -1;
+        return a.maxTs < b.maxTs ? 1 : a.maxTs > b.maxTs ? -1 : a.key.localeCompare(b.key);
+    });
+    return groups;
+}

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

@@ -117,6 +117,24 @@ export interface TeamOrigin {
      * meta dir has aged past the teams cleanup window.
      */
     parentSessionId?: string;
+    /**
+     * Spawn time (`started_at` in the teammate meta.json) — when `agents teams`
+     * launched this teammate. Distinct from the session's own `timestamp` (first
+     * transcript line), and present even before the harness writes a transcript.
+     * Absent for the entrypoint-only fallback (no meta record).
+     */
+    startedAt?: string;
+    /**
+     * How this origin was established, which is what separates a real
+     * `agents teams` teammate from a plain SDK sub-agent (a `Task` / `Agent()`
+     * spawn). Both carry the `sdk-cli` entrypoint that sets `isTeamOrigin`, so the
+     * entrypoint flag alone cannot tell them apart — only a teammate has a
+     * `meta.json` under the teams agents dir.
+     *   - `'meta'`     — a teammate: read from its `meta.json` record.
+     *   - `'entrypoint'` — an SDK spawn with no team record (a sub-agent, or a
+     *                      teammate whose meta dir aged past the cleanup window).
+     */
+    source?: 'meta' | 'entrypoint';
 }
 /** Lightweight metadata for a discovered session, used in listings and pickers. */
 export interface SessionMeta {
@@ -144,8 +162,23 @@ export interface SessionMeta {
     tokenCount?: number;
     /** Real generated (output) tokens — excludes cache-read/-write context (issue: `agents output`). */
     outputTokens?: number;
+    /**
+     * Uncached input tokens, cache-read tokens, and cache-write (cache-creation)
+     * tokens — the burn split `agents output` reports, kept only for harnesses that
+     * record a per-message cache split (Claude/Codex/Gemini/Droid). Undefined for
+     * harnesses that expose no split (RUSH-2287).
+     */
+    inputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
     /** Total USD cost, computed at scan time from per-model token usage (issue #323). */
     costUsd?: number;
+    /**
+     * USD cost priced as if caching were off — cache read/write billed at the full
+     * input rate. Backs `agents output --pricing no-cache` (RUSH-2287). Undefined
+     * when the harness records no cache split (then no-cache == actual by definition).
+     */
+    costUsdNoCache?: number;
     /** Wall-clock duration in ms (lastTs − firstTs), persisted at scan time. */
     durationMs?: number;
     /** Underlying LLM model observed in the transcript, when the agent records one. */