@phnx-labs/agents-cli 1.22.35 → 1.22.37

package/dist/commands/teams.js

@@ -13,16 +13,17 @@ import { runSupervisor } from '../lib/teams/supervisor.js';
 import { debug } from '../lib/teams/debug.js';
 import { runPrWatch, DEFAULT_MAX_WAVES, } from '../lib/teams/pr-watch.js';
 import { handleSpawn, handleStatus, handleStop, toTaskStatusSummary, } from '../lib/teams/api.js';
+import { resolveTeammateDelivery, deliveryDisplayLabel, deliveryColorKey, } from '../lib/teams/delivery.js';
 import { createTeam, ensureTeam, getTeam, loadTeams, removeTeam, teamExists, } from '../lib/teams/registry.js';
 import { setHelpSections } from '../lib/help.js';
-import { createWorktree, isGitRepo, hasUncommittedChanges, removeWorktree, worktreeCheckoutExists, worktreeExists, } from '../lib/teams/worktree.js';
+import { createWorktree, commitsBehindDefault, isGitRepo, hasUncommittedChanges, removeWorktree, worktreeCheckoutExists, worktreeExists, } from '../lib/teams/worktree.js';
 import { resolveHost } from '../lib/hosts/registry.js';
 import { isDeviceAuto, resolveDeviceAuto } from '../lib/smart-launch.js';
 import { sshTargetFor } from '../lib/hosts/types.js';
 import { ensureHostReady } from '../lib/hosts/ready.js';
 import { remoteShellFor } from '../lib/hosts/remote-cmd.js';
 import { resolveRemoteOsSync } from '../lib/hosts/remote-os.js';
-import { remoteWorktreeDirty, removeRemoteWorktree, ensureRemoteRepo } from '../lib/teams/remoteWorktree.js';
+import { remoteWorktreeDirty, removeRemoteWorktree, ensureRemoteRepo, remoteCommitsBehindDefault } from '../lib/teams/remoteWorktree.js';
 import { getRemoteUrl } from '../lib/git.js';
 import { machineId } from '../lib/session/sync/config.js';
 import { isVersionInstalled, resolveVersionAlias, resolveVersionAliasLoose } from '../lib/versions.js';
@@ -59,6 +60,7 @@ function statusColor(status) {
         case 'pending': return chalk.blue;
         case 'running': return chalk.yellow;
         case 'completed': return chalk.green;
+        case 'pr_open': return chalk.magenta; // RUSH-2380: process done, PR not merged
         case 'failed': return chalk.red;
         case 'stopped': return chalk.gray;
         default: return chalk.white;
@@ -299,6 +301,57 @@ function warnOrphanWorktree(baseCwd, name, reason) {
         `  Remove it manually: git -C ${baseCwd} worktree remove --force .agents/worktrees/${name} ` +
         `&& git -C ${baseCwd} branch -D agents/${name}\n`));
 }
