@phnx-labs/agents-cli 1.20.85 → 1.20.87

package/CHANGELOG.md

@@ -1,5 +1,173 @@
 # 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
+  tool calls.** Kimi writes its checklist with `TodoList` (items shaped
+  `{title, status}`, where finished is `done`) rather than Claude's `TodoWrite`
+  (`{content, status: "completed"}`), so the checklist registry matched nothing
+  and every Kimi session rendered with no todos — in the picker preview, the
+  session detail, and the `--active` fan-out that carries progress off remote
+  devices. Kimi also names the file argument `path` where Claude names it
+  `file_path`, so `Read`/`Write`/`Edit` calls summarized as a bare `Read ` with
+  no file. Both spellings are now handled, and the snapshot-checklist tool names
+  live in one exported registry (`SNAPSHOT_TODO_TOOLS`) that the picker and the
+  state engine share instead of each hardcoding its own pair. Source:
+  `apps/cli/src/lib/session/parse.ts`, `apps/cli/src/lib/session/state.ts`,
+  `apps/cli/src/commands/sessions-picker.ts`.
+
+- **`agents view` now shows Grok's default model (e.g. `grok-4.5`).** Claude,
+  Codex, Antigravity, and Kimi already filled the model column via their
+  catalogs; Grok was missing from `locateModelSource`, so
+  `resolveConfiguredModel` returned null and the column stayed blank. Grok has
+  no `settings.json` `model` field (its config is `config.toml` +
+  `models_cache.json`); the authoritative default is `grok models` →
+  `Default model: <id>`. The catalog extractor now spawns that command against
+  the version-home binary (skipping failed-download stubs) and flags the
+  default, so `agents view`, `agents view --json` (`configuredModel`), and the
+  other identity-cluster surfaces show it. Source: `apps/cli/src/lib/models.ts`,
+  `apps/cli/src/commands/models.ts`.
+
+- **`agents events --limit 0` now reads the whole stream, and a capped read says
+  so.** `--limit` parsed as `Math.max(1, parseInt(raw) || 50)`, so `--limit 0`
+  collapsed back to `50` (`0 || 50`) and there was no way to read past the default
+  cap at all. The cap is applied after filtering and before the caller sees
+  anything, so every aggregation over `--json` silently ranked the newest 50
+  records instead of the matching set — measured against a real 7-day corpus of
+  2,135 CLI failures in 9 classes, 8 of 9 ranks came out wrong with counts off by
+  roughly 100x, and nothing warned. `--limit 0` now means no cap (29,649 records
+  on a 30-day stream here, against 50 before), a truncated read prints
+  `Showing the newest 50 — more events matched. Pass --limit 0 for all.` (on
+  stderr under `--json`, so a `| jq` pipeline still receives clean JSON), and a
+  non-numeric, negative, or empty `--limit` exits 2 rather than quietly becoming
+  50 — an empty one (`--limit "$LIMIT"` with the variable unset) would otherwise
+  have read as "no cap" and returned the whole stream unannounced.
+  Source: `apps/cli/src/commands/events.ts`, `apps/cli/tests/events-limit.test.ts`,
+  `apps/cli/docs/06-observability.md`.
+
+- **Desktop notifications now show the current agents-cli mark, not the old
+  logo.** The menu-bar helper's app icon — the icon macOS puts on the left of
+  every notification banner it posts (the menu bar helper's own notices and every
+  `agents run --notify` finish notice) — was generated from the retired gradient
+  "A" logo, so notifications carried stale branding while the menu-bar status
+  item already used the new lowercase `a`. The shared master logo
+  (`assets/logo.png`) is now the current `a` mark, so the menu-bar helper, the
+  `agents computer` helper, and the keychain helper all regenerate their
+  `AppIcon.icns` from it on the next build. Source: `assets/logo.png`,
+  `apps/cli/menubar/scripts/build.sh`.
+
 ## 1.20.85
 
 - **`agents feed post` can now be mirrored to the systems you actually watch.**

package/dist/commands/events.d.ts

@@ -14,4 +14,20 @@
  * today's operational log live.
  */
 import type { Command } from 'commander';
+/**
+ * Resolve `--limit` into a record cap. `0` means "no cap" — without it there is
+ * no way to read the whole stream, and any aggregation (group-by failure, count
+ * per module) silently ranks the newest 50 records instead of the real set.
+ * A non-numeric or negative value is a usage error, not a quiet fallback.
+ */
+export declare function resolveEventsLimit(raw: string | undefined): number | undefined;
+/**
+ * Cap `fetched` (read with `limit + 1`) to `limit`, reporting whether records
+ * were dropped. The caller announces the cap so a truncated read is never
+ * mistaken for the complete set.
+ */
+export declare function capRecords<T>(fetched: T[], limit: number | undefined): {
+    records: T[];
+    truncated: boolean;
+};
 export declare function registerEventsCommand(program: Command): void;

package/dist/commands/events.js

@@ -17,6 +17,33 @@ import chalk from 'chalk';
 import * as fs from 'fs';
 import { getLogsPath } from '../lib/events.js';
 import { readUnifiedEvents } from '../lib/event-stream.js';
