@phnx-labs/agents-cli 1.20.85 → 1.20.87

package/dist/commands/teams.js

@@ -1,5 +1,5 @@
 import chalk from 'chalk';
-import { die, relTime, truncate, isJsonMode, padRight } from '../lib/format.js';
+import { dieFriction, relTime, truncate, isJsonMode, padRight } from '../lib/format.js';
 import * as fs from 'fs/promises';
 import { addHostOption } from '../lib/hosts/option.js';
 import * as path from 'path';
@@ -32,6 +32,7 @@ import { buildPreview as buildSessionPreview } from './sessions-picker.js';
 import { parseExecEnv } from '../lib/exec.js';
 import { checkRunAccountReadiness } from '../lib/rotate.js';
 import { teamPicker, printTeamTable } from './teams-picker.js';
+import { teamSpawners } from '../lib/session/db.js';
 import { itemPicker } from '../lib/picker.js';
 import { profileExists, readProfile } from '../lib/profiles.js';
 import { isPromptCancelled, isInteractiveTerminal, requireDestructiveArg, requireInteractiveSelection, } from './utils.js';
@@ -187,10 +188,10 @@ function parseTeammate(spec) {
             };
         }
         catch (err) {
-            die(`Profile '${name}' is malformed: ${err.message}`);
+            dieFriction('teams', 'profile-malformed', `Profile '${name}' is malformed: ${err.message}`);
         }
     }
-    die(`Unknown teammate '${spec}'. Available agents: ${VALID_AGENTS.join(', ')}.\n` +
+    dieFriction('teams', 'unknown-teammate', `Unknown teammate '${spec}'. Available agents: ${VALID_AGENTS.join(', ')}.\n` +
         `  Use 'claude', 'kimi@latest', 'kimi@0.19.2' (a version from 'agents view'), or a profile name.`);
 }
 function shortId(id) {
@@ -840,7 +841,9 @@ function buildTasksFromSnapshots(agents) {
     }
     return tasks.sort((a, b) => new Date(b.modified_at).getTime() - new Date(a.modified_at).getTime());
 }
-export function buildTeamRowsFromSnapshots(registry, agents) {
+export function buildTeamRowsFromSnapshots(registry, agents, 
+/** team name -> the session that spawned it (see teamSpawners). */
+spawners) {
     const byTeam = new Map();
     for (const agent of agents) {
         const details = byTeam.get(agent.task_name) || [];
@@ -854,6 +857,7 @@ export function buildTeamRowsFromSnapshots(registry, agents) {
             team,
             agents: byTeam.get(team.task_name) || [],
             description: registry[team.task_name]?.description,
+            spawnedBy: spawners?.get(team.task_name)?.shortId,
         })),
         names: teams.map((team) => team.task_name),
     };