+/** Pluralize a commit count: "1 commit" / "3 commits". */
+function commitsWord(behind) {
+    return `${behind} commit${behind === 1 ? '' : 's'}`;
+}
+/**
+ * The blocking message when `teams add` is pointed at a stale checkout. Pure so
+ * the guidance is pinned by tests (mirrors `remoteCwdOnAddError`): it MUST name
+ * how far behind, tell the caller to sync with remote main, and mention `--confirm`
+ * as the override.
+ */
+export function staleRepoError(params) {
+    return (`${params.where} is ${commitsWord(params.behind)} behind origin/${params.base}. ` +
+        `A team started here would build on stale code — bring it up to date with remote main first:\n` +
+        `  ${params.sync}\n` +
+        `Then re-run \`agents teams add ${params.team} …\`, or pass --confirm to start on the stale repo anyway.`);
+}
+/**
+ * Guard against pointing a team at a stale checkout. Before a teammate is bound
+ * to a repo, this fetches origin and counts how far behind `origin/<default>` the
+ * base checkout is (the local cwd, or the repo provisioned on a `--device` host).
+ * If it is behind and the caller did NOT pass `--confirm`, the add is refused with
+ * {@link staleRepoError} — because a team started on stale code reasons and builds
+ * against a tree that has already moved on (the 71-commit-stale s1 checkout
+ * incident). With `--confirm` it prints a one-line advisory and proceeds.
+ *
+ * A `null` behind-count (offline, non-repo, unreachable host) is "can't tell" and
+ * never blocks — this is a freshness nudge, not a hard prerequisite.
+ */
+async function assertRepoFreshOrConfirm(params) {
+    const { team, confirm, json } = params;
+    const res = params.remote
+        ? remoteCommitsBehindDefault(params.remote.target, params.remote.repoPath, {
+            extraSshArgs: params.remote.extraSshArgs,
+        })
+        : params.local
+            ? await commitsBehindDefault(params.local)
+            : null;
+    if (!res || res.behind <= 0)
+        return;
+    const where = params.remote
+        ? `The repo on ${params.remote.host} (${params.remote.repoPath})`
+        : `This checkout (${params.local})`;
+    const sync = params.remote
+        ? `agents ssh ${params.remote.host} 'git -C ${params.remote.repoPath} merge --ff-only origin/${res.base}'`
+        : `git -C ${params.local} merge --ff-only origin/${res.base}`;
+    if (confirm) {
+        process.stderr.write(chalk.yellow(`⚠ ${where} is ${commitsWord(res.behind)} behind origin/${res.base}; starting anyway (--confirm).\n`));
+        return;
+    }
+    dieFriction('teams', 'repo-stale', staleRepoError({ team, where, behind: res.behind, base: res.base, sync }), 1, { json });
+}
 /**
  * Register the generic cloud dispatcher — staged cloud teammates get
  * dispatched when their --after deps resolve, using repo/branch stored on
@@ -526,7 +579,14 @@ async function reactWithTeammate(mgr, team, action, prompt) {
     }
     let result;
     try {
-        result = await handleSpawn(mgr, team, 'claude', prompt, cwd, 'edit', 'medium', null, cwd, null, name, after, null, null, taskType, null, null, null, null, worktreeName, worktreePath);
+        result = await handleSpawn(mgr, team, 'claude', prompt, cwd, 'edit', 'medium', null, cwd, null, name, after, null, null, taskType, null, null, null, null, worktreeName, worktreePath, null, // profileName
+        null, // hostName
+        null, // hostTarget
+        null, // repoPath
+        // A pr-watch fixer belongs to the same team, so it gets the same project
+        // grants as any other teammate. Wiring `--project` into only the
+        // `teams add` caller would have left this one silently without them.
+        (await getTeam(team))?.project ?? null);
     }
     catch (err) {
         // The spawn failed after we created this fixer's worktree — tear it down so
@@ -617,7 +677,11 @@ async function resolveTeammateAcrossTeams(base, ref, teamHint) {
 //     ! reported an error             (if flagged)
 //     PR: <url>                       (if set)
 function printAgentDetail(a, session) {
-    const label = statusColor(a.status)(a.status.toUpperCase());
+    // RUSH-2380: process COMPLETED + open PR → show PR OPEN, not COMPLETED.
+    const delivery = a.delivery ??
+        resolveTeammateDelivery({ status: a.status, prUrl: a.pr_url });
+    const colorKey = deliveryColorKey(delivery, a.status);
+    const label = statusColor(colorKey)(deliveryDisplayLabel(delivery, a.status));
     const who = fullName(a.agent_type, a.version);
     const h = displayHandle(a);
     const secondary = a.name ? chalk.gray(`(${shortId(a.agent_id)})`) : '';
@@ -722,7 +786,10 @@ async function resolveTeammateSessions(agents) {
 // last." Caller passes the projected AgentStatusSummary; for the full
 // verbose layout use printAgentDetail above.
 function printAgentSummary(s) {
-    const label = statusColor(s.status)(s.status.toUpperCase());
+    const delivery = s.delivery ??
+        resolveTeammateDelivery({ status: s.status, prUrl: s.pr_url });
+    const colorKey = deliveryColorKey(delivery, s.status);
+    const label = statusColor(colorKey)(deliveryDisplayLabel(delivery, s.status));
     const handle = s.name ?? shortId(s.agent_id);
     const ident = s.name ? chalk.gray(`(${shortId(s.agent_id)})`) : '';
     const duration = s.duration ? `${chalk.gray(' · ')}${chalk.white(s.duration)}` : '';
@@ -1282,9 +1349,22 @@ export function registerTeamsCommands(program) {
         .option('--devices <list>', 'Pool of machines this team may run teammates on (comma-separated). Enables distributed auto-scheduling.')
         .option('--hosts <list>', 'Alias for --devices.')
         .option('--repo <urlOrPath>', 'How each remote (--device) teammate gets the code — ONE git URL/path for the whole team (existing checkout reused, else cloned). A team is single-repo; for work across repos, make one team per repo. Defaults to this checkout origin.')
+        .option('--project <slug>', "Work this team on a defined project: its primary directory is each local teammate's base cwd, its other directories become --add-dir grants")
         .option('--json', 'Output machine-readable JSON')
         .action(async (team, opts) => {
         try {
+            // Fail here, not at the first `teams add`: a team created against a
+            // project that does not resolve would silently fall back to the
+            // orchestrator's cwd for every teammate.
+            if (opts.project) {
+                const { resolveProjectRef } = await import('../lib/project-root.js');
+                try {
+                    await resolveProjectRef(opts.project, { forRemote: false });
+                }
+                catch (err) {
+                    dieFriction('teams', 'project-unresolved', err.message);
+                }
+            }
             // --devices / --hosts are aliases; commander can't express a two-name
             // option that isn't a short flag, so merge them here. Split on comma,
             // trim, drop blanks, dedupe (preserving first-seen order).
@@ -1302,8 +1382,8 @@ export function registerTeamsCommands(program) {
                     continue;
                 const host = await resolveHost(name);
                 if (!host) {
-                    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.`);
+                    dieFriction('teams', 'pool-device-not-resolvable', `Couldn't resolve pool device "${name}". Register it with \`agents devices add ${name} <target>\`, ` +
+                        `or pass user@host.`);
                 }
                 if (remoteShellFor(host.os ?? resolveRemoteOsSync(host.name)) === 'powershell') {
                     dieFriction('teams', 'pool-device-windows-unsupported', `Distributed teams on Windows device "${host.name}" are not supported yet — ` +
@@ -1328,6 +1408,7 @@ export function registerTeamsCommands(program) {
                 useWorktree: opts.useWorktree,
                 devices,
                 repo,
+                project: opts.project,
             });
             if (isJsonMode(opts)) {
                 console.log(JSON.stringify({ team, ...meta }, null, 2));
@@ -1344,6 +1425,8 @@ export function registerTeamsCommands(program) {
                 console.log(chalk.gray(`  devices: ${meta.devices.join(', ')}`));
             if (meta.repo)
                 console.log(chalk.gray(`  repo: ${meta.repo}`));
+            if (meta.project)
+                console.log(chalk.gray(`  project: ${meta.project}`));
             console.log();
             console.log(chalk.gray('Add your first teammate:'));
             if (meta.enable_worktrees) {
@@ -1374,6 +1457,7 @@ export function registerTeamsCommands(program) {
         .option('--repo <owner/repo>', 'GitHub repository (required for --cloud rush)')
         .option('--branch <name>', 'Target git branch for cloud dispatch')
         .option('--force', "Skip the advisory 'may not be signed in' / 'account throttled' warnings")
+        .option('--confirm', 'Proceed even when the base checkout/repo is behind origin/main (a stale repo otherwise blocks the add)')
         .option('--json', 'Output machine-readable JSON')
         .action(async (team, teammate, task, opts) => {
         // `--remote-cwd` rides the shared --host option family but is never read by
@@ -1440,14 +1524,15 @@ export function registerTeamsCommands(program) {
         let hostName = null;
         let hostTarget = null;
         let hostRepoPath = null;
+        let hostExtraSshArgs = [];
         if (explicitDevice && explicitDevice.toLowerCase() !== machineId()) {
             if (cloudProviderId) {
                 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) {
-                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.`);
+                dieFriction('teams', 'device-not-resolvable', `Couldn't resolve --device "${explicitDevice}". Register it with \`agents devices add ${explicitDevice} <target>\`, ` +
+                    `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
@@ -1491,9 +1576,12 @@ export function registerTeamsCommands(program) {
             if (!effectiveRepo && (await isGitRepo(process.cwd()))) {
                 effectiveRepo = (await getRemoteUrl(process.cwd())) ?? '';
             }
+            // Capture the ssh args ensureRemoteRepo uses so the staleness probe below
+            // reaches the host with the same identity.
+            hostExtraSshArgs = host.identityFile ? ['-i', host.identityFile, '-o', 'IdentitiesOnly=yes'] : [];
             try {
                 hostRepoPath = ensureRemoteRepo(hostTarget, effectiveRepo, team, {
-                    extraSshArgs: host.identityFile ? ['-i', host.identityFile, '-o', 'IdentitiesOnly=yes'] : [],
+                    extraSshArgs: hostExtraSshArgs,
                 });
             }
             catch (err) {
@@ -1570,6 +1658,25 @@ export function registerTeamsCommands(program) {
         catch (err) {
             dieFriction('teams', 'add-precondition-failed', err.message);
         }
+        // Stale-repo guard: refuse to point a team at a checkout behind origin/main
+        // unless --confirm. A cloud teammate clones fresh in the provider, so it has
+        // no local/remote checkout to assess — skip it there.
+        if (!cloudProviderId) {
+            if (hostName) {
+                await assertRepoFreshOrConfirm({
+                    team,
+                    confirm: Boolean(opts.confirm),
+                    json: isJsonMode(opts),
+                    remote: { target: hostTarget, repoPath: hostRepoPath, host: hostName, extraSshArgs: hostExtraSshArgs },
+                });
+            }
+            else {
+                const base = sharedWorktree ?? opts.cwd ?? process.cwd();
+                if (await isGitRepo(base)) {
+                    await assertRepoFreshOrConfirm({ team, confirm: Boolean(opts.confirm), json: isJsonMode(opts), local: base });
+                }
+            }
+        }
         // Track a worktree WE create in this add so a later failure (dep race,
         // launch error, cloud dispatch) can tear it down instead of stranding the
         // branch. Only a worktree THIS add created is ever torn down, so a
@@ -1674,10 +1781,32 @@ export function registerTeamsCommands(program) {
         else if (opts.worktree) {
             dieFriction('teams', 'worktree-requires-enable-worktrees', `--worktree requires --enable-worktrees on the team. Recreate the team with: agents teams create ${team} --enable-worktrees`);
         }
+        // The team's project (`teams create --project`) contributes a base cwd and
+        // the access grants for its other directories. It sits BELOW --cwd in the
+        // precedence chain: an explicit --cwd on this teammate still wins.
+        //
+        // Grants are attached even when a worktree or --cwd owns the cwd — the
+        // sibling repos are what the project binds, not where the teammate sits.
+        // Only the base cwd is resolved here — a LOCAL teammate needs a concrete
+        // directory to start in. The GRANTS are deliberately not resolved now:
+        // an unpinned teammate on a --devices pool is placed at launch, so its
+        // shape (absolute vs ~/…) is not yet knowable. The project name rides on
+        // the record and resolveTeammateGrants resolves it per launch.
+        let projectCwd;
+        if (teamMeta?.project && !hostName) {
+            const { resolveProjectRef } = await import('../lib/project-root.js');
+            try {
+                projectCwd = await resolveProjectRef(teamMeta.project, { forRemote: false });
+            }
+            catch (err) {
+                dieFriction('teams', 'project-unresolved', err.message);
+            }
+        }
         // Distributed teammates have no LOCAL cwd — their working dir lives on the
         // host (repoPath / the remote worktree). Local teammates default to the
-        // worktree path, then --cwd, then the current directory.
-        const cwd = hostName ? null : (worktreePath ?? opts.cwd ?? process.cwd());
+        // worktree path, then --cwd, then the project's primary directory, then
+        // the current directory.
+        const cwd = hostName ? null : (worktreePath ?? opts.cwd ?? projectCwd ?? process.cwd());
         // Factory teammates: prepend the worker-skill preamble to every task
         // prompt so implementers/testers/reviewers know about the Ledger, the
         // dynamic DAG, and the pattern for filing new tasks mid-flight. No
@@ -1735,7 +1864,7 @@ export function registerTeamsCommands(program) {
             }
         }
         try {
-            const result = await handleSpawn(mgr, team, agent, effectiveTask, cwd, opts.mode, opts.effort, null, cwd, version, opts.name ?? null, after, opts.model ?? null, envOverrides ?? null, taskType, cloudProviderId, cloudSessionId, opts.repo ?? null, opts.branch ?? null, worktreeName, worktreePath, profileName, hostName, hostTarget, hostRepoPath);
+            const result = await handleSpawn(mgr, team, agent, effectiveTask, cwd, opts.mode, opts.effort, null, cwd, version, opts.name ?? null, after, opts.model ?? null, envOverrides ?? null, taskType, cloudProviderId, cloudSessionId, opts.repo ?? null, opts.branch ?? null, worktreeName, worktreePath, profileName, hostName, hostTarget, hostRepoPath, teamMeta?.project ?? null);
             emit('teams.add', { module: 'teams', team, agent, name: result.name, agent_id: result.agent_id, status: result.status });
             if (isJsonMode(opts)) {
                 console.log(JSON.stringify(result, null, 2));
@@ -1920,6 +2049,24 @@ export function registerTeamsCommands(program) {
                 return;
             team = picked;
         }
+        // RUSH-2450: a disbanded team must not be re-startable. Orphan PENDING
+        // records can no longer resurrect after purge + saveMeta guard, but if a
+        // caller still points start at a gone team name, fail loud with a reason
+        // instead of launching nothing and looking successful.
+        if (!(await teamExists(team))) {
+            const orphanCount = (await mgr.listByTask(team)).length;
+            const msg = orphanCount > 0
+                ? `Team '${team}' is not registered (disbanded?). ${orphanCount} orphan teammate record(s) remain on disk — re-create the team or purge them before starting.`
+                : `Team '${team}' is not registered (disbanded or never created). Nothing to start.`;
+            if (isJsonMode(opts)) {
+                console.log(JSON.stringify({ team, error: 'team-not-found', message: msg, orphan_teammates: orphanCount }));
+            }
+            else {
+                dieFriction('teams', 'team-not-found', msg, 2);
+            }
+            process.exitCode = 1;
+            return;
+        }
         if (!opts.force && !isJsonMode(opts)) {
             await warnUnsignedTeammates(mgr, team);
             await warnThrottledTeammates(mgr, team);
@@ -2366,11 +2513,14 @@ export function registerTeamsCommands(program) {
         const stopRes = await handleStop(mgr, team);
         if ('error' in stopRes)
             dieFriction('teams', 'stop-failed', stopRes.error);
+        // Snapshot the roster once for worktree cleanup + messaging. Purge below
+        // is the terminal removal of teammate records (RUSH-2450).
         const status = await handleStatus(mgr, team, 'all');
+        const rosterBefore = status.agents;
         // Clean up worktrees for all teammates
         const baseCwd = process.cwd();
         const keptWorktrees = [];
-        for (const a of status.agents) {
+        for (const a of rosterBefore) {
             const agent = await mgr.get(a.agent_id);
             if (agent?.worktreeName && agent?.worktreePath) {
                 try {
@@ -2397,30 +2547,37 @@ export function registerTeamsCommands(program) {
                 catch { /* best-effort */ }
             }
         }