+/**
+ * Resolve `--limit` into a record cap. `0` means "no cap" — without it there is
+ * no way to read the whole stream, and any aggregation (group-by failure, count
+ * per module) silently ranks the newest 50 records instead of the real set.
+ * A non-numeric or negative value is a usage error, not a quiet fallback.
+ */
+export function resolveEventsLimit(raw) {
+    const token = raw ?? '50';
+    // Number('') and Number('   ') are both 0, which would read as "no cap" — an
+    // empty --limit (an unset "$LIMIT" in a script) must be rejected, not silently
+    // turned into the unbounded read.
+    const value = token.trim() === '' ? NaN : Number(token);
+    if (!Number.isInteger(value) || value < 0) {
+        throw new RangeError(`Invalid --limit ${raw} — pass a whole number, or 0 for no cap.`);
+    }
+    return value === 0 ? undefined : value;
+}
+/**
+ * Cap `fetched` (read with `limit + 1`) to `limit`, reporting whether records
+ * were dropped. The caller announces the cap so a truncated read is never
+ * mistaken for the complete set.
+ */
+export function capRecords(fetched, limit) {
+    if (limit === undefined || fetched.length <= limit)
+        return { records: fetched, truncated: false };
+    return { records: fetched.slice(0, limit), truncated: true };
+}
 /** Parse `--since`: relative offsets (30s/5m/2h/7d/4w) or an ISO/absolute date. */
 function parseSince(s) {
     const m = s.match(/^(\d+)([smhdw])$/);
@@ -80,7 +107,7 @@ export function registerEventsCommand(program) {
         .option('--agent <name>', 'Only events tagged with this agent')
         .option('--since <time>', 'Only events newer than this (e.g. 2h, 7d, or ISO date)')
         .option('--audit', 'Operational events only (skip agent activity)')
-        .option('--limit <n>', 'Max records to show (default 50)', '50')
+        .option('--limit <n>', 'Max records to show; 0 for no cap (default 50)', '50')
         .option('--json', 'Output raw records as JSON')
         .option('-f, --follow', "Tail today's operational log live")
         .addHelpText('after', `
@@ -90,31 +117,41 @@ Examples:
   agents events --audit                  Operational events only (secrets / teams / ...)
   agents events --event pr.opened --since 7d
   agents events --module secrets         Every secret accessed or revealed
-  agents events -f                       Live tail (operational)`)
+  agents events -f                       Live tail (operational)
+  agents events --event pr.opened --since 30d --limit 0 --json
+                                         Every match — use --limit 0 whenever you
+                                         aggregate, or you rank only the newest 50`)
         .action(async (options) => {
         if (options.follow) {
             await followLog();
             return;
         }
-        const limit = Math.max(1, parseInt(options.limit ?? '50', 10) || 50);
+        let limit;
         let startDate;
         try {
+            limit = resolveEventsLimit(options.limit);
             startDate = options.since ? parseSince(options.since) : undefined;
         }
         catch (err) {
             console.error(chalk.red(err.message));
             process.exit(2);
         }
-        const records = readUnifiedEvents({
+        // Read one past the cap so we can tell a full result from a clipped one.
+        const fetched = readUnifiedEvents({
             startDate,
             eventTypes: options.event && options.event.length ? options.event : undefined,
             agent: options.agent,
             command: options.command,
             module: options.module,
-            limit,
+            limit: limit === undefined ? undefined : limit + 1,
             includeActivity: !options.audit,
         });
+        const { records, truncated } = capRecords(fetched, limit);
+        const capNote = `Showing the newest ${limit} — more events matched. Pass --limit 0 for all.`;
         if (options.json) {
+            // Notice goes to stderr so `--json | jq` still receives clean JSON.
+            if (truncated)
+                console.error(chalk.yellow(capNote));
             console.log(JSON.stringify(records, null, 2));
             return;
         }
@@ -126,6 +163,8 @@ Examples:
         for (const r of records.slice().reverse())
             console.log(renderRow(r));
         console.log(chalk.gray(`\n${records.length} event(s). Log: ${getLogsPath()}`));
+        if (truncated)
+            console.log(chalk.yellow(capNote));
     });
 }
 /** commander repeatable-option collector. */

package/dist/commands/models.js

@@ -13,7 +13,7 @@ import { listInstalledVersions, getGlobalDefault, resolveVersion, resolveVersion
 import { getModelCatalog, locateModelSource } from '../lib/models.js';
 import { terminalWidth, truncateToWidth, stringWidth } from '../lib/session/width.js';
 import { wrapJoined } from './inspect.js';
-const MODEL_CAPABLE_AGENTS = ['claude', 'codex', 'opencode', 'cursor', 'openclaw', 'antigravity', 'kimi'];
+const MODEL_CAPABLE_AGENTS = ['claude', 'codex', 'opencode', 'cursor', 'openclaw', 'antigravity', 'kimi', 'grok'];
 /**
  * Agents that don't necessarily install under ~/.agents/versions (cursor ships
  * via a curl script). For these, fall back to the PATH binary and synthesize

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) => {