@phnx-labs/agents-cli 1.20.86 → 1.20.87

package/CHANGELOG.md

@@ -1,5 +1,117 @@
 # Changelog
 
+## 1.20.87
+
+- **`agents devices enable|disable|prefer|unprefer <name>` control which machines
+  Factory auto-launches onto.** A *disabled* device is skipped by
+  `New <Agent>` and the balanced launch, but stays available through
+  `New <Agent> (Pick Host)`. A *preferred* device wins ties against otherwise
+  equivalent machines — worth about two running agents in the ranking, so a
+  preference never sends work to a box that is genuinely swamped. Every device
+  is enabled and unpreferred by default, and an unregistered name is now
+  rejected instead of writing a preference that matches nothing. Preferences
+  live in `~/.agents/.history/devices/auto-launch.json`, written by the CLI and
+  read by the extension. Source: `apps/cli/src/lib/devices/registry.ts`,
+  `apps/cli/src/commands/ssh.ts`, `apps/factory/src/core/deviceAutoLaunch.ts`,
+  `apps/factory/src/core/launchHost.ts`.
+
+- **Point-of-use friction events for `agents teams` failures.** The CLI's `die()`
+  chokepoints in `teams` now emit a structured `friction` event (`surface`,
+  `failureId`, `error`) before exiting, so the nightly factory-metrics routine can
+  rank recurring failures without re-parsing transcripts. A hidden
+  `agents _internal friction` recorder lets shell guard hooks (git-guard, rm-guard,
+  large-file-add-guard) self-report blocks into the same stream. Source:
+  `apps/cli/src/lib/events.ts`, `apps/cli/src/lib/format.ts`,
+  `apps/cli/src/commands/teams.ts`, `apps/cli/src/index.ts`.
+
+- **`agents view` no longer reports a working Claude install as "logged out".**
+  Claude's `signedIn` is `!!email` read from a version home's `.claude.json`
+  (`lib/agents.ts`), so a version that authenticates from an ambient
+  `CLAUDE_CODE_OAUTH_TOKEN` — no account ever written to that home — rendered
+  "(logged out — log in with: claude, then /login)" while every run against it
+  succeeded. On one fleet box five of seven versions read as locked out and all
+  of them answered a live prompt. Those now render "(no per-version login —
+  using ambient CLAUDE_CODE_OAUTH_TOKEN)", which is both accurate and the more
+  useful warning: an ambient token is ONE account, so balanced rotation across
+  those versions rotates nothing. Source: `apps/cli/src/lib/signin-badge.ts`,
+  `apps/cli/src/commands/view.ts`.
+
+- **Claude per-account run tokens.** `agents run` now injects the Claude setup token keyed to the selected version home's own account email, so balanced Claude rotation no longer inherits one ambient shared token across accounts. Source: `src/lib/exec.ts`.
+
+- **`agents sessions` now shows which session spawned which team.** The link
+  already existed on disk and was discarded twice. `SessionMeta.spawnedTeam` — the
+  team name read off the `agents teams create/add` command at scan time — had no
+  column in `sessions.db`, so the writer dropped it and no consumer had ever seen
+  a non-`undefined` value; a new `spawned_team` column (schema **v21**, which
+  forces one full rescan) persists it, and orchestrator rows now carry a green
+  `team:<name>` badge. Separately, `classifyTeamSession` was already opening each
+  teammate's `meta.json` and throwing away its `task_name` and
+  `parent_session_id`, so a teammate row could not name its team or point back at
+  its orchestrator; teammate rows now read `[<team>/<handle>]` and the preview
+  pane carries a `Team:` line from either end of the lineage. New `--in-team
+  <name>` (and a `t` hotkey in the browser) filters to one team's orchestrator
+  plus its teammates, `agents teams status --parent-session <id>` lists the
+  teammates a given session spawned, and `agents teams list` gains a `by <id>`
+  column. Source: `apps/cli/src/lib/session/db.ts`,
+  `apps/cli/src/lib/session/team-filter.ts`, `apps/cli/src/commands/sessions.ts`,
+  `apps/cli/src/commands/sessions-browser.ts`, `apps/cli/src/commands/teams.ts`.
+
+- **`agents sessions --device <box>` no longer opens an empty browser.** The
+  interactive one-host listing kept the browser's default this-repo scope, but
+  every row it fetches is the peer's and no peer cwd is under the local
+  `process.cwd()` — so the filter dropped all of them. A host scope now implies
+  all-directories (and the `p` hotkey is a no-op under one). Three more
+  scope bugs on the same path: `--device <this machine>` fanned out to the whole
+  tailnet, because `gatherRemoteList` reads the resulting empty peer list as "no
+  hosts given" and sweeps; `--local --device <box>` rendered a silent empty list
+  instead of reporting that the two flags ask for opposite things; and
+  `--device <box> --cloud` fell through to the cloud listing, which has no host
+  scope and silently ignored the device. An unreachable peer now says so in the
+  browser header — the fan-out's stderr note is repainted away by the full-screen
+  picker, so "that box is asleep" used to read as "no sessions match". Source:
+  `apps/cli/src/commands/sessions.ts`, `apps/cli/src/commands/sessions-browser.ts`,
+  `apps/cli/src/lib/session/remote-list.ts`.
+
+- **Teammate records are found by the session id they actually produced.** A
+  teammate's directory under `teams/agents/` is named for its *agent* id, but the
+  harness mints its own session id and the spawn records it separately as
+  `remote_session_id`. `classifyTeamSession` looked only under the directory
+  name, so most teammates were unreachable — on a live box, 14 of 16 records
+  resolved only via `remote_session_id` — and their rows could not name their
+  team however complete the record was. Both keys are now registered in one
+  index built per process, which also replaces the `existsSync` + `readFileSync`
+  the old path paid for every row in the pool. Source:
+  `apps/cli/src/lib/session/team-filter.ts`.
+
+- **`detectSpawnedTeam` no longer indexes prose or flag values as team names.**
+  Rendering the value exposed that it had been wrong for most of the rows that
+  had one: on a live index of 4627 sessions, 11 carried a team and 6 of those
+  read `2` or `t`. It matched documentation and echoed output rather than only
+  executed commands; its flag-skip used `\s` and so ran across a newline to
+  capture a word from the next line; and a value-taking flag did not swallow its
+  value, so `--device auto` left `auto` looking like the team name — which was
+  corrupting real detections, not just adding false ones. After the fix the same
+  index resolves ten teams, every one of them a real team name. Source:
+  `apps/cli/src/lib/session/state.ts`.
+
+- **`--in-team` returns a team's whole lineage, not the slice inside the default
+  window.** It filtered in memory after the query, so a team older than the
+  default top-50 / 30-day / current-directory scope came back empty with no
+  message — and a team's teammates run in their own worktrees, which the
+  directory scope hid. The flag now widens its own scope the way `--all` does. It
+  is also refused with `--active`, whose live rows carry no lineage to match on,
+  rather than being silently ignored. Source: `apps/cli/src/commands/sessions.ts`.
+
+- **The session preview pane sanitizes peer-supplied `plan` and directory
+  text.** A remote row's metadata is JSON the peer sent and `parseRemoteList`
+  hands over verbatim; `sanitizeMeta` covered `topic`/`label`/`cwd`/`todos` but
+  not these, so a terminal escape in another machine's plan text reached the TTY.
+  The remote preview also renders more of what already rides across the hop: the
+  checklist items, the directories the scan recorded, and a one-line plan summary
+  (never the full markdown blob). `directoriesTouched` now reads the real
+  `recentDirectoriesTouched` field instead of a `dirsTouched` that nothing in the
+  repo ever wrote. Source: `apps/cli/src/commands/sessions-picker.ts`.
+
 ## 1.20.86
 
 - **`agents sessions` now shows a Kimi session's todo list and its file-touching

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

