@phnx-labs/agents-cli 1.20.86 → 1.20.87

package/dist/lib/claude-account-token.d.ts

@@ -0,0 +1,12 @@
+/** The per-account key an email maps to inside the `auth` bundle. */
+export declare function claudeAccountTokenKey(account: string): string;
+/** Signed-in account email for a version home, from `.claude.json` (no keychain). */
+export declare function readClaudeAccountEmail(home?: string): string | null;
+/**
+ * Resolve a long-lived `claude setup-token` for the account signed into `home`
+ * from the reserved FILE-BASED `auth` bundle. Returns the token or null. Reads
+ * ONLY when the bundle is file-backed (never keychain), so this path itself can
+ * never trigger a Touch ID prompt — that is the entire point: usage/probe reads
+ * authenticate with the shareable setup-token, not the ACL-bound login item.
+ */
+export declare function resolveClaudeSetupToken(home?: string): string | null;

package/dist/lib/claude-account-token.js

@@ -0,0 +1,63 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { bundleBackend, bundleExists, readAndResolveBundleEnv } from './secrets/bundles.js';
+/**
+ * Reserved FILE-BASED secrets bundle holding long-lived, non-rotating Claude
+ * setup-tokens. Usage/probe reads authenticate with these instead of Claude
+ * Code's ACL-bound login item, so they never pop Touch ID. Keyed strictly
+ * per-account (`CLAUDE_CODE_OAUTH_TOKEN_<slug>` from the account email) — never a
+ * bare key, so one account's token can't be misapplied to another in a
+ * multi-account fleet.
+ */
+const AUTH_BUNDLE = 'auth';
+/** The per-account key an email maps to inside the `auth` bundle. */
+export function claudeAccountTokenKey(account) {
+    const slug = account
+        .trim()
+        .toUpperCase()
+        .replace(/@/g, '_AT_')
+        .replace(/\./g, '_DOT_')
+        .replace(/[^A-Z0-9_]/g, '_');
+    return `CLAUDE_CODE_OAUTH_TOKEN_${slug}`;
+}
+/** Signed-in account email for a version home, from `.claude.json` (no keychain). */
+export function readClaudeAccountEmail(home) {
+    const base = home ?? os.homedir();
+    for (const p of [path.join(base, '.claude', '.claude.json'), path.join(base, '.claude.json')]) {
+        try {
+            const email = JSON.parse(fs.readFileSync(p, 'utf-8')).oauthAccount?.emailAddress;
+            if (typeof email === 'string' && email.trim().length > 0)
+                return email.trim();
+        }
+        catch {
+            // Missing/unreadable at this location — try the next.
+        }
+    }
+    return null;
+}
+/**
+ * Resolve a long-lived `claude setup-token` for the account signed into `home`
+ * from the reserved FILE-BASED `auth` bundle. Returns the token or null. Reads
+ * ONLY when the bundle is file-backed (never keychain), so this path itself can
+ * never trigger a Touch ID prompt — that is the entire point: usage/probe reads
+ * authenticate with the shareable setup-token, not the ACL-bound login item.
+ */
+export function resolveClaudeSetupToken(home) {
+    try {
+        // Require a known account (email) up front: without it we cannot key a
+        // per-account token, and we must NOT fall back to a bare shared key that
+        // would misapply one account's setup-token to another.
+        const email = readClaudeAccountEmail(home);
+        if (!email)
+            return null;
+        if (!bundleExists(AUTH_BUNDLE) || bundleBackend(AUTH_BUNDLE) !== 'file')
+            return null;
+        const { env } = readAndResolveBundleEnv(AUTH_BUNDLE, { caller: 'usage', agentOnly: true });
+        const v = (env[claudeAccountTokenKey(email)] ?? '').trim();
+        return v.length > 0 ? v : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/lib/devices/registry.d.ts

@@ -142,3 +142,28 @@ export declare function addIgnored(name: string): Promise<Set<string>>;
 /** Remove a node name from the ignore-list (un-ignore). Returns false if it was
  * not ignored. */
 export declare function removeIgnored(name: string): Promise<boolean>;
+/**
+ * Auto-launch preferences: which registered devices are eligible for Factory's
+ * auto-host selection, and which are preferred. Stored as a sibling to the
+ * registry and ignore-list under ~/.agents/.history/devices/.
+ */
+export interface AutoLaunchPreference {
+    enabled?: boolean;
+    preferred?: boolean;
+}
+export interface AutoLaunchPreferences {
+    devices: Record<string, AutoLaunchPreference>;
+    updatedAt: string;
+}
+/** Load auto-launch preferences. Missing or malformed file => empty map. */
+export declare function loadAutoLaunchPreferences(): Promise<Record<string, AutoLaunchPreference>>;
+/** True if the device is enabled for auto-launch. Missing entry defaults to true. */
+export declare function isAutoLaunchEnabled(name: string): Promise<boolean>;
+/** Set whether a device is enabled for auto-launch. Setting to the default
+ * (enabled) removes the entry to keep the file minimal. */
+export declare function setAutoLaunchEnabled(name: string, enabled: boolean): Promise<void>;
+/** True if the device is preferred for auto-launch ranking. */
+export declare function isAutoLaunchPreferred(name: string): Promise<boolean>;
+/** Set whether a device is preferred for auto-launch. Setting to the default
+ * (not preferred) removes the flag to keep the file minimal. */
+export declare function setAutoLaunchPreferred(name: string, preferred: boolean): Promise<void>;

package/dist/lib/devices/registry.js

@@ -18,7 +18,7 @@ import * as fsSync from 'fs';
 import * as path from 'path';
 import { randomBytes } from 'crypto';
 import lockfile from 'proper-lockfile';
-import { getDevicesRegistryPath, getDevicesIgnoredPath } from '../state.js';
+import { getDevicesRegistryPath, getDevicesIgnoredPath, getDevicesAutoLaunchPath } from '../state.js';
 /** A device's effective role, defaulting to `worker` when unset. */
 export function deviceRole(d) {
     return d.role ?? 'worker';
@@ -288,3 +288,84 @@ export async function removeIgnored(name) {
         return true;
     });
 }
+function autoLaunchPath() {
+    return getDevicesAutoLaunchPath();
+}
+/** Load auto-launch preferences. Missing or malformed file => empty map. */
+export async function loadAutoLaunchPreferences() {
+    const p = autoLaunchPath();
+    let raw;
+    try {
+        raw = await fs.readFile(p, 'utf-8');
+    }
+    catch (err) {
+        if (err && err.code === 'ENOENT')
+            return {};
+        throw err;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed.devices && typeof parsed.devices === 'object' ? parsed.devices : {};
+    }
+    catch (err) {
+        throw new Error(`Device auto-launch preferences corrupted at ${p}: ${err?.message ?? err}. Inspect and restore from backup.`);
+    }
+}
+/** True if the device is enabled for auto-launch. Missing entry defaults to true. */
+export async function isAutoLaunchEnabled(name) {
+    assertValidDeviceName(name);
+    const prefs = await loadAutoLaunchPreferences();
+    return prefs[name]?.enabled !== false;
+}
+/** Set whether a device is enabled for auto-launch. Setting to the default
+ * (enabled) removes the entry to keep the file minimal. */
+export async function setAutoLaunchEnabled(name, enabled) {
+    assertValidDeviceName(name);
+    const p = autoLaunchPath();
+    await withRegistryLock(p, async () => {
+        const prefs = await loadAutoLaunchPreferences();
+        if (enabled) {
+            if (prefs[name]) {
+                const { enabled: _, ...rest } = prefs[name];
+                if (Object.keys(rest).length === 0) {
+                    delete prefs[name];
+                }
+                else {
+                    prefs[name] = rest;
+                }
+            }
+        }
+        else {
+            prefs[name] = { ...prefs[name], enabled: false };
+        }
+        await atomicWriteJson(p, { devices: prefs, updatedAt: new Date().toISOString() });
+    });
+}
+/** True if the device is preferred for auto-launch ranking. */
+export async function isAutoLaunchPreferred(name) {
+    assertValidDeviceName(name);
+    const prefs = await loadAutoLaunchPreferences();
+    return prefs[name]?.preferred === true;
+}
+/** Set whether a device is preferred for auto-launch. Setting to the default
+ * (not preferred) removes the flag to keep the file minimal. */
+export async function setAutoLaunchPreferred(name, preferred) {
+    assertValidDeviceName(name);
+    const p = autoLaunchPath();
+    await withRegistryLock(p, async () => {
+        const prefs = await loadAutoLaunchPreferences();
+        if (preferred) {
+            prefs[name] = { ...prefs[name], preferred: true };
+        }
+        else if (prefs[name]) {
+            const { preferred: _, ...rest } = prefs[name];
+            if (Object.keys(rest).length === 0) {
+                delete prefs[name];
+            }
+            else {
+                prefs[name] = rest;
+            }
+        }
+        await atomicWriteJson(p, { devices: prefs, updatedAt: new Date().toISOString() });
+    });
+}

package/dist/lib/events.d.ts

@@ -13,7 +13,7 @@
  */
 import { type ActorKind } from './actor.js';
 export type EventLevel = 'audit' | 'warn' | 'info' | 'debug';
-export type EventType = 'agent.run.start' | 'agent.run.end' | 'agent.spawn.start' | 'agent.spawn.end' | 'version.install' | 'version.switch' | 'version.remove' | 'skill.install' | 'skill.remove' | 'browser.launch' | 'browser.close' | 'browser.navigate' | 'browser.screenshot' | 'secrets.get' | 'secrets.unlocked' | 'secrets.set' | 'secrets.delete' | 'secrets.rename' | 'cloud.dispatch' | 'cloud.complete' | 'cloud.cancel' | 'cloud.message' | 'teams.create' | 'teams.add' | 'teams.start' | 'teams.complete' | 'teams.disband' | 'hook.fire' | 'hook.complete' | 'hook.error' | 'mcp.add' | 'mcp.remove' | 'mcp.register' | 'resource.sync' | 'rotation.resolved' | 'command.start' | 'command.end' | 'perf.timing' | 'session.start' | 'session.end' | 'plan.created' | 'pr.opened' | 'pr.merged' | 'worktree.created' | 'worktree.removed' | 'commit.created' | 'pushed' | 'subagent.spawned' | 'artifact.created' | 'task.completed' | 'checklist.created' | 'status.posted' | 'file.edited' | 'error' | 'warn' | 'info' | 'debug';
+export type EventType = 'agent.run.start' | 'agent.run.end' | 'agent.spawn.start' | 'agent.spawn.end' | 'version.install' | 'version.switch' | 'version.remove' | 'skill.install' | 'skill.remove' | 'browser.launch' | 'browser.close' | 'browser.navigate' | 'browser.screenshot' | 'secrets.get' | 'secrets.unlocked' | 'secrets.set' | 'secrets.delete' | 'secrets.rename' | 'cloud.dispatch' | 'cloud.complete' | 'cloud.cancel' | 'cloud.message' | 'teams.create' | 'teams.add' | 'teams.start' | 'teams.complete' | 'teams.disband' | 'hook.fire' | 'hook.complete' | 'hook.error' | 'mcp.add' | 'mcp.remove' | 'mcp.register' | 'resource.sync' | 'rotation.resolved' | 'command.start' | 'command.end' | 'perf.timing' | 'session.start' | 'session.end' | 'plan.created' | 'pr.opened' | 'pr.merged' | 'worktree.created' | 'worktree.removed' | 'commit.created' | 'pushed' | 'subagent.spawned' | 'artifact.created' | 'task.completed' | 'checklist.created' | 'status.posted' | 'file.edited' | 'friction' | 'error' | 'warn' | 'info' | 'debug';
 export declare function levelFor(event: EventType): EventLevel;
 export interface EventMeta {
     ts: string;
@@ -156,6 +156,13 @@ export declare function emitCommand(command: string, args?: string[], payload?:
  * Emit an error event with full details.
  */
 export declare function emitError(err: Error | string, payload?: EventPayload): void;
+/**
+ * Emit a friction event — a structured, point-of-use record of a failure or
+ * block the CLI just hit. `surface` is the subsystem (teams, browser, secrets,
+ * guard, …); `failureId` is a stable slug that lets the nightly routine group
+ * the same failure across sessions (e.g. 'remote-cwd-on-add', 'not-installed').
+ */
+export declare function emitFriction(surface: string, failureId: string, payload?: EventPayload): void;
 /**
  * Remove log files older than the retention period.
  * Removes numbered gzip archives whose filesystem mtime exceeds retention.

package/dist/lib/events.js

@@ -523,6 +523,19 @@ export function emitError(err, payload = {}) {
         errorStack: truncate(error.stack, 1000),
     });
 }
+/**
+ * Emit a friction event — a structured, point-of-use record of a failure or
+ * block the CLI just hit. `surface` is the subsystem (teams, browser, secrets,
+ * guard, …); `failureId` is a stable slug that lets the nightly routine group
+ * the same failure across sessions (e.g. 'remote-cwd-on-add', 'not-installed').
+ */
+export function emitFriction(surface, failureId, payload = {}) {
+    emit('friction', {
+        ...payload,
+        surface,
+        failureId,
+    });
+}
 // ─── Gzip rotation ──────────────────────────────────────────────────────────
 /** Rotate the active file while its append lock is held. */
 function maybeGzipRotateLocked(logPath) {

package/dist/lib/exec.js

@@ -28,6 +28,7 @@ import { mailboxDir, isValidMailboxId } from './mailbox.js';
 import { composeWin32CommandLine } from './platform/index.js';
 import { isTmuxInstalled } from './tmux/binary.js';
 import { shellQuote } from './ssh-exec.js';
+import { resolveClaudeSetupToken } from './claude-account-token.js';
 /**
  * Map a raw mode string (CLI flag, YAML field, env var) to the canonical Mode.
  *
@@ -259,7 +260,15 @@ export function buildExecEnv(options) {
             ? resolvedVersion
             : (resolvedVersion && isVersionInstalled('claude', resolvedVersion) ? resolvedVersion : null);
         if (version) {
-            result.CLAUDE_CONFIG_DIR = path.join(getVersionHomePath('claude', version), '.claude');
+            const versionHome = getVersionHomePath('claude', version);
+            result.CLAUDE_CONFIG_DIR = path.join(versionHome, '.claude');
+            const setupToken = resolveClaudeSetupToken(versionHome);
+            if (setupToken) {
+                // A token keyed to this version home's own account replaces any ambient
+                // shared value inherited from the launcher. options.env still wins below
+                // for explicit caller overrides.
+                result.CLAUDE_CODE_OAUTH_TOKEN = setupToken;
+            }
             // A managed pin lives in a per-version dir; Claude Code's own background
             // auto-updater would rewrite that pinned binary in place (and has left it
             // half-swapped and broken). Disable it so a pin stays a pin. Honor an

package/dist/lib/format.d.ts

@@ -27,6 +27,13 @@ export declare function formatDie(msg: string, opts?: DieOptions): {
  * keep the original red-stderr behavior.
  */
 export declare function die(msg: string, code?: number, opts?: DieOptions): never;
+/**
+ * `die()` with a structured friction event attached. Use this at CLI error
+ * chokepoints so the nightly routine can classify and rank recurring failures
+ * without re-parsing transcripts. `surface` is the subsystem (teams, browser,
+ * secrets, guard, …); `failureId` is a stable slug (e.g. 'remote-cwd-on-add').
+ */
+export declare function dieFriction(surface: string, failureId: string, msg: string, code?: number, opts?: DieOptions): never;
 /**
  * Truncate `s` to at most `max` characters, appending a single-char ellipsis
  * (`…`) when shortened. Character-count based (not ANSI/width aware — use

package/dist/lib/format.js

@@ -9,6 +9,7 @@
  */
 import chalk from 'chalk';
 import { readSync } from 'node:fs';
+import { emitFriction } from './events.js';
 /**
  * Render a fatal error to the right stream. Pure — no I/O, no `process.exit` — so
  * the human-vs-agent split is unit-testable. A `--json` caller gets
@@ -43,6 +44,16 @@ export function die(msg, code = 1, opts = {}) {
         console.error(text);
     process.exit(code);
 }
+/**
+ * `die()` with a structured friction event attached. Use this at CLI error
+ * chokepoints so the nightly routine can classify and rank recurring failures
+ * without re-parsing transcripts. `surface` is the subsystem (teams, browser,
+ * secrets, guard, …); `failureId` is a stable slug (e.g. 'remote-cwd-on-add').
+ */
+export function dieFriction(surface, failureId, msg, code = 1, opts = {}) {
+    emitFriction(surface, failureId, { error: msg });
+    die(msg, code, opts);
+}
 /**
  * Truncate `s` to at most `max` characters, appending a single-char ellipsis
  * (`…`) when shortened. Character-count based (not ANSI/width aware — use

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

@@ -8,6 +8,10 @@
  */
 import Database from '../sqlite.js';
 import type { SessionAgentId, SessionMeta } from './types.js';
+/** Current schema version; bumped when migrations are added. Exported so tests
+ * assert against the constant instead of hardcoding a number that every bump
+ * then has to chase (docs/05-sessions.md calls the constant the source of truth). */
+export declare const SCHEMA_VERSION = 21;
 /** Raw row shape returned from the sessions table. */
 export interface SessionRow {
     id: string;
@@ -40,6 +44,7 @@ export interface SessionRow {
     pr_number: number | null;
     worktree_slug: string | null;
     ticket_id: string | null;
+    spawned_team: string | null;
     plan: string | null;
     machine: string | null;
     todos: string | null;
@@ -297,6 +302,22 @@ export declare function queryAffinityRollup(options: {
 export declare function queryUsageRollup(options: QueryOptions & {
     groupBy: UsageRollupGroup;
 }): UsageRollupRow[];
+/** Who spawned a team: the orchestrator session, from its transcript. */
+export interface TeamSpawner {
+    sessionId: string;
+    shortId: string;
+    /** The human the orchestrator ran as, when the row carries actor provenance. */
+    actor?: string;
+}
+/**
+ * Map every team name to the session that ran `agents teams create/add` for it.
+ *
+ * One scan over the rows that carry a `spawned_team`, rather than a query per
+ * team — `agents teams list` needs the whole map at once, and the column has no
+ * index. When two sessions spawned the same team name (a team re-created after a
+ * disband), the most recent wins, which is the one whose work the name refers to.
+ */
+export declare function teamSpawners(): Map<string, TeamSpawner>;
 /** A session with its cost, for the top-N-by-cost listing. */
 export interface TopCostSession {
     meta: SessionMeta;

package/dist/lib/session/db.js

@@ -16,8 +16,10 @@ import { machineForSessionFile } from './origin-machine.js';
 import { loadSessionActorIndex, readSessionActorRecord } from './actor-sidecar.js';
 const SESSIONS_DIR = getSessionsDir();
 const DB_PATH = getSessionsDbPath();
-/** Current schema version; bumped when migrations are added. */
-const SCHEMA_VERSION = 20;
+/** Current schema version; bumped when migrations are added. Exported so tests
+ * assert against the constant instead of hardcoding a number that every bump
+ * then has to chase (docs/05-sessions.md calls the constant the source of truth). */
+export const SCHEMA_VERSION = 21;
 /**
  * Canonicalize a file path for use as a scan_ledger key. The same physical
  * session file is reachable via multiple aliases — `~/.claude/projects/x.jsonl`
@@ -74,6 +76,7 @@ CREATE TABLE IF NOT EXISTS sessions (
   pr_number INTEGER,
   worktree_slug TEXT,
   ticket_id TEXT,
+  spawned_team TEXT,
   plan TEXT,
   machine TEXT,
   todos TEXT,
@@ -383,6 +386,19 @@ function migrateSchema(db, fromVersion) {
             db.exec(`ALTER TABLE sessions ADD COLUMN model TEXT`);
         db.exec(`DELETE FROM scan_ledger; DELETE FROM dir_ledger;`);
     }
+    if (fromVersion < 21) {
+        // v20 → v21: persist the team a session SPAWNED (`agents teams create/add`).
+        // The value was already derived at scan time (discover.ts detectSpawnedTeam)
+        // and set on SessionMeta, but had no column — so it was dropped at the write
+        // and no consumer ever saw it. Wipe BOTH ledgers, not just scan_ledger: with
+        // dir_ledger intact, collectChangedFilesInLeafDirs treats every non-live-root
+        // dir as unchanged and derives its hot set from the scan stamps just deleted,
+        // so archived dirs would never be re-parsed and would stay NULL forever.
+        const cols = db.prepare(`PRAGMA table_info(sessions)`).all();
+        if (!cols.some(c => c.name === 'spawned_team'))
+            db.exec(`ALTER TABLE sessions ADD COLUMN spawned_team TEXT`);
+        db.exec(`DELETE FROM scan_ledger; DELETE FROM dir_ledger;`);
+    }
 }
 /** Open (or return the cached) sessions database, applying migrations as needed. */
 export function getDB() {
@@ -744,7 +760,7 @@ const upsertSessionStmt = (db) => db.prepare(`
     project, cwd, git_branch, topic, label, message_count, token_count,
     output_tokens, cost_usd, duration_ms, model,
     file_path, file_mtime_ms, file_size, scanned_at, is_team_origin,
-    pr_url, pr_number, worktree_slug, ticket_id, plan, todos,
+    pr_url, pr_number, worktree_slug, ticket_id, spawned_team, plan, todos,
     recent_directories_touched, linear_project, linear_project_url, machine,
     actor, initiated_by
   ) VALUES (
@@ -753,7 +769,7 @@ const upsertSessionStmt = (db) => db.prepare(`
     @project, @cwd, @git_branch, @topic, @label, @message_count, @token_count,
     @output_tokens, @cost_usd, @duration_ms, @model,
     @file_path, @file_mtime_ms, @file_size, @scanned_at, @is_team_origin,
-    @pr_url, @pr_number, @worktree_slug, @ticket_id, @plan, @todos,
+    @pr_url, @pr_number, @worktree_slug, @ticket_id, @spawned_team, @plan, @todos,
     @recent_directories_touched, @linear_project, @linear_project_url, @machine,
     @actor, @initiated_by
   )
@@ -795,6 +811,7 @@ const upsertSessionStmt = (db) => db.prepare(`
     pr_number = excluded.pr_number,
     worktree_slug = excluded.worktree_slug,
     ticket_id = excluded.ticket_id,
+    spawned_team = excluded.spawned_team,
     plan = excluded.plan,
     todos = excluded.todos,
     recent_directories_touched = excluded.recent_directories_touched,
@@ -911,6 +928,7 @@ export function upsertSession(meta, content, scan) {
         pr_number: meta.prNumber ?? null,
         worktree_slug: meta.worktreeSlug ?? null,
         ticket_id: meta.ticketId ?? null,
+        spawned_team: meta.spawnedTeam ?? null,
         plan: meta.plan ?? null,
         todos: meta.todos ? JSON.stringify(meta.todos) : null,
         recent_directories_touched: meta.recentDirectoriesTouched ? JSON.stringify(meta.recentDirectoriesTouched) : null,
@@ -1031,6 +1049,7 @@ export function upsertSessionsBatch(entries) {
                     pr_number: meta.prNumber ?? null,
                     worktree_slug: meta.worktreeSlug ?? null,
                     ticket_id: meta.ticketId ?? null,
+                    spawned_team: meta.spawnedTeam ?? null,
                     plan: meta.plan ?? null,
                     todos: meta.todos ? JSON.stringify(meta.todos) : null,
                     recent_directories_touched: meta.recentDirectoriesTouched ? JSON.stringify(meta.recentDirectoriesTouched) : null,
@@ -1219,6 +1238,7 @@ function rowToMeta(row) {
         prNumber: row.pr_number ?? undefined,
         worktreeSlug: row.worktree_slug ?? undefined,
         ticketId: row.ticket_id ?? undefined,
+        spawnedTeam: row.spawned_team ?? undefined,
         plan: row.plan ?? undefined,
         todos: parseJsonColumn(row.todos),
         recentDirectoriesTouched: parseJsonColumn(row.recent_directories_touched),
@@ -1483,6 +1503,27 @@ export function queryUsageRollup(options) {
   `;
     return db.prepare(sql).all(...params);
 }
+/**
+ * Map every team name to the session that ran `agents teams create/add` for it.
+ *
+ * One scan over the rows that carry a `spawned_team`, rather than a query per
+ * team — `agents teams list` needs the whole map at once, and the column has no
+ * index. When two sessions spawned the same team name (a team re-created after a
+ * disband), the most recent wins, which is the one whose work the name refers to.
+ */
+export function teamSpawners() {
+    const db = getDB();
+    const rows = db
+        .prepare(`SELECT spawned_team, id, short_id, actor FROM sessions
+       WHERE spawned_team IS NOT NULL AND spawned_team != ''
+       ORDER BY timestamp ASC`)
+        .all();
+    const out = new Map();
+    for (const r of rows) {
+        out.set(r.spawned_team, { sessionId: r.id, shortId: r.short_id, actor: r.actor ?? undefined });
+    }
+    return out;
+}
 /**
  * Return the N most expensive sessions (cost_usd DESC, NULLs excluded),
  * honoring the same filter shape as querySessions. Drops rows whose JSONL

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

@@ -20,6 +20,13 @@ export interface RemoteListResult {
     sessions: SessionMeta[];
     /** How many peer machines we attempted to reach (drives the empty-fleet tip). */
     deviceCount: number;
+    /**
+     * Peers that failed to answer, by display name. The stderr note above is
+     * enough for a printed listing, but the interactive browser repaints over it —
+     * so callers rendering a full-screen UI need the outcome as data to tell
+     * "that box is asleep" apart from "that box has no matching sessions".
+     */
+    unreachable: string[];
 }
 /**
  * Gather listing sessions from other machines. With an explicit `hosts` list

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

@@ -97,9 +97,9 @@ async function fetchByTarget(target, machine, display, forwardedArgs, os) {
     const { code, stdout } = await sshCapture(target, remoteListCommand(forwardedArgs, os), REMOTE_TIMEOUT_MS);
     if (code !== 0) {
         process.stderr.write(chalk.gray(`  ${display}: unreachable or no agents CLI — skipped\n`));
-        return [];
+        return { sessions: [], unreachable: display };
     }
-    return parseRemoteList(stdout, machine);
+    return { sessions: parseRemoteList(stdout, machine) };
 }
 /**
  * Gather listing sessions from other machines. With an explicit `hosts` list
@@ -122,7 +122,7 @@ export async function gatherRemoteList(forwardedArgs, hosts) {
             reg = await loadDevices();
         }
         catch {
-            return { sessions: [], deviceCount: 0 };
+            return { sessions: [], deviceCount: 0, unreachable: [] };
         }
         for (const d of Object.values(reg)) {
             if (d.tailscale?.online !== true)
@@ -147,7 +147,11 @@ export async function gatherRemoteList(forwardedArgs, hosts) {
         }
     }
     const results = await Promise.all(targets.map((t) => fetchByTarget(t.target, t.machine, t.name, forwardedArgs, t.os)));
-    return { sessions: results.flat(), deviceCount: targets.length };
+    return {
+        sessions: results.flatMap((r) => r.sessions),
+        deviceCount: targets.length,
+        unreachable: results.map((r) => r.unreachable).filter((n) => !!n),
+    };
 }
 /** Resolve a peer's SSH target (and OS) from the device registry by its
  * normalized machine id — the same id the fan-out tags rows with. Returns

package/dist/lib/session/state.js

@@ -201,12 +201,66 @@ const GH_PR_CREATE_RE = /\bgh\s+pr\s+(?:create|new)\b/;
 const GH_ISSUE_CREATE_RE = /\bgh\s+issue\s+create\b/;
 /** A created GitHub issue URL (…/issues/123) in tool-result output. */
 const GH_ISSUE_URL_RE = /https:\/\/github\.com\/[^\s"'()<>]+\/issues\/(\d+)/;
+/**
+ * Flags of `teams create` / `teams add` that take a value, so the value is not
+ * mistaken for the positional team name. Mirrors their value-taking flags in
+ * `commands/teams.ts` — most are `.option('… <x>')` registrations, but
+ * `--device`/`--host` come from `addHostOption`, so auditing this list against
+ * `.option(` alone would wrongly drop them. A flag missing here degrades to "no
+ * team detected", never to a wrong one.
+ */
+const TEAM_VALUE_FLAGS = [
+    '-d', '--description', '--use-worktree', '--devices', '--hosts', '--repo',
+    '-n', '--name', '-m', '--mode', '-e', '--effort', '--model', '--env',
+    '--cwd', '--worktree', '--after', '--task-type', '--cloud', '--branch',
+    '--device', '--host',
+];
+/**
+ * One flag value: a quoted string or a bare token. `-d "sessions lineage"` is the
+ * common shape — `--description` is usually a phrase — and a value pattern of
+ * `\S+` alone stops at the first space, leaving the rest of the phrase to be read
+ * as the positional team name (`… -d "sessions lineage" my-team` detected
+ * `lineage`). Quotes are matched as a unit so the whole value is consumed.
+ *
+ * A value containing an ESCAPED quote (`-d "say \"hi\" now"`) stops the quoted
+ * branch early and the match then fails outright — which is the intended failure
+ * direction: no team detected rather than a wrong one.
+ */
+const FLAG_VALUE = String.raw `(?:"[^"\n]*"|'[^'\n]*'|\S+)`;
 /**
  * `agents teams create <name>` / `agents teams add <team> …` (also the `ag` alias).
  * The team NAME is the first bareword after the sub-verb, skipping any flags. This
  * is the structural signal that a session SPAWNED a team (vs. was spawned by one).
+ *
+ * The separators are spaces/tabs, never `\s`: a command string routinely embeds
+ * documentation and quoted output, and `\s` let the flag-skip run across newlines
+ * to capture a word from a completely different line (a real scan produced
+ * `team:installed` from a heredoc). For the same reason the flag-skip is bounded
+ * rather than unlimited — a real invocation carries a handful of flags before the
+ * name, not dozens.
  */
-const TEAMS_SPAWN_RE = /\bag(?:ents)?\s+teams?\s+(?:create|add)\s+(?:--?[a-z][\w-]*(?:[= ]\S+)?\s+)*([A-Za-z0-9][\w-]*)/;
+const TEAMS_SPAWN_RE = new RegExp(
+// Start of an actually-executed command: string start, a newline, or a shell
+// separator. Without this, a backticked mention inside prose or tool output
+// ("… and `agents teams add --device auto`") reads as a spawn.
+String.raw `(?:^|[\n;&|(]|&&|\|\|)[ \t]*` +
+    String.raw `ag(?:ents)?[ \t]+teams?[ \t]+(?:create|add)[ \t]+` +
+    // Flags before the positional name. A value-taking flag must swallow its
+    // value, or `--device auto` leaves `auto` looking like the team name — and
+    // the generic branch must exclude those flags, or it swallows the flag alone
+    // and hands the value back as the name.
+    String.raw `(?:(?:${TEAM_VALUE_FLAGS.join('|')})[= \t]${FLAG_VALUE}[ \t]+` +
+    String.raw `|(?!(?:${TEAM_VALUE_FLAGS.join('|')})[= \t])--?[a-z][\w-]*(?:=\S+)?[ \t]+){0,6}` +
+    // A team name may start with a digit — `createTeam` validates nothing, and
+    // `2fa-migration` is a legal name — so the class stays [A-Za-z0-9]. The
+    // all-digits case is rejected in the guard below instead.
+    String.raw `([A-Za-z0-9][\w-]*)`);
+/**
+ * Sub-verbs that can follow `teams create|add` in prose ("teams add a teammate")
+ * but are never a team name. Guards the common case where the match came from a
+ * sentence rather than an executed command.
+ */
+const NON_TEAM_WORDS = new Set(['a', 'an', 'the', 'to', 'for', 'with', 'and', 'this', 'your', 'my', 'it']);
 /** Collapse to a single trimmed line for a one-row preview cell. */
 function oneLine(s) {
     return s.replace(/\s+/g, ' ').trim();
@@ -259,7 +313,20 @@ export function detectSpawnedTeam(command) {
     if (!command)
         return undefined;
     const m = command.match(TEAMS_SPAWN_RE);
-    return m ? m[1] : undefined;
+    if (!m)
+        return undefined;
+    const name = m[1];
+    // A single character is a doc placeholder (`agents teams create t --host <box>`)
+    // far more often than a real team, and an English article is prose. Both used to
+    // land in the index as a team name, and now that the name is rendered on the row
+    // a wrong one is worse than none.
+    // A single character is a doc placeholder (`agents teams create t --host <name>`)
+    // far more often than a real team; an all-digits token is a flag value or a list
+    // index that leaked through, never a name someone typed. Both had reached the
+    // index, and now that the name is rendered a wrong one is worse than none.
+    if (name.length < 2 || /^\d+$/.test(name) || NON_TEAM_WORDS.has(name.toLowerCase()))
+        return undefined;
+    return name;
 }
 /**
  * True when a tool_use call CREATES a tracker ticket — a Linear MCP `create_issue`