-        const removedIds = [];
-        if (!opts.keepLogs) {
-            const base = await getAgentsDir();
-            for (const a of status.agents) {
-                try {
-                    await fs.rm(path.join(base, a.agent_id), { recursive: true, force: true });
-                    removedIds.push(a.agent_id);
-                }
-                catch { /* best-effort */ }
-            }
-        }
+        // Drop the registry entry FIRST so any concurrent supervisor's saveMeta
+        // (RUSH-2450) refuses to re-persist teammates for this team, then purge
+        // the durable teammate records + in-memory cache. Order matters: purge
+        // after removeTeam closes the race where a supervisor re-writes meta
+        // between the two steps.
         const existed = await removeTeam(team);
+        const removedIds = await mgr.purgeByTask(team, { keepLogs: Boolean(opts.keepLogs) });
         if (isJsonMode(opts)) {
-            console.log(JSON.stringify({ team, existed, stopped: stopRes.stopped, removed_members: removedIds }, null, 2));
+            console.log(JSON.stringify({
+                team,
+                existed,
+                stopped: stopRes.stopped,
+                removed_members: removedIds,
+                already_gone: !existed && rosterBefore.length === 0 && removedIds.length === 0,
+            }, null, 2));
             return;
         }
-        if (!existed && stopRes.stopped.length === 0 && status.agents.length === 0) {
-            dieFriction('teams', 'team-not-found', `No team called '${team}'`, 2);
+        if (!existed && stopRes.stopped.length === 0 && rosterBefore.length === 0 && removedIds.length === 0) {
+            // Second disband on a fully-gone team: clean no-op, not a false success
+            // that claims N logs were cleared again.
+            dieFriction('teams', 'team-not-found', `No team called '${team}' (already disbanded or never created)`, 2);
         }
         console.log(chalk.green(`Team ${chalk.cyan(team)} disbanded.`));
         if (stopRes.stopped.length)
             console.log(chalk.gray(`  Stopped ${stopRes.stopped.length} working teammate(s).`));
-        if (removedIds.length)
-            console.log(chalk.gray(`  Cleared ${removedIds.length} teammate log(s).`));
+        if (removedIds.length && !opts.keepLogs) {
+            console.log(chalk.gray(`  Cleared ${removedIds.length} teammate record(s).`));
+        }
+        else if (removedIds.length && opts.keepLogs) {
+            console.log(chalk.gray(`  Removed ${removedIds.length} teammate record(s); logs kept.`));
+        }
         if (keptWorktrees.length) {
             console.log(chalk.yellow(`  Kept ${keptWorktrees.length} worktree(s) with uncommitted changes: ${keptWorktrees.join(', ')}`));
         }

package/dist/commands/tickets.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerTicketsCommand(program: Command): void;

package/dist/commands/tickets.js

@@ -0,0 +1,43 @@
+import { setHelpSections } from '../lib/help.js';
+import { listTickets } from '../lib/tickets/list.js';
+export function registerTicketsCommand(program) {
+    const tickets = program
+        .command('tickets')
+        .description('Read work items from the trackers linked to this workspace.');
+    setHelpSections(tickets, {
+        examples: `
+      agents tickets list --json
+      agents tickets list --github-assigned-only --json
+    `,
+        notes: `
+      The response reports each source's availability explicitly. A failed tracker
+      never makes another tracker's rows disappear.
+    `,
+    });
+    tickets
+        .command('list')
+        .description('List workspace tickets from Linear and GitHub.')
+        .option('--cwd <path>', 'Workspace used to resolve tracker context')
+        .option('--no-linear', 'Exclude Linear tickets')
+        .option('--no-github', 'Exclude GitHub issues')
+        .option('--github-assigned-only', 'Only include GitHub issues assigned to the current user')
+        .option('--json', 'Output machine-readable tickets, cycle metadata, and source availability')
+        .action(async (options) => {
+        const result = await listTickets({
+            cwd: options.cwd ?? process.cwd(),
+            linear: options.linear,
+            github: options.github,
+            githubAssignedOnly: options.githubAssignedOnly === true,
+        });
+        if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(`${result.tickets.length} ticket${result.tickets.length === 1 ? '' : 's'}`);
+        for (const source of ['linear', 'github']) {
+            const status = result.sources[source];
+            if (!status.available && status.error)
+                console.error(`${source}: ${status.error}`);
+        }
+    });
+}

package/dist/commands/update.js

@@ -83,7 +83,6 @@ export function registerUpdateCommand(program) {
         .command('update [target]')
         .description('Move a frozen agent installation to a new release, keeping its name and every reference to it')
         .option('--to <release>', 'Release to move to: latest (default), oldest, or an exact version')
-        .option('--account <label>', 'Disambiguate by signed-in account when several installations match')
         .option('--json', 'Machine-readable result')
         .action(async (target, options) => {
         try {
@@ -96,7 +95,7 @@ export function registerUpdateCommand(program) {
                 // and reporting it as the pin that was asked for.
                 throw new Error(`${agent} is a single self-updating binary with no pinnable releases — drop --to, or pass --to latest.`);
             }
-            const installation = await resolveInstallation(agent, selector, { account: options.account });
+            const installation = await resolveInstallation(agent, selector);
             const strategy = selectUpdateStrategy(agent);
             if (!options.json && !strategy.transactional) {
                 console.log(chalk.yellow(`${agent} installs one vendor-managed binary, so this update cannot be staged or rolled back; `
@@ -137,12 +136,11 @@ export function registerUpdateCommand(program) {
         examples: `agents update list claude
 agents update claude@2.0.65
 agents update claude@2.0.65 --to 2.1.220
-agents update claude --account work
 agents update claude@2.0.65 --json`,
         notes: 'An installation keeps its name for life; only the release inside it moves. That is why a default, a project pin, '
             + 'a routine version, or a profile that names claude@2.0.65 keeps working after you update it. '
             + 'The selector matches either the installation name or the release it currently carries — when two installations '
-            + 'share a release, name one or pass --account <label> (see: agents accounts). '
+            + 'share a release, select one by its installation name. '
             + 'The new release is fetched and launched before it replaces the working one, so a bad release leaves your agent running.',
     });
 }

package/dist/commands/usage.js

@@ -7,11 +7,13 @@ export function registerUsageCommand(program) {
     addHostOption(program.command('usage [agent]'))
         .description('Show rate-limit / quota usage per agent')
         .option('--json', 'Emit machine-readable JSON (per-agent usage snapshot) instead of the table')
+        .option('-r, --refresh', 'Collect fresh usage through the shared device coordinator before rendering')
         .addHelpText('after', `
 Examples:
   agents usage              Show usage for all installed agents
   agents usage claude       Show usage for Claude only
   agents usage codex        Show usage for Codex only
+  agents usage claude --refresh  Explicitly refresh Claude once, device-wide
   agents usage --json       Machine-readable snapshot for scripts
 `)
         .action(async (agentFilter, options) => {
@@ -35,7 +37,7 @@ Examples:
             console.log(chalk.gray('No agents installed. Run `agents add <agent>` first.'));
             return;
         }
-        const records = await Promise.all(targets.map((agentId) => collectAgentUsage(agentId)));
+        const records = await Promise.all(targets.map((agentId) => collectAgentUsage(agentId, options.refresh === true)));
         if (options.json) {
             console.log(JSON.stringify(records, null, 2));
             return;
@@ -44,7 +46,7 @@ Examples:
     });
 }
 /** Gather one agent's usage snapshot as structured data (shared by both renderers). */
-async function collectAgentUsage(agentId) {
+async function collectAgentUsage(agentId, forceRefresh = false) {
     // Plain name — color is applied only at text-render time (formatAgentUsage), so
     // `--json` never emits ANSI escapes in `label` (e.g. under FORCE_COLOR=1).
     const label = AGENTS[agentId].name;
@@ -61,7 +63,7 @@ async function collectAgentUsage(agentId) {
     if (!info.usageKey && !info.accountKey) {
         return { agent: agentId, label, status: 'not-signed-in' };
     }
-    const usage = await getUsageInfoForIdentity({ agentId, home, info, cliVersion: null });
+    const usage = await getUsageInfoForIdentity({ agentId, home, info, cliVersion: null }, forceRefresh ? { forceRefresh: true } : undefined);
     return { agent: agentId, label, status: 'ok', email: info.email ?? undefined, usage };
 }
 /** Render one usage record as the human table section. */

package/dist/commands/versions.js

@@ -5,7 +5,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { select, confirm, checkbox } from '@inquirer/prompts';
 import { AGENTS, MANAGED_AGENT_IDS, accountOrgBadge, getAccountEmail, getAccountInfo, agentLabel, warnAgentDeprecated, isAgentHardDeprecated, hardDeprecationError, isSelfUpdatingAgent, } from '../lib/agents.js';
-import { formatUsageSummary, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, } from '../lib/usage.js';
+import { formatUsageSummary, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, isUsageHeadlessScopeError, } from '../lib/usage.js';
 import { viewAction } from './view.js';
 import { resolveConfiguredModel, formatAgentIdentity } from '../lib/models.js';
 import { readManifest, writeManifest, createDefaultManifest } from '../lib/manifest.js';
@@ -31,7 +31,7 @@ function fixSessionFilePaths(agent, version, oldVersionDir) {
     const trashPath = path.join(trashAgentDir, stamps[0]);
     updateSessionFilePaths(oldVersionDir, trashPath);
 }
-function formatAccountHint(info, usage, unverified = false) {
+function formatAccountHint(info, usage, unverified = false, headless = false) {
     const parts = [];
     if (info.email) {
         // Same-email accounts can live in different orgs (personal Max vs a Team
@@ -39,7 +39,10 @@ function formatAccountHint(info, usage, unverified = false) {
         const badge = accountOrgBadge(info);
         parts.push(badge ? `${info.email} (${badge})` : info.email);
     }
-    const usageSummary = formatUsageSummary(info.plan, usage, 3, { unverified });
+    const usageSummary = formatUsageSummary(info.plan, usage, 3, {
+        unverified: unverified && !headless,
+        headless,
+    });
     if (usageSummary)
         parts.push(usageSummary);
     if (parts.length === 0)
@@ -540,7 +543,8 @@ export function registerVersionsCommands(program) {
                                 // This hint sits in a "switch your default to this version?"
                                 // confirm — the one place a stale reading directly steers a
                                 // choice, so it must not present an unconfirmed bar as fact.
-                                const accountHint = formatAccountHint(info, usage.snapshot, !!usage.snapshot && !!usage.error);
+                                const headless = isUsageHeadlessScopeError(usage.error);
+                                const accountHint = formatAccountHint(info, usage.snapshot, !headless && !!usage.snapshot && !!usage.error, headless);
                                 const message = `Switch default from ${agentLabel(agentConfig.id)}@${currentDefault} to ${agentLabel(agentConfig.id)}@${installedVersion}${accountHint}?`;
                                 const setAsDefault = await confirm({
                                     message,
@@ -708,9 +712,11 @@ export function registerVersionsCommands(program) {
                         const email = accountInfo?.email || '';
                         const usageKey = getUsageLookupKey(accountInfo);
                         const versionUsage = usageKey ? usageByKey.get(usageKey) : undefined;
+                        const headless = isUsageHeadlessScopeError(versionUsage?.error);
                         const usageSummary = usageKey
                             ? formatUsageSummary(null, versionUsage?.snapshot || null, 3, {
-                                unverified: !!versionUsage?.snapshot && !!versionUsage.error,
+                                unverified: !headless && !!versionUsage?.snapshot && !!versionUsage.error,
+                                headless,
                             })
                             : '';
                         if (maxEmailLen > 0) {

package/dist/commands/view.js

@@ -8,7 +8,7 @@ import { AGENTS, ALL_AGENT_IDS, accountDisplayLabel, getAllCliStates, getUnmanag
 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';
+import { agentReportsUsage, deriveUsageStatusFromSnapshot, formatUsageSection, formatUsageSummary, formatUsageStatusBadge, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, isUsageHeadlessScopeError, } from '../lib/usage.js';
 import { readManifest } from '../lib/manifest.js';
 import { listInstalledVersions, listInstalledVersionDirs, getGlobalDefault, getVersionHomePath, getVersionDir, removeVersion, printTrashFooter, reconcileStaleLatestForAgent, isGlobalBinaryAgent, getLiveVersion, isVersionIsolated, getIsolatedDefault, } from '../lib/versions.js';
 import { ensureVersionedAliasCurrent, removeShim, } from '../lib/shims.js';
@@ -520,11 +520,13 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
                 const info = rawInfo ? mergeCanonical(rawInfo) : undefined;
                 const usageKey = getUsageLookupKey(info);
                 const usageInfo = usageKey ? usageByKey.get(usageKey) : undefined;
-                const usageUnavailable = agentReportsUsage(agentId) && !!info?.signedIn && !usageInfo?.snapshot;
-                const usageUnverified = !!usageInfo?.snapshot && !!usageInfo.error;
+                const headless = isUsageHeadlessScopeError(usageInfo?.error);
+                const usageUnavailable = agentReportsUsage(agentId) && !!info?.signedIn && !usageInfo?.snapshot && !headless;
+                const usageUnverified = !headless && !!usageInfo?.snapshot && !!usageInfo.error;
                 const usageStr = formatUsageSummary(info?.plan || null, usageInfo?.snapshot || null, maxPlanWidth, {
                     unavailable: usageUnavailable,
                     unverified: usageUnverified,
+                    headless,
                     maxWindows: usageWindowCap,
                 });
                 maxUsageWidth = Math.max(maxUsageWidth, stringWidth(usageStr));
@@ -586,11 +588,13 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
                 }
                 const hasEmail = !!vInfo?.email;
                 const signedIn = !!vInfo?.signedIn;
-                const usageUnavailable = agentReportsUsage(agentId) && signedIn && !usageInfo?.snapshot;
-                const usageUnverified = !!usageInfo?.snapshot && !!usageInfo.error;
+                const headless = isUsageHeadlessScopeError(usageInfo?.error);
+                const usageUnavailable = agentReportsUsage(agentId) && signedIn && !usageInfo?.snapshot && !headless;
+                const usageUnverified = !headless && !!usageInfo?.snapshot && !!usageInfo.error;
                 const usageStr = formatUsageSummary(vInfo?.plan || null, usageInfo?.snapshot || null, maxPlanWidth, {
                     unavailable: usageUnavailable,
                     unverified: usageUnverified,
+                    headless,
                     maxWindows: usageWindowCap,
                 });
                 const hasUsage = usageStr.length > 0;
@@ -712,8 +716,10 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
             gMaxStatusWidth = Math.max(gMaxStatusWidth, stringWidth(formatUsageStatusBadge(gInfo?.usageStatus)));
             const gUsageKey = getUsageLookupKey(gInfo);
             const gUsage = gUsageKey ? usageByKey.get(gUsageKey) : undefined;
+            const gHeadless = isUsageHeadlessScopeError(gUsage?.error);
             const gUsageStr = formatUsageSummary(gInfo?.plan || null, gUsage?.snapshot || null, 3, {
-                unverified: !!gUsage?.snapshot && !!gUsage.error,
+                unverified: !gHeadless && !!gUsage?.snapshot && !!gUsage.error,
+                headless: gHeadless,
                 maxWindows: usageWindowCap,
             });
             gMaxUsageWidth = Math.max(gMaxUsageWidth, stringWidth(gUsageStr));
@@ -733,8 +739,10 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
             const parts = [`    ${verLabel}${padding}`];
             const gUsageKey = getUsageLookupKey(gInfo);
             const gUsage = gUsageKey ? usageByKey.get(gUsageKey) : undefined;
+            const gHeadless = isUsageHeadlessScopeError(gUsage?.error);
             const gUsageStr = formatUsageSummary(gInfo?.plan || null, gUsage?.snapshot || null, 3, {
-                unverified: !!gUsage?.snapshot && !!gUsage.error,
+                unverified: !gHeadless && !!gUsage?.snapshot && !!gUsage.error,
+                headless: gHeadless,
                 maxWindows: usageWindowCap,
             });
             const gActiveStr = gInfo ? formatLastActive(gInfo.lastActive) : '';

package/dist/commands/webhook.d.ts

@@ -1,9 +1,9 @@
 /**
- * `agents webhook` — localhost receiver for signed public webhook ingress.
+ * `agents webhooks` — localhost receiver for signed public webhook ingress.
  *
  * The receiver intentionally binds localhost by default. Public exposure is a
  * separate `agents funnel up <host>` step so the HTTP process can be tested and
  * rotated without changing the Tailscale Funnel config.
  */
 import type { Command } from 'commander';
-export declare function registerWebhookCommand(program: Command): void;
+export declare function registerWebhooksCommand(program: Command): void;