@@ -24,11 +24,27 @@ export interface BrowserFilter {
     agent?: string;
     /** filter to one machine, or all — the `D` key / `--device`. */
     device?: string;
+    /** filter to one team's lineage, or all — the `T` key / `--in-team`. */
+    team?: string;
     /** this-repo subtree vs every directory — the `P` key / `--all`. */
     projectScope: 'repo' | 'all';
     /** time window (undefined = all time) — the `W` key / `--since`. */
     window?: string;
 }
+/**
+ * Complete a seed into the filter the picker actually runs on.
+ *
+ * Every optional field of {@link BrowserFilter} has to be named here, because the
+ * seed is copied field-by-field and an omission is silent: the field is optional,
+ * so the compiler says nothing and the browser just opens without that filter.
+ * `team` was dropped exactly this way, which made `--in-team` a no-op on the
+ * interactive path while the scope half of the same seed still applied — so the
+ * view opened wide and all-time and looked like the flag had worked.
+ *
+ * Exported so a test can assert the FILTER, not just the seed; testing the seed
+ * alone cannot see this class of bug.
+ */
+export declare function buildInitialFilter(initial: Partial<BrowserFilter>): BrowserFilter;
 /** Return the next value in `[undefined, ...options]`, wrapping. */
 export declare function cycle(current: string | undefined, options: string[]): string | undefined;
 export declare function cycleWindow(current: string | undefined): string | undefined;