@@ -908,7 +912,17 @@ async function loadTeamAgentSnapshots() {
 // fallbacks for `status` / `start`; full status stays lazy until a team is picked.
 async function loadTeamRows(_mgr) {
     const [registry, agents] = await Promise.all([loadTeams(), loadTeamAgentSnapshots()]);
-    return buildTeamRowsFromSnapshots(registry, agents);
+    // Lineage is read off the session index, not the team registry: the registry is
+    // per-machine runtime state, while the transcript that ran `teams create` is
+    // indexed, survives the teammate cleanup, and covers teams created before this.
+    let spawners;
+    try {
+        spawners = teamSpawners();
+    }
+    catch {
+        // The index is an enrichment here — a missing/locked DB just drops the column.
+    }
+    return buildTeamRowsFromSnapshots(registry, agents, spawners);
 }
 // Picker fallback for `teams logs` when the teammate ref is omitted. Shows a
 // flat list of every teammate with their team context; Enter picks one.
@@ -1090,7 +1104,16 @@ export function registerTeamsCommands(program) {
             arr.push(a);
             byTeam.set(a.task_name, arr);
         }
-        let rows = buildTeamRowsFromSnapshots(registry, everyAgent).rows;
+        // Same lineage enrichment as loadTeamRows — without it this listing is the
+        // one `teams list` surface that silently drops the "spawned by" column.
+        let spawners;
+        try {
+            spawners = teamSpawners();
+        }
+        catch {
+            // The session index is an enrichment here; a missing one drops the column.
+        }
+        let rows = buildTeamRowsFromSnapshots(registry, everyAgent, spawners).rows;
         // --- query: substring match on team name ---
         if (query) {
             const q = query.toLowerCase();
@@ -1112,7 +1135,7 @@ export function registerTeamsCommands(program) {
             const want = opts.status.toLowerCase();
             const validStatuses = ['working', 'done', 'failed', 'empty'];
             if (!validStatuses.includes(want)) {
-                die(`Invalid --status '${opts.status}'. Use one of: ${validStatuses.join(', ')}`);
+                dieFriction('teams', 'invalid-status-filter', `Invalid --status '${opts.status}'. Use one of: ${validStatuses.join(', ')}`);
             }
             rows = rows.filter((row) => classifyTeamStatus(row.team) === want);
         }
@@ -1120,13 +1143,13 @@ export function registerTeamsCommands(program) {
         if (opts.since) {
             const cutoff = parseTimeFilter(opts.since);
             if (!cutoff)
-                die(`Could not parse --since '${opts.since}'`);
+                dieFriction('teams', 'invalid-since-filter', `Could not parse --since '${opts.since}'`);
             rows = rows.filter((row) => new Date(row.team.modified_at).getTime() >= cutoff);
         }
         if (opts.until) {
             const cutoff = parseTimeFilter(opts.until);
             if (!cutoff)
-                die(`Could not parse --until '${opts.until}'`);
+                dieFriction('teams', 'invalid-until-filter', `Could not parse --until '${opts.until}'`);
             rows = rows.filter((row) => new Date(row.team.modified_at).getTime() <= cutoff);
         }
         rows = rows.slice(0, limit);
@@ -1194,11 +1217,11 @@ export function registerTeamsCommands(program) {
                     continue;
                 const host = await resolveHost(name);
                 if (!host) {
-                    die(`Couldn't resolve pool device "${name}". Register it with \`agents devices\`, ` +
+                    dieFriction('teams', 'pool-device-not-resolvable', `Couldn't resolve pool device "${name}". Register it with \`agents devices\`, ` +
                         `enroll it with \`agents hosts add ${name}\`, or pass user@host.`);
                 }
                 if (remoteShellFor(host.os ?? resolveRemoteOsSync(host.name)) === 'powershell') {
-                    die(`Distributed teams on Windows device "${host.name}" are not supported yet — ` +
+                    dieFriction('teams', 'pool-device-windows-unsupported', `Distributed teams on Windows device "${host.name}" are not supported yet — ` +
                         `the teams remote monitor is POSIX-only. Use a Linux/macOS device.`);
                 }
             }
@@ -1246,7 +1269,7 @@ export function registerTeamsCommands(program) {
             }
         }
         catch (err) {
-            die(err.message);
+            dieFriction('teams', 'create-failed', err.message);
         }
     });
     // add
@@ -1273,29 +1296,29 @@ export function registerTeamsCommands(program) {
         // silently ignoring it — see remoteCwdOnAddError. `!== undefined` so even an
         // explicit empty value (`--remote-cwd ""`) is rejected, not silently dropped.
         if (opts.remoteCwd !== undefined) {
-            die(remoteCwdOnAddError(team));
+            dieFriction('teams', 'remote-cwd-on-add', remoteCwdOnAddError(team));
         }
         if (!VALID_MODES.includes(opts.mode)) {
-            die(`Invalid mode '${opts.mode}'. Use one of: ${VALID_MODES.join(', ')}`);
+            dieFriction('teams', 'invalid-mode', `Invalid mode '${opts.mode}'. Use one of: ${VALID_MODES.join(', ')}`);
         }
         if (!VALID_EFFORTS.includes(opts.effort)) {
-            die(`Invalid effort '${opts.effort}'. Use one of: ${VALID_EFFORTS.join(', ')}`);
+            dieFriction('teams', 'invalid-effort', `Invalid effort '${opts.effort}'. Use one of: ${VALID_EFFORTS.join(', ')}`);
         }
         let taskType = null;
         if (opts.taskType) {
             if (!VALID_TASK_TYPES.includes(opts.taskType)) {
-                die(`Invalid task-type '${opts.taskType}'. Use one of: ${VALID_TASK_TYPES.join(', ')}`);
+                dieFriction('teams', 'invalid-task-type', `Invalid task-type '${opts.taskType}'. Use one of: ${VALID_TASK_TYPES.join(', ')}`);
             }
             taskType = opts.taskType;
         }
         let cloudProviderId = null;
         if (opts.cloud) {
             if (!VALID_CLOUD_PROVIDERS.includes(opts.cloud)) {
-                die(`Invalid cloud provider '${opts.cloud}'. Use one of: ${VALID_CLOUD_PROVIDERS.join(', ')}`);
+                dieFriction('teams', 'invalid-cloud-provider', `Invalid cloud provider '${opts.cloud}'. Use one of: ${VALID_CLOUD_PROVIDERS.join(', ')}`);
             }
             cloudProviderId = opts.cloud;
             if (cloudProviderId === 'rush' && !opts.repo) {
-                die(`--cloud rush requires --repo <owner/repo>`);
+                dieFriction('teams', 'cloud-rush-needs-repo', `--cloud rush requires --repo <owner/repo>`);
             }
         }
         // Auto-create the team if it doesn't exist yet (friendlier UX than erroring),
@@ -1310,7 +1333,7 @@ export function registerTeamsCommands(program) {
             const h = opts.host;
             const d = opts.device;
             if (h && d && h !== d) {
-                die('Conflicting --host/--device values — pass just one.');
+                dieFriction('teams', 'conflicting-host-device', 'Conflicting --host/--device values — pass just one.');
             }
             return h ?? d ?? null;
         })();
@@ -1324,18 +1347,18 @@ export function registerTeamsCommands(program) {
         let hostRepoPath = null;
         if (explicitDevice && explicitDevice.toLowerCase() !== machineId()) {
             if (cloudProviderId) {
-                die(`--device and --cloud are mutually exclusive (two different remote backends). Pick one.`);
+                dieFriction('teams', 'device-cloud-mutually-exclusive', `--device and --cloud are mutually exclusive (two different remote backends). Pick one.`);
             }
             const host = await resolveHost(explicitDevice);
             if (!host) {
-                die(`Couldn't resolve --device "${explicitDevice}". Register it with \`agents devices\`, ` +
+                dieFriction('teams', 'device-not-resolvable', `Couldn't resolve --device "${explicitDevice}". Register it with \`agents devices\`, ` +
                     `enroll it with \`agents hosts add ${explicitDevice}\`, or pass user@host.`);
             }
             // POSIX-only in v1: the remote follow/monitor layer offset-tails the log
             // with tail/cat/kill, which don't exist under PowerShell. Refuse Windows
             // up front, mirroring dispatch.ts launchDetached.
             if (remoteShellFor(host.os ?? resolveRemoteOsSync(host.name)) === 'powershell') {
-                die(`Distributed teammates on Windows host "${host.name}" are not supported yet — ` +
+                dieFriction('teams', 'device-windows-unsupported', `Distributed teammates on Windows host "${host.name}" are not supported yet — ` +
                     `the teams remote monitor is POSIX-only (offset-tails the remote log with tail/cat/kill). ` +
                     `Use a Linux/macOS host, or run this teammate locally.`);
             }
@@ -1343,7 +1366,7 @@ export function registerTeamsCommands(program) {
                 hostTarget = sshTargetFor(host);
             }
             catch (err) {
-                die(`Can't resolve an ssh target for "${host.name}": ${err.message}`);
+                dieFriction('teams', 'ssh-target-unresolvable', `Can't resolve an ssh target for "${host.name}": ${err.message}`);
             }
             // Ensure agents-cli is present + version-matched on the host; surface
             // (not fail on) an agent-not-installed warning, like the run --host path.
@@ -1353,7 +1376,7 @@ export function registerTeamsCommands(program) {
                     process.stderr.write(chalk.yellow(`[teams] warning: ${w}\n`));
             }
             catch (err) {
-                die(`Host "${host.name}" is not ready: ${err.message}`);
+                dieFriction('teams', 'host-not-ready', `Host "${host.name}" is not ready: ${err.message}`);
             }
             // Provision the repo on the host from the team's --repo (clone into
             // ~/.agents/repos/<team> or reuse an existing checkout), resolving to the
@@ -1370,7 +1393,7 @@ export function registerTeamsCommands(program) {
                 hostRepoPath = ensureRemoteRepo(hostTarget, effectiveRepo, team);
             }
             catch (err) {
-                die(`Couldn't provision the repo on "${host.name}": ${err.message}\n` +
+                dieFriction('teams', 'repo-provision-failed', `Couldn't provision the repo on "${host.name}": ${err.message}\n` +
                     `  Set how each device gets the code with: agents teams create ${team} --repo <url|path>`);
             }
             hostName = host.name;
@@ -1380,7 +1403,7 @@ export function registerTeamsCommands(program) {
         // Version-installed check is about the LOCAL machine — a distributed (--on)
         // teammate's agent/version lives on the host, verified by ensureHostReady.
         if (version && !hostName && !isVersionInstalled(agent, version)) {
-            die(`${AGENT_NAMES[agent]} ${version} isn't installed.\n` +
+            dieFriction('teams', 'agent-version-not-installed', `${AGENT_NAMES[agent]} ${version} isn't installed.\n` +
                 `  Install it:  agents add ${agent}@${version}\n` +
                 `  Or see what's installed (incl. @latest):  agents view ${agent}`);
         }
@@ -1404,26 +1427,26 @@ export function registerTeamsCommands(program) {
         }
         if (opts.name !== undefined) {
             if (!opts.name || !/^[A-Za-z0-9_-]+$/.test(opts.name)) {
-                die(`Invalid teammate name '${opts.name}'. Use letters, numbers, '-', or '_'.`);
+                dieFriction('teams', 'invalid-teammate-name', `Invalid teammate name '${opts.name}'. Use letters, numbers, '-', or '_'.`);
             }
         }
         if (opts.worktree !== undefined) {
             if (!opts.worktree || !/^[A-Za-z0-9_-]+$/.test(opts.worktree)) {
-                die(`Invalid worktree name '${opts.worktree}'. Use letters, numbers, '-', or '_'.`);
+                dieFriction('teams', 'invalid-worktree-name', `Invalid worktree name '${opts.worktree}'. Use letters, numbers, '-', or '_'.`);
             }
         }
         const after = opts.after
             ? opts.after.split(',').map((s) => s.trim()).filter(Boolean)
             : [];
         if (after.length > 0 && !opts.name) {
-            die("--after requires --name (dependencies reference teammates by name).");
+            dieFriction('teams', 'after-requires-name', "--after requires --name (dependencies reference teammates by name).");
         }
         let envOverrides;
         try {
             envOverrides = parseExecEnv(opts.env);
         }
         catch (err) {
-            die(err.message);
+            dieFriction('teams', 'invalid-env', err.message);
         }
         // Team already ensured + loaded above (teamMeta) for the --repo provisioning.
         const worktreesEnabled = teamMeta?.enable_worktrees ?? false;
@@ -1436,19 +1459,19 @@ export function registerTeamsCommands(program) {
             // remote teammate; a per-teammate worktree is created ON THE HOST at launch
             // (createRemoteWorktree in launchRemoteProcess) — we just capture its name.
             if (sharedWorktree) {
-                die(`Team '${team}' uses a shared local --use-worktree, which can't apply to a --device (remote) teammate.`);
+                dieFriction('teams', 'shared-worktree-remote-conflict', `Team '${team}' uses a shared local --use-worktree, which can't apply to a --device (remote) teammate.`);
             }
             if (worktreesEnabled) {
                 if (!opts.worktree) {
-                    die(`Team '${team}' has worktrees enabled. Use --worktree <name> for the remote teammate (created on ${hostName}).`);
+                    dieFriction('teams', 'worktree-required-remote', `Team '${team}' has worktrees enabled. Use --worktree <name> for the remote teammate (created on ${hostName}).`);
                 }
                 if (!opts.name) {
-                    die(`Team '${team}' has worktrees enabled. Use --name <name> to identify this teammate.`);
+                    dieFriction('teams', 'name-required-remote', `Team '${team}' has worktrees enabled. Use --name <name> to identify this teammate.`);
                 }
                 worktreeName = opts.worktree;
             }
             else if (opts.worktree) {
-                die(`--worktree requires --enable-worktrees on the team. Recreate the team with: agents teams create ${team} --enable-worktrees`);
+                dieFriction('teams', 'worktree-requires-enable-worktrees', `--worktree requires --enable-worktrees on the team. Recreate the team with: agents teams create ${team} --enable-worktrees`);
             }
             // Local cwd stays null — the remote cwd is repoPath / the remote worktree.
         }
@@ -1458,38 +1481,38 @@ export function registerTeamsCommands(program) {
             try {
                 const stat = await fsp.stat(sharedWorktree);
                 if (!stat.isDirectory()) {
-                    die(`Shared worktree path is not a directory: ${sharedWorktree}`);
+                    dieFriction('teams', 'shared-worktree-not-dir', `Shared worktree path is not a directory: ${sharedWorktree}`);
                 }
             }
             catch {
-                die(`Shared worktree path does not exist: ${sharedWorktree}`);
+                dieFriction('teams', 'shared-worktree-missing', `Shared worktree path does not exist: ${sharedWorktree}`);
             }
             worktreePath = sharedWorktree;
             if (opts.worktree) {
-                die(`Team '${team}' uses --use-worktree (shared). Don't pass --worktree on add.`);
+                dieFriction('teams', 'worktree-on-shared-team', `Team '${team}' uses --use-worktree (shared). Don't pass --worktree on add.`);
             }
         }
         else if (worktreesEnabled) {
             if (!opts.worktree) {
-                die(`Team '${team}' has worktrees enabled. Use --worktree <name> to specify a worktree name.`);
+                dieFriction('teams', 'worktree-required', `Team '${team}' has worktrees enabled. Use --worktree <name> to specify a worktree name.`);
             }
             if (!opts.name) {
-                die(`Team '${team}' has worktrees enabled. Use --name <name> to identify this teammate.`);
+                dieFriction('teams', 'name-required', `Team '${team}' has worktrees enabled. Use --name <name> to identify this teammate.`);
             }
             const baseCwd = opts.cwd ?? process.cwd();
             if (!(await isGitRepo(baseCwd))) {
-                die(`Worktrees require a git repository. ${baseCwd} is not inside a git repo.`);
+                dieFriction('teams', 'worktree-needs-repo', `Worktrees require a git repository. ${baseCwd} is not inside a git repo.`);
             }
             try {
                 worktreeName = opts.worktree;
                 worktreePath = await createWorktree(baseCwd, worktreeName);
             }
             catch (err) {
-                die(`Failed to create worktree '${opts.worktree}': ${err.message}`);
+                dieFriction('teams', 'worktree-create-failed', `Failed to create worktree '${opts.worktree}': ${err.message}`);
             }
         }
         else if (opts.worktree) {
-            die(`--worktree requires --enable-worktrees on the team. Recreate the team with: agents teams create ${team} --enable-worktrees`);
+            dieFriction('teams', 'worktree-requires-enable-worktrees', `--worktree requires --enable-worktrees on the team. Recreate the team with: agents teams create ${team} --enable-worktrees`);
         }
         // Distributed teammates have no LOCAL cwd — their working dir lives on the
         // host (repoPath / the remote worktree). Local teammates default to the
@@ -1541,7 +1564,7 @@ export function registerTeamsCommands(program) {
                 cloudSessionId = cloudTask.id;
             }
             catch (err) {
-                die(`Cloud dispatch failed: ${err.message}`);
+                dieFriction('teams', 'cloud-dispatch-failed', `Cloud dispatch failed: ${err.message}`);
             }
         }
         try {
@@ -1595,7 +1618,7 @@ export function registerTeamsCommands(program) {
             }
         }
         catch (err) {
-            die(`Could not add ${fullName(agent, version)} to ${team}: ${err.message}`);
+            dieFriction('teams', 'add-failed', `Could not add ${fullName(agent, version)} to ${team}: ${err.message}`);
         }
     });
     // status
@@ -1605,20 +1628,22 @@ export function registerTeamsCommands(program) {
         .option('-f, --filter <state>', 'Show only teammates in this state: running, completed, failed, stopped, or all (default: all)', 'all')
         .option('-s, --since <iso>', 'Cursor from a previous status call; only show updates after this timestamp (enables efficient polling)')
         .option('--agent-id <id>', 'Show only this one teammate (by UUID or UUID prefix)')
+        .option('--parent-session <id>', 'Show the teammates spawned BY this session, across teams. Resolves only teammates whose record survives the teams cleanup window.')
         .option('-v, --verbose', 'Emit the full per-teammate detail (prompt, all file paths, all messages). Default is a compact summary.')
         .option('--json', 'Output machine-readable JSON')
         .action(async (team, opts) => {
         const filter = opts.filter;
         const mgr = mkManager();
         // No team given → drop into the picker (TTY) or fail clearly (script).
-        if (!team) {
+        // --parent-session is its own lookup key, so it needs no team at all.
+        if (!team && !opts.parentSession) {
             const picked = await pickTeamOr(mgr, 'agents teams status');
             if (!picked)
                 return;
             team = picked;
         }
         try {
-            const result = await handleStatus(mgr, team, filter, opts.since);
+            const result = await handleStatus(mgr, team, filter, opts.since, opts.parentSession);
             const agents = opts.agentId
                 ? result.agents.filter((a) => a.agent_id.startsWith(opts.agentId))
                 : result.agents;
@@ -1633,20 +1658,31 @@ export function registerTeamsCommands(program) {
                 console.log(JSON.stringify(payload, null, 2));
                 return;
             }
-            const exists = await teamExists(team);
-            if (!exists && result.agents.length === 0) {
-                console.log(chalk.yellow(`No team called '${team}'. Create it with: agents teams create ${team}`));
+            // A --parent-session lookup spans teams, so there is no single team to
+            // check for existence — its label is the session that spawned them.
+            const label = team ?? `session ${opts.parentSession.slice(0, 8)}`;
+            if (team) {
+                const exists = await teamExists(team);
+                if (!exists && result.agents.length === 0) {
+                    console.log(chalk.yellow(`No team called '${team}'. Create it with: agents teams create ${team}`));
+                    return;
+                }
+            }
+            else if (result.agents.length === 0) {
+                console.log(chalk.yellow(`No teammates recorded for ${label}.`));
+                console.log(chalk.gray('Teammate records are cleaned up after 7 days; an older team may have aged out.'));
                 return;
             }
             if (opts.verbose) {
-                await printTeamStatus(team, filtered);
+                await printTeamStatus(label, filtered);
             }
             else {
-                printTeamSummary(team, toTaskStatusSummary(filtered));
+                printTeamSummary(label, toTaskStatusSummary(filtered));
             }
         }
         catch (err) {
-            die(`Could not check on team ${team}: ${err.message}`);
+            // `team` is undefined for a --parent-session lookup, which spans teams.
+            dieFriction('teams', 'status-failed', `Could not check on ${team ? `team ${team}` : 'the requested session'}: ${err.message}`);
         }
     });
     // active — list every live teammate across every team, grouped by team.
@@ -1908,18 +1944,18 @@ export function registerTeamsCommands(program) {
         }
         const lookup = await mgr.resolveAgentIdInTask(team, ref);
         if (lookup.kind === 'none') {
-            die(`No teammate matching '${ref}' in team ${team}`, 2);
+            dieFriction('teams', 'teammate-not-found', `No teammate matching '${ref}' in team ${team}`, 2);
         }
         if (lookup.kind === 'ambiguous') {
             const shorts = lookup.matches.map(shortId).join(', ');
-            die(`'${ref}' matches multiple teammates: ${shorts}. Use more characters or a name.`, 2);
+            dieFriction('teams', 'teammate-ambiguous', `'${ref}' matches multiple teammates: ${shorts}. Use more characters or a name.`, 2);
         }
         const agentId = lookup.agentId;
         const agent = await mgr.get(agentId);
         const display = agent?.name || shortId(agentId);
         const stopRes = await handleStop(mgr, team, agentId);
         if ('error' in stopRes)
-            die(stopRes.error);
+            dieFriction('teams', 'stop-failed', stopRes.error);
         // Clean up worktree if this teammate had one
         let worktreeKept = false;
         if (agent?.worktreeName && agent?.worktreePath) {
@@ -1977,10 +2013,10 @@ export function registerTeamsCommands(program) {
         const mgr = mkManager();
         const lookup = await mgr.resolveAgentIdInTask(team, ref);
         if (lookup.kind === 'none')
-            die(`No teammate matching '${ref}' in team ${team}`, 2);
+            dieFriction('teams', 'teammate-not-found', `No teammate matching '${ref}' in team ${team}`, 2);
         if (lookup.kind === 'ambiguous') {
             const shorts = lookup.matches.map(shortId).join(', ');
-            die(`'${ref}' matches multiple teammates: ${shorts}. Use more characters or a name.`, 2);
+            dieFriction('teams', 'teammate-ambiguous', `'${ref}' matches multiple teammates: ${shorts}. Use more characters or a name.`, 2);
         }
         const agentId = lookup.agentId;
         // mgr.get reconciles the teammate's status (PID + start-time guard / remote
@@ -1988,20 +2024,20 @@ export function registerTeamsCommands(program) {
         // is a fact, not a guess.
         const agent = await mgr.get(agentId);
         if (!agent)
-            die(`Teammate ${shortId(agentId)} vanished from team ${team}.`);
+            dieFriction('teams', 'teammate-vanished', `Teammate ${shortId(agentId)} vanished from team ${team}.`);
         const display = agent.name || shortId(agentId);
         const status = agent.status;
         const hasMessage = message != null && message.trim().length > 0;
         const route = decideTeamMessageRoute(status, hasMessage);
         switch (route.kind) {
             case 'not-started':
-                die(`Teammate '${display}' hasn't started yet (waiting on --after deps). Run \`agents teams start ${team}\` to launch it.`);
+                dieFriction('teams', 'teammate-not-started', `Teammate '${display}' hasn't started yet (waiting on --after deps). Run \`agents teams start ${team}\` to launch it.`);
                 return;
             case 'need-message':
                 if (status === AgentStatus.RUNNING) {
-                    die(`Teammate '${display}' is running — pass a message to steer it.`);
+                    dieFriction('teams', 'steer-needs-message', `Teammate '${display}' is running — pass a message to steer it.`);
                 }
-                die(`Teammate '${display}' is ${status} — pass a message to resume it: \`agents teams resume ${team} ${display} "<message>"\`.`);
+                dieFriction('teams', 'resume-needs-message', `Teammate '${display}' is ${status} — pass a message to resume it: \`agents teams resume ${team} ${display} "<message>"\`.`);
                 return;
             case 'steer': {
                 // Running -> steer via mailbox; never re-launch (that forks a 2nd session).
@@ -2020,7 +2056,7 @@ export function registerTeamsCommands(program) {
                     await mgr.resumeTeammate(agentId, message);
                 }
                 catch (err) {
-                    die(err.message);
+                    dieFriction('teams', 'resume-failed', err.message);
                 }
                 if (isJsonMode(opts)) {
                     console.log(JSON.stringify({ team, agent_id: agentId, name: agent.name ?? null, action: 'resume', prior_status: status }, null, 2));
@@ -2079,18 +2115,18 @@ export function registerTeamsCommands(program) {
         }
         const lookup = await mgr.resolveAgentIdInTask(team, ref);
         if (lookup.kind === 'none') {
-            die(`No teammate matching '${ref}' in team ${team}`, 2);
+            dieFriction('teams', 'teammate-not-found', `No teammate matching '${ref}' in team ${team}`, 2);
         }
         if (lookup.kind === 'ambiguous') {
             const shorts = lookup.matches.map(shortId).join(', ');
-            die(`'${ref}' matches multiple teammates: ${shorts}. Use more characters or a name.`, 2);
+            dieFriction('teams', 'teammate-ambiguous', `'${ref}' matches multiple teammates: ${shorts}. Use more characters or a name.`, 2);
         }
         const agentId = lookup.agentId;
         const agent = await mgr.get(agentId);
         const display = agent?.name || shortId(agentId);
         // Require agent to be stopped first
         if (agent?.status === 'running' || agent?.status === 'pending') {
-            die(`Teammate '${display}' is still ${agent.status}. Run 'agents teams stop ${team} ${display}' first.`);
+            dieFriction('teams', 'remove-still-running', `Teammate '${display}' is still ${agent.status}. Run 'agents teams stop ${team} ${display}' first.`);
         }
         if (!opts.keepLogs) {
             try {
@@ -2128,7 +2164,7 @@ export function registerTeamsCommands(program) {
         }
         const stopRes = await handleStop(mgr, team);
         if ('error' in stopRes)
-            die(stopRes.error);
+            dieFriction('teams', 'stop-failed', stopRes.error);
         const status = await handleStatus(mgr, team, 'all');
         // Clean up worktrees for all teammates
         const baseCwd = process.cwd();
@@ -2176,7 +2212,7 @@ export function registerTeamsCommands(program) {
             return;
         }
         if (!existed && stopRes.stopped.length === 0 && status.agents.length === 0) {
-            die(`No team called '${team}'`, 2);
+            dieFriction('teams', 'team-not-found', `No team called '${team}'`, 2);
         }
         console.log(chalk.green(`Team ${chalk.cyan(team)} disbanded.`));
         if (stopRes.stopped.length)
@@ -2214,11 +2250,11 @@ export function registerTeamsCommands(program) {
         else {
             const resolved = await resolveTeammateAcrossTeams(base, teammateRef, opts.team);
             if (resolved.kind === 'none') {
-                die(`No notes on record for teammate '${teammateRef}'`, 2);
+                dieFriction('teams', 'teammate-notes-not-found', `No notes on record for teammate '${teammateRef}'`, 2);
             }
             if (resolved.kind === 'ambiguous') {
                 const hints = resolved.candidates.map((c) => `${c.team}/${c.display}`).join(', ');
-                die(`'${teammateRef}' matches multiple teammates: ${hints}.\n` +
+                dieFriction('teams', 'teammate-notes-ambiguous', `'${teammateRef}' matches multiple teammates: ${hints}.\n` +
                     `  Narrow it with --team <team>, or pass a UUID prefix.`, 2);
             }
             agentId = resolved.agentId;
@@ -2249,7 +2285,7 @@ export function registerTeamsCommands(program) {
             process.stdout.write(lines.slice(-n).join('\n'));
         }
         catch {
-            die(`No notes on record for teammate '${teammateRef ?? agentId}' (looked in ${logPath})`, 2);
+            dieFriction('teams', 'teammate-notes-not-found', `No notes on record for teammate '${teammateRef ?? agentId}' (looked in ${logPath})`, 2);
         }
     });
     // doctor

package/dist/commands/view.js

@@ -5,7 +5,7 @@ import ora from 'ora';
 import * as fs from 'fs';
 import * as path from 'path';
 import { AGENTS, ALL_AGENT_IDS, accountDisplayLabel, getAllCliStates, getUnmanagedCliState, getAccountInfo, resolveAgentName, formatAgentError, agentLabel, colorAgent, } from '../lib/agents.js';
-import { loginHint } from '../lib/signin-badge.js';
+import { ambientClaudeToken, loginHint } from '../lib/signin-badge.js';
 import { machineId } from '../lib/machine-id.js';
 import { authCacheKey, formatCheckedAge, readAuthHealthCache } from '../lib/auth-health.js';
 import { agentReportsUsage, deriveUsageStatusFromSnapshot, formatUsageSection, formatUsageSummary, formatUsageStatusBadge, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, } from '../lib/usage.js';
@@ -530,8 +530,19 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
                 if (runDefaults.mode)
                     runDefaultBits.push(`mode:${runDefaults.mode}`);
                 if (!hasEmail && !hasUsage && !signedIn) {
-                    // Installed but never signed in
-                    parts.push(chalk.gray('(logged out — log in with: ' + loginHint(agentId) + ')'));
+                    // No per-version credential. That is NOT the same as unusable: Claude
+                    // Code authenticates from `CLAUDE_CODE_OAUTH_TOKEN` when the
+                    // environment carries one, and a run then succeeds against whatever
+                    // account minted that token — while `signedIn` (agents.ts: `!!email`,
+                    // read from this version home's `.claude.json`) stays false because no
+                    // account was ever written here. Reporting that as "logged out" reads
+                    // as a locked-out account and sends people hunting a login that is not
+                    // missing; naming the ambient token instead points at the real state —
+                    // every version on this box resolves to the SAME account, so balanced
+                    // rotation across them is not actually rotating.
+                    parts.push(chalk.gray(ambientClaudeToken(agentId)
+                        ? '(no per-version login — using ambient CLAUDE_CODE_OAUTH_TOKEN)'
+                        : '(logged out — log in with: ' + loginHint(agentId) + ')'));
                 }
                 else {
                     if (hasEmail || hasUsage || hasActive || signedIn) {

package/dist/index.js

@@ -98,7 +98,7 @@ import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedbac
 import { applyGlobalHelpConventions } from './lib/help.js';
 import { renderWhatsNew } from './lib/whats-new.js';
 import { getCliLaunch } from './lib/cli-entry.js';
-import { emit, redactArgs } from './lib/events.js';
+import { emit, emitFriction, redactArgs } from './lib/events.js';
 // Transparent shim delegate: the generated Windows `.cmd` shims invoke
 // `agents __shim <agent>[@version] <raw args>`. Intercept here, before commander
 // parses anything, so the agent's own flags (`--help`, `--version`, etc.) pass
@@ -691,6 +691,32 @@ function registerResourcesTombstoneCommand(p) {
         await program.parseAsync(['node', 'agents', ...args]);
     });
 }
+/**
+ * Hidden `agents _internal <sub>` namespace for machine-to-machine calls that
+ * are not user-facing. The first subcommand is `friction`, used by shell guard
+ * hooks (git-guard, rm-guard, …) to self-report a block into the event log
+ * before they exit 2 — they run before any `agents` process exists, so they
+ * cannot emit in-process.
+ */
+function registerInternalCommand(p) {
+    const internal = p.command('_internal', { hidden: true });
+    internal
+        .command('friction')
+        .option('--surface <surface>', 'Subsystem that hit the failure (e.g. guard, teams)')
+        .option('--id <failureId>', 'Stable failure slug (e.g. git.reset-hard)')
+        .option('--error <message>', 'Human-readable failure reason')
+        .option('--command <command>', 'The command that was blocked')
+        .action((opts) => {
+        if (!opts.surface || !opts.id) {
+            process.exit(0); // fail-open: never break the caller
+        }
+        emitFriction(opts.surface, opts.id, {
+            ...(opts.error ? { error: opts.error } : {}),
+            ...(opts.command ? { command: opts.command } : {}),
+        });
+        process.exit(0);
+    });
+}
 /** Self-upgrade command (`agents upgrade [version]`). */
 function registerUpgradeCommand(p) {
     p.command('upgrade')
@@ -784,6 +810,9 @@ async function registerEagerForRequest(name) {
             registerResourcesTombstoneCommand(program);
             await reg(loadView);
             return true;
+        case '_internal':
+            registerInternalCommand(program);
+            return true;
         case 'upgrade':
             registerUpgradeCommand(program);
             return true;
@@ -878,6 +907,7 @@ async function registerAllEagerCommands() {
     await reg(loadSsh);
     registerJobsCronAliasCommand(program, 'jobs');
     registerJobsCronAliasCommand(program, 'cron');
+    registerInternalCommand(program);
     registerUpgradeCommand(program);
     await reg(loadPull);
     await reg(loadPush);