@@ -74,6 +90,8 @@ export declare function bareBrowserSeed(opts: {
     agent?: string;
     all?: boolean;
     since?: string;
+    host?: string[];
+    inTeam?: string;
 }): Partial<BrowserFilter>;
 /**
  * A live session's stable row key: its session id when the agent reported one,

package/dist/commands/sessions-browser.js

@@ -11,13 +11,51 @@
  */
 import path from 'path';
 import { spawnSync } from 'child_process';
+import chalk from 'chalk';
 import { dynamicPicker } from '../lib/picker.js';
 import { isSessionTrackedAgent } from '../lib/session/types.js';
 import { discoverSessions } from '../lib/session/discover.js';
 import { gatherRemoteList } from '../lib/session/remote-list.js';
+import { enrichTeamOrigins, safeTeamText } from '../lib/session/team-filter.js';
 import { machineId, normalizeHost } from '../lib/session/sync/config.js';
 import { buildPreview } from './sessions-picker.js';
-import { formatPickerLabel, pickerColumnsFor, ticketLabel, mergeLocalFirst, gatherActiveSessions, liveHostLabel, LIVE_ROW_PREFIX, cleanPreview, handlePickedSession, shouldIncludeLocal, remoteHostsToDial, } from './sessions.js';
+import { formatPickerLabel, pickerColumnsFor, ticketLabel, mergeLocalFirst, gatherActiveSessions, liveHostLabel, LIVE_ROW_PREFIX, cleanPreview, handlePickedSession, shouldIncludeLocal, remoteHostsToDial, matchesTeam, } from './sessions.js';
+/**
+ * Complete a seed into the filter the picker actually runs on.
+ *
+ * Every optional field of {@link BrowserFilter} has to be named here, because the
+ * seed is copied field-by-field and an omission is silent: the field is optional,
+ * so the compiler says nothing and the browser just opens without that filter.
+ * `team` was dropped exactly this way, which made `--in-team` a no-op on the
+ * interactive path while the scope half of the same seed still applied — so the
+ * view opened wide and all-time and looked like the flag had worked.
+ *
+ * Exported so a test can assert the FILTER, not just the seed; testing the seed
+ * alone cannot see this class of bug.
+ */
+export function buildInitialFilter(initial) {
+    return {
+        running: initial.running ?? false,
+        teams: initial.teams ?? false,
+        agent: initial.agent,
+        device: initial.device,
+        team: initial.team,
+        projectScope: initial.projectScope ?? 'repo',
+        window: 'window' in initial ? initial.window : '30d',
+    };
+}
+/** Cache key for the transcript pool: every filter that changes what is FETCHED
+ *  (window, team-origin inclusion, and the team filter's deeper limit) — not the
+ *  ones applied in memory afterwards. */
+function poolCacheKey(f) {
+    // The team filter contributes only whether it is SET, not which team: any team
+    // fetches the same deep pool and is then narrowed in memory. Keying on the name
+    // would make `t` the one hotkey that re-fans-out the fleet on every step of the
+    // cycle, at up to REMOTE_TIMEOUT_MS per unreachable peer.
+    return `${f.window ?? 'all'}|${f.teams}|${f.team ? 'team' : ''}`;
+}
+/** Pool size when a team filter is active; one team's rows can sit anywhere. */
+const WHOLE_TEAM_POOL_LIMIT = 5000;
 /** Ordered window cycle for the `W` key. `undefined` = all time. */
 const WINDOW_CYCLE = [undefined, '1d', '7d', '30d'];
 /** Return the next value in `[undefined, ...options]`, wrapping. */
@@ -73,6 +111,8 @@ export function browserFilterToArgv(f, query = '') {
         a.push('-a', f.agent);
     if (f.device)
         a.push('--device', f.device);
+    if (f.team)
+        a.push('--in-team', f.team);
     if (f.projectScope === 'all')
         a.push('--all');
     if (f.window)
@@ -116,12 +156,28 @@ export function activeBrowserSeed(opts) {
  * `-a`/`--device` still narrow their axis.
  */
 export function bareBrowserSeed(opts) {
+    // An explicit --device scopes the pool to a peer, whose cwds live under that
+    // machine's home — none of them can be under OUR process.cwd(), so the default
+    // 'repo' scope would filter every fetched row away and render an empty list.
+    // A host scope therefore implies all-directories, exactly as --all does.
+    const scoped = (opts.host?.length ?? 0) > 0;
+    // --in-team asks for ONE team's lineage, and a team's teammates run in their own
+    // `.agents/worktrees/<slug>/` — a different cwd from ours — while the team itself
+    // may be older than the default window. Both defaults would hide exactly the rows
+    // the flag exists to surface, so it widens the scope the way --all does. The flag
+    // path does this too (sessions.ts `wantsWholeTeam`); the browser is the one a
+    // human actually reaches, so it must not be the one that stays narrow.
+    const wholeTeam = !!opts.inTeam;
     return {
         teams: !!opts.teams,
         agent: opts.agent,
+        // The filter carries one device; seed it only when the scope names exactly
+        // one, so a two-device scope isn't narrowed to the first of them.
+        device: opts.host?.length === 1 ? normalizeDeviceSeed(opts.host[0]) : undefined,
+        team: opts.inTeam,
         // --all maxes every non-status filter: all dirs AND all-time. --since wins.
-        projectScope: opts.all ? 'all' : 'repo',
-        window: opts.since ?? (opts.all ? undefined : '30d'),
+        projectScope: opts.all || scoped || wholeTeam ? 'all' : 'repo',
+        window: opts.since ?? (opts.all || wholeTeam ? undefined : '30d'),
     };
 }
 /** Copy text to the OS clipboard (best-effort; silently no-ops if unavailable). */
@@ -154,6 +210,7 @@ function copyToClipboard(text) {
  * not add" contract instead of always sweeping the whole fleet. */
 async function fetchRawPool(f, self, local, hosts) {
     const since = f.window;
+    let unreachable = [];
     // Local pool: wide (every directory) — device/agent/project are applied in
     // memory so a hotkey toggle is instant and doesn't re-hit the disk. Skipped
     // when an explicit host scope excludes this machine.
@@ -163,7 +220,10 @@ async function fetchRawPool(f, self, local, hosts) {
             cwd: process.cwd(),
             since,
             excludeTeamOrigin: !f.teams,
-            limit: 500,
+            // A team filter reaches back past the usual browse window, so the pool it
+            // draws from has to as well — otherwise the newest 500 rows decide which
+            // teams exist.
+            limit: f.team ? WHOLE_TEAM_POOL_LIMIT : 500,
             sortBy: 'timestamp',
         })
         : [];
@@ -171,22 +231,40 @@ async function fetchRawPool(f, self, local, hosts) {
     // Skipped under --local. An explicit --host/--device scopes exactly which peers
     // are dialed (undefined = sweep every online device). Best-effort — a fan-out
     // failure leaves the local list intact.
-    if (!local) {
+    const remoteHosts = remoteHostsToDial(hosts, self);
+    // An explicit scope naming only this machine leaves nothing remote to dial.
+    // gatherRemoteList reads `[]` as "no hosts given" and falls through to the
+    // whole-fleet sweep, so `--device <self>` would dial every online box — the
+    // exact opposite of the flag's scope-not-add contract. Skip the fan-out here,
+    // the same way gatherActiveSessions does for --active.
+    const dialPeers = !local && (!hosts?.length || (remoteHosts && remoteHosts.length > 0));
+    if (dialPeers) {
         try {
-            const forwarded = ['sessions', '--all', '--json', '--limit', '500'];
+            // The peer's cap has to match the local one, or a team filter widens only
+            // this machine's half of the pool and a peer's older rows stay invisible —
+            // the same bug one hop out. A numeric --limit is forwarded rather than
+            // --in-team itself, which a peer on an older build would reject as an
+            // unknown option and fail the whole fan-out.
+            const forwarded = ['sessions', '--all', '--json', '--limit', String(f.team ? WHOLE_TEAM_POOL_LIMIT : 500)];
             if (since)
                 forwarded.push('--since', since);
             if (f.teams)
                 forwarded.push('--teams');
-            const { sessions: remote } = await gatherRemoteList(forwarded, remoteHostsToDial(hosts, self));
-            if (remote.length > 0)
-                rows = mergeLocalFirst([...rows, ...remote], self);
+            const remoteResult = await gatherRemoteList(forwarded, remoteHosts);
+            unreachable = remoteResult.unreachable;
+            if (remoteResult.sessions.length > 0)
+                rows = mergeLocalFirst([...rows, ...remoteResult.sessions], self);
         }
         catch {
             // enrichment, never a hard dependency
         }
     }
-    return { key: `${since ?? 'all'}|${f.teams}`, rows };
+    // Team rows are anonymous without their meta.json (team name, handle, the
+    // orchestrator that spawned them). Only pay for that read when team rows are
+    // actually in the pool — with `c` off they were excluded at the query.
+    if (f.teams)
+        rows = enrichTeamOrigins(rows);
+    return { key: poolCacheKey(f), rows, unreachable };
 }
 /**
  * A live session's stable row key: its session id when the agent reported one,
@@ -288,6 +366,8 @@ function applyFilters(rows, live, f, self) {
         out = out.filter((r) => r.agent === f.agent);
     if (f.device)
         out = out.filter((r) => (r.machine ?? self) === f.device);
+    if (f.team)
+        out = out.filter((r) => matchesTeam(r, f.team));
     if (f.projectScope === 'repo') {
         const cwd = process.cwd();
         out = out.filter((r) => !!r.cwd && (r.cwd === cwd || r.cwd.startsWith(cwd + '/')));
@@ -310,6 +390,7 @@ function headerFor(f) {
     const bits = [
         `device:${f.device ?? 'all'}`,
         `agent:${f.agent ?? 'all'}`,
+        `team:${f.team ?? 'all'}`,
         f.projectScope === 'repo' ? 'this repo' : 'all dirs',
         `window:${f.window ?? 'all'}`,
     ];
@@ -323,7 +404,7 @@ function helpFor(_f, mode) {
     if (mode === 'search') {
         return 'type to filter · ↑↓ navigate · esc exit search · ⏎ resume';
     }
-    return 's search · r running · c teams · a agent · d device · p project · w window · tab preview · y copy-cmd · ⏎ resume · esc quit';
+    return 's search · r running · c teams · t team · a agent · d device · p project · w window · tab preview · y copy-cmd · ⏎ resume · esc quit';
 }
 /**
  * Launch the interactive session browser. `initial` seeds the filter (e.g.
@@ -337,10 +418,17 @@ export async function runSessionBrowser(initial = {}, opts = {}) {
     // Updated after each load so the A/D cycles range over what's actually present.
     let agentsInPool = [];
     let devicesInPool = [];
+    let teamsInPool = [];
     let cols = {};
-    // Cache the transcript fetch, keyed by (window, teams); agent/device/project/
-    // running are applied in memory so their hotkeys don't re-fan-out the fleet.
+    // Cache the transcript fetch, keyed by poolCacheKey (everything that changes
+    // what is FETCHED); agent/device/project/running are applied in memory so their
+    // hotkeys don't re-fan-out the fleet.
     let rawCache = null;
+    // Peers that didn't answer the last fan-out. The fan-out's own note goes to
+    // stderr, which the full-screen picker repaints over — so it is surfaced in
+    // the header instead, where "that box is asleep" stays distinguishable from
+    // "that box has nothing matching".
+    let unreachable = [];
     // The live index is slow (a full ps/tmux scan) and only the running filter
     // needs it — fetch it once, lazily, the first time running is toggled on.
     let liveCache = null;
@@ -350,17 +438,13 @@ export async function runSessionBrowser(initial = {}, opts = {}) {
     // caches) is a side channel it can't see — so a stale load must never commit
     // it. We compute into locals and only write the shared state as the latest load.
     let loadGen = 0;
-    const initialFilter = {
-        running: initial.running ?? false,
-        teams: initial.teams ?? false,
-        agent: initial.agent,
-        device: initial.device,
-        projectScope: initial.projectScope ?? 'repo',
-        window: 'window' in initial ? initial.window : '30d',
-    };
+    const initialFilter = buildInitialFilter(initial);
     const load = async (f) => {
         const myGen = ++loadGen;
-        const key = `${f.window ?? 'all'}|${f.teams}`;
+        // f.team decides the fetch limit, so it belongs in the key — otherwise arriving
+        // via `t` reuses a 500-row pool while --in-team fetched 5000, and the cycle can
+        // only offer the teams that happened to be in whichever pool was built first.
+        const key = poolCacheKey(f);
         let pool = rawCache && rawCache.key === key ? rawCache : null;
         if (!pool) {
             const fetched = await fetchRawPool(f, self, local, hosts);
@@ -386,6 +470,7 @@ export async function runSessionBrowser(initial = {}, opts = {}) {
         // Latest load — commit shared state atomically (no await past this point, so
         // no newer load can interleave between these writes).
         rawCache = pool;
+        unreachable = pool.unreachable;
         if (live)
             liveCache = live;
         // Live sessions the transcript pool lacks become rows of their own, so the
@@ -393,6 +478,17 @@ export async function runSessionBrowser(initial = {}, opts = {}) {
         const rows = f.running && live ? mergeLiveIntoPool(pool.rows, live, self) : pool.rows;
         agentsInPool = distinct(rows.map((r) => r.agent));
         devicesInPool = distinct(rows.map((r) => r.machine ?? self));
+        // Both ends of the lineage seed the cycle: teams a row spawned, and teams a
+        // row belongs to. Teammate rows only carry `teamOrigin` when `c` is on, so
+        // with teams hidden this ranges over spawned teams alone — which is exactly
+        // the set whose rows are visible.
+        // Through safeTeamText: the cycle's values become `f.team`, which headerFor
+        // interpolates into the header and browserFilterToArgv copies into a command,
+        // and on a peer's row these strings are that machine's to choose.
+        teamsInPool = distinct([
+            ...rows.map((r) => safeTeamText(r.spawnedTeam)),
+            ...rows.map((r) => safeTeamText(r.teamOrigin?.team)),
+        ]);
         const filtered = applyFilters(rows, live ?? new Map(), f, self);
         cols = pickerColumnsFor(filtered);
         cols.showHost = shouldShowHostColumn(f, live, filtered);
@@ -406,7 +502,9 @@ export async function runSessionBrowser(initial = {}, opts = {}) {
         labelFor: (s, q) => formatPickerLabel(s, q, cols, sshOriginTagFor(liveCache, s.id), liveHostLabel(liveCache?.get(s.id))),
         matches: sessionMatchesQuery,
         buildPreview,
-        headerFor,
+        headerFor: (f) => unreachable.length > 0
+            ? `${headerFor(f)} · ${chalk.yellow(`${unreachable.join(', ')}: unreachable`)}`
+            : headerFor(f),
         helpFor,
         enterHint: 'resume',
         emptyMessage: 'No sessions match this filter.',
@@ -416,7 +514,11 @@ export async function runSessionBrowser(initial = {}, opts = {}) {
             c: (f) => ({ ...f, teams: !f.teams }),
             a: (f) => ({ ...f, agent: cycle(f.agent, agentsInPool) }),
             d: (f) => ({ ...f, device: cycle(f.device, devicesInPool) }),
-            p: (f) => ({ ...f, projectScope: f.projectScope === 'repo' ? 'all' : 'repo' }),
+            t: (f) => ({ ...f, team: cycle(f.team, teamsInPool) }),
+            // Under an explicit --device scope every row is a peer's, and no peer cwd
+            // is under our process.cwd() — so narrowing to "this repo" could only ever
+            // empty the list. Returning the same reference makes the key a no-op.
+            p: (f) => (hosts ? f : { ...f, projectScope: f.projectScope === 'repo' ? 'all' : 'repo' }),
             w: (f) => ({ ...f, window: cycleWindow(f.window) }),
         },
         onKey: (name, f, _active, query) => {

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

@@ -31,18 +31,31 @@ export interface SessionPickerConfig {
 }
 /** Build a cached multi-line preview string for display in the session picker. */
 export declare function buildPreview(session: SessionMeta): string;
-/** Optional dirs-touched field the parser teammate may attach; we prefer it. */
-type SessionMetaWithDirs = SessionMeta & {
-    dirsTouched?: string[];
-};
+/**
+ * Body lines available from SessionMeta alone (no transcript parse) — used for
+ * remote / unindexed sessions so checklist progress still surfaces when the
+ * parser teammate (or a prior scan) has populated `session.todos`.
+ */
+/**
+ * The session's place in a team, from whichever end it sits at: the orchestrator
+ * that ran `agents teams create` (from the scan-derived `spawnedTeam`), or a
+ * teammate (from its `meta.json`, via `classifyTeamSession`). Empty for a session
+ * with no team involvement, which is the overwhelming majority.
+ *
+ * Deliberately no live teammate counts: tallying a team means reading every
+ * record under the teams-agents dir, which runs to thousands of files on a busy
+ * machine — far too much for a pane that repaints as the cursor moves. The line
+ * names the command that does report them instead.
+ */
+export declare function formatTeamLineage(session: SessionMeta): string;
 /**
  * Unique directories the session touched, compact and human-readable.
- * Prefer `session.dirsTouched` when the parser teammate has populated it;
- * otherwise derive from file-change + tool paths already available here.
+ * Prefer `session.recentDirectoriesTouched` — the scan records it on the row, so
+ * it is present for remote rows whose transcript we can't parse here — otherwise
+ * derive from the file-change + tool paths already available.
  */
-export declare function directoriesTouched(session: SessionMetaWithDirs, events: SessionEvent[], changes: ReturnType<typeof classifyFileChanges>): string[];
+export declare function directoriesTouched(session: SessionMeta, events: SessionEvent[], changes: ReturnType<typeof classifyFileChanges>): string[];
 /** Relativize a file path to its parent dir, short enough for one preview line. */
 export declare function relativizeDir(filePath: string, cwd?: string): string | undefined;
 /** Show an interactive session picker and return the selected session with its action (resume or view). */
 export declare function sessionPicker(config: SessionPickerConfig): Promise<PickedSession | null>;
-export {};

package/dist/commands/sessions-picker.js

@@ -10,6 +10,7 @@ import path from 'node:path';
 import chalk from 'chalk';
 import { truncate, humanDuration } from '../lib/format.js';
 import { parseSession, sanitizeForTerminal, SNAPSHOT_TODO_TOOLS } from '../lib/session/parse.js';
+import { safeTeamText } from '../lib/session/team-filter.js';
 import { cleanSessionPrompt, extractSessionTopic } from '../lib/session/prompt.js';
 import { linkPath, linkUrl, relativeToCwd, shortenModel } from '../lib/session/render.js';
 import { linearIssueUrl } from '../lib/session/linear.js';
@@ -84,6 +85,12 @@ function sanitizeMeta(s) {
         label: clean(s.label),
         ticketId: clean(s.ticketId),
         prUrl: clean(s.prUrl),
+        // A remote row's meta is peer-supplied JSON that parseRemoteList hands over
+        // unsanitized, and both of these reach the preview pane — so an escape
+        // sequence in a peer's plan text or path list would otherwise hit our TTY.
+        plan: clean(s.plan),
+        spawnedTeam: clean(s.spawnedTeam),
+        recentDirectoriesTouched: s.recentDirectoriesTouched?.map(sanitizeForTerminal),
         todos,
     };
 }
@@ -205,15 +212,69 @@ function formatHeader(session, events) {
  * remote / unindexed sessions so checklist progress still surfaces when the
  * parser teammate (or a prior scan) has populated `session.todos`.
  */
+/**
+ * The session's place in a team, from whichever end it sits at: the orchestrator
+ * that ran `agents teams create` (from the scan-derived `spawnedTeam`), or a
+ * teammate (from its `meta.json`, via `classifyTeamSession`). Empty for a session
+ * with no team involvement, which is the overwhelming majority.
+ *
+ * Deliberately no live teammate counts: tallying a team means reading every
+ * record under the teams-agents dir, which runs to thousands of files on a busy
+ * machine — far too much for a pane that repaints as the cursor moves. The line
+ * names the command that does report them instead.
+ */
+export function formatTeamLineage(session) {
+    const origin = session.teamOrigin;
+    if (origin) {
+        const team = safeTeamText(origin.team);
+        const handleName = safeTeamText(origin.handle);
+        const mode = safeTeamText(origin.mode);
+        const parent = safeTeamText(origin.parentSessionId);
+        const parts = [chalk.white(team ?? 'team')];
+        const handle = handleName ? `teammate ${handleName}` : 'teammate';
+        parts.push(chalk.white(mode ? `${handle} (${mode})` : handle));
+        if (parent) {
+            parts.push(chalk.gray('spawned by ') + chalk.white(parent.slice(0, 8)));
+        }
+        return parts.join(chalk.gray(' · '));
+    }
+    const spawned = safeTeamText(session.spawnedTeam);
+    if (spawned) {
+        return (chalk.gray('spawned team ') +
+            chalk.white(spawned) +
+            chalk.gray(` · agents teams status ${spawned}`));
+    }
+    return '';
+}
 function formatMetaOnlyBody(session) {
     const lines = [];
     if (session.topic) {
         lines.push(chalk.cyan('Prompt: ') + chalk.white(truncate(session.topic.trim(), (process.stdout.columns || 80) - 12)));
     }
+    const teamLine = formatTeamLineage(session);
+    if (teamLine) {
+        lines.push(chalk.cyan('Team:   ') + teamLine);
+    }
     const compact = formatTodoCompact(session.todos);
     if (compact) {
         lines.push(chalk.cyan('Todos: ') + chalk.white(compact));
     }
+    const termWidth = process.stdout.columns || 80;
+    for (const l of session.todos?.items?.length ? renderTodos(session.todos.items, termWidth) : []) {
+        lines.push(l);
+    }
+    const dirs = session.recentDirectoriesTouched?.slice(0, DIRS_TOUCHED_MAX) ?? [];
+    if (dirs.length) {
+        lines.push(chalk.cyan('Dirs:   ') + chalk.white(dirs.join(chalk.gray(' · '))));
+    }
+    // `plan` is the whole ExitPlanMode markdown, not a path — summarize it. The
+    // pane is height-clamped anyway, so pasting the blob would just push every
+    // other line out of view.
+    const planLines = session.plan?.trim() ? session.plan.trim().split('\n') : [];
+    if (planLines.length) {
+        const head = truncate(planLines[0].replace(/^#+\s*/, ''), termWidth - 20);
+        lines.push(chalk.cyan('Plan:   ') + chalk.white(head) + chalk.gray(` · ${planLines.length} lines`));
+    }
     if (lines.length === 0)
         return '';
     return lines.map(l => '  ' + l).join('\n');
@@ -360,6 +421,10 @@ function formatCompactPreview(events, session) {
     if (dirs.length) {
         lines.push(chalk.cyan('Dirs:    ') + chalk.white(dirs.join(chalk.gray(' · '))));
     }
+    const teamLine = formatTeamLineage(session);
+    if (teamLine) {
+        lines.push(chalk.cyan('Team:    ') + teamLine);
+    }
     const activity = [];
     const changed = chg.created + chg.modified + chg.deleted;
     if (changed) {
@@ -435,16 +500,27 @@ function isSubAgentTool(tool, command) {
 }
 /**
  * Unique directories the session touched, compact and human-readable.
- * Prefer `session.dirsTouched` when the parser teammate has populated it;
- * otherwise derive from file-change + tool paths already available here.
+ * Prefer `session.recentDirectoriesTouched` — the scan records it on the row, so
+ * it is present for remote rows whose transcript we can't parse here — otherwise
+ * derive from the file-change + tool paths already available.
  */
 export function directoriesTouched(session, events, changes) {
-    const fromMeta = session.dirsTouched;
+    const fromMeta = session.recentDirectoriesTouched;
     if (Array.isArray(fromMeta) && fromMeta.length > 0) {
-        return fromMeta
-            .map((d) => sanitizeForTerminal(String(d).trim()))
-            .filter(Boolean)
-            .slice(0, DIRS_TOUCHED_MAX);
+        // The scan stores ABSOLUTE paths, so they go through the same relativizer the
+        // derived branch below uses — otherwise adopting this field (which a remote row
+        // needs, having no transcript to derive from) would turn every local preview's
+        // `Dirs:` line from `src/lib · docs` into a column of full home-rooted paths.
+        const seen = new Set();
+        for (const raw of fromMeta) {
+            const dir = relativizeDir(sanitizeForTerminal(String(raw).trim()), session.cwd);
+            if (dir)
+                seen.add(dir);
+            if (seen.size >= DIRS_TOUCHED_MAX)
+                break;
+        }
+        if (seen.size > 0)
+            return [...seen];
     }
     const counts = new Map();
     const bump = (raw) => {

package/dist/commands/sessions.d.ts

@@ -8,6 +8,7 @@ interface SessionFilterOptions {
     project?: string;
     all?: boolean;
     teams?: boolean;
+    inTeam?: string;
     routine?: boolean;
     since?: string;
     until?: string;
@@ -274,6 +275,24 @@ export declare function isBareBrowserListing(options: SessionsOptions, query: st
  * `runSessionBrowser` picker cannot represent.
  */
 export declare function hasNoBrowserDisqualifyingFlags(options: SessionsOptions, query: string | undefined): boolean;
+/**
+ * Whether a session belongs to `team`, from either end: it spawned the team, or
+ * it is one of the team's teammates. Case-insensitive, matching the SQL
+ * predicate behind `querySessions({ spawnedTeam })`.
+ */
+export declare function matchesTeam(session: SessionMeta, team: string): boolean;
+/**
+ * The `team:<name>` badge for a session that SPAWNED a team — the orchestrator
+ * end of the lineage, from the scan-derived `spawnedTeam`. Returned as a plain
+ * (uncolored) string plus its display width so callers can reserve the width
+ * from the topic budget and color it as their own segment: folding it into the
+ * topic string would lose the color, since renderTopicCell strips ANSI and
+ * re-whitens every slice.
+ */
+export declare function teamBadge(session: SessionMeta): {
+    plain: string;
+    width: number;
+};
 /** One flat table row:
  *   shortId · agent · version · model · project · [glyph] label·doing · [ticket] · [wt] · time
  * `doing` is the live preview when running, else the topic. The `ticket` column