@phnx-labs/agents-cli 1.22.59 → 1.22.61

package/dist/commands/teams.js

@@ -3,7 +3,7 @@ import { dieFriction, relTime, truncate, isJsonMode, padRight } from '../lib/for
 import * as fs from 'fs/promises';
 import { addHostOption } from '../lib/hosts/option.js';
 import * as path from 'path';
-import { AgentManager, AgentStatus, checkCliSignedIn, collectTeamsDoctorData, getAgentsDir, VALID_TASK_TYPES, } from '../lib/teams/agents.js';
+import { AgentManager, AgentStatus, checkCliSignedIn, collectTeamsDoctorData, getAgentsDir, VALID_TASK_TYPES, withTeammatePrPolicy, } from '../lib/teams/agents.js';
 import { mailboxDir, enqueue } from '../lib/mailbox.js';
 import { resolveProvider } from '../lib/cloud/registry.js';
 import { emit } from '../lib/feed/events.js';
@@ -62,6 +62,7 @@ function statusColor(status) {
         case 'running': return chalk.yellow;
         case 'completed': return chalk.green;
         case 'pr_open': return chalk.magenta; // RUSH-2380: process done, PR not merged
+        case 'stranded': return chalk.yellow; // PHNX-2951: done but work not committed
         case 'failed': return chalk.red;
         case 'stopped': return chalk.gray;
         default: return chalk.white;
@@ -150,6 +151,7 @@ function snapshotToStatusDetail(agent) {
         after: agent.after,
         task_type: agent.task_type,
         host: agent.host,
+        workspace_dir: agent.workspace_dir,
     };
 }
 function fullName(type, version) {
@@ -371,7 +373,10 @@ export function wireCloudDispatcher(mgr) {
 }
 export function cloudDispatchOptions(agent) {
     return {
-        prompt: agent.prompt,
+        // PHNX-3236: a cloud teammate runs in the provider sandbox and never inherits
+        // the local merge-guard.sh hook, so the prompt policy is its ONLY self-merge
+        // boundary — apply the same helper buildRunArgv uses for local/remote.
+        prompt: withTeammatePrPolicy(agent.prompt, agent.mode),
         agent: agent.agentType,
         repo: agent.cloudRepo ?? undefined,
         branch: agent.cloudBranch ?? undefined,
@@ -784,6 +789,9 @@ function printAgentDetail(a, session) {
     }
     if (a.has_errors)
         console.log(`    ${chalk.red('! reported an error')}`);
+    if (delivery === 'stranded' && a.workspace_dir) {
+        console.log(`    ${chalk.yellow('! stranded')} uncommitted work at ${a.workspace_dir}`);
+    }
     if (a.pr_url)
         console.log(`    ${chalk.gray('PR  ')}${a.pr_url}`);
 }
@@ -864,17 +872,34 @@ function printAgentSummary(s) {
                 console.log(`      ${chalk.gray('>')} ${truncate(firstLine, 96)}`);
         }
     }
+    if (delivery === 'stranded' && s.workspace_dir) {
+        console.log(`    ${chalk.yellow('! stranded')} uncommitted work at ${s.workspace_dir}`);
+    }
     if (s.pr_url)
         console.log(`    ${chalk.gray('PR      ')} ${chalk.cyan(s.pr_url)}`);
 }
+function formatTeamStatusSummary(summary) {
+    const done = Math.max(0, summary.completed - summary.stranded);
+    const parts = [];
+    if (summary.pending > 0)
+        parts.push(`${summary.pending} pending`);
+    if (summary.running > 0 || parts.length === 0)
+        parts.push(`${summary.running} working`);
+    if (done > 0 || summary.stranded === 0)
+        parts.push(`${done} done`);
+    if (summary.stranded > 0)
+        parts.push(`${summary.stranded} stranded`);
+    if (summary.failed > 0 || parts.length === 0)
+        parts.push(`${summary.failed} failed`);
+    if (summary.stopped > 0 || parts.length === 0)
+        parts.push(`${summary.stopped} stopped`);
+    return `(${parts.join(', ')})`;
+}
 // Render a team's status in the same format the `status` subcommand uses, so
 // the interactive picker's Enter action drops the user into a familiar view.
 async function printTeamStatus(team, result) {
     const { summary, agents } = result;
-    console.log(chalk.bold(`Team ${chalk.cyan(team)}  `) +
-        chalk.gray(summary.pending > 0
-            ? `(${summary.pending} pending, ${summary.running} working, ${summary.completed} done, ${summary.failed} failed, ${summary.stopped} stopped)`
-            : `(${summary.running} working, ${summary.completed} done, ${summary.failed} failed, ${summary.stopped} stopped)`));
+    console.log(chalk.bold(`Team ${chalk.cyan(team)}  `) + chalk.gray(formatTeamStatusSummary(summary)));
     if (agents.length === 0) {
         console.log(chalk.gray('  (no teammates yet — add one with `agents teams add`)'));
     }
@@ -900,10 +925,7 @@ async function printTeamStatus(team, result) {
 // verbose/legacy layout.
 function printTeamSummary(team, result) {
     const { summary, agents } = result;
-    console.log(chalk.bold(`Team ${chalk.cyan(team)}  `) +
-        chalk.gray(summary.pending > 0
-            ? `(${summary.pending} pending, ${summary.running} working, ${summary.completed} done, ${summary.failed} failed, ${summary.stopped} stopped)`
-            : `(${summary.running} working, ${summary.completed} done, ${summary.failed} failed, ${summary.stopped} stopped)`));
+    console.log(chalk.bold(`Team ${chalk.cyan(team)}  `) + chalk.gray(formatTeamStatusSummary(summary)));
     if (agents.length === 0) {
         console.log(chalk.gray('  (no teammates yet — add one with `agents teams add`)'));
     }
@@ -925,12 +947,13 @@ function printTeamSummary(team, result) {
     console.log(chalk.gray('Raw log:     agents teams logs --team ' + team + ' --teammate <name>'));
 }
 // Classify a team into a single bucket for --status filtering.
-//  - empty:   no teammates (created but nobody added yet)
-//  - waiting: only staged teammates — call `teams start` to kick them off
-//  - working: at least one teammate still running
-//  - failed:  at least one teammate failed or was stopped (any failure wins —
-//             even if others finished, you want to know about the failure)
-//  - done:    everyone finished successfully, no failures
+//  - empty:    no teammates (created but nobody added yet)
+//  - waiting:  only staged teammates — call `teams start` to kick them off
+//  - working:  at least one teammate still running
+//  - failed:   at least one teammate failed or was stopped (any failure wins —
+//              even if others finished, you want to know about the failure)
+//  - stranded: everyone finished, but at least one has uncommitted work and no PR
+//  - done:     everyone finished successfully, no failures, no stranded work
 function classifyTeamStatus(t) {
     if (t.agent_count === 0)
         return 'empty';
@@ -943,6 +966,10 @@ function classifyTeamStatus(t) {
     const accounted = t.running + t.completed + t.failed + t.stopped;
     if (accounted < t.agent_count)
         return 'waiting';
+    // Completed-without-delivery is not "done": the work is still in the worktree
+    // and will be lost on cleanup (PHNX-2951).
+    if ((t.stranded ?? 0) > 0)
+        return 'stranded';
     return 'done';
 }
 // Merge persistent team registry with tasks derived from live agents so empty
@@ -959,6 +986,7 @@ function mergeTeams(registry, tasks) {
                 pending: 0,
                 running: 0,
                 completed: 0,
+                stranded: 0,
                 failed: 0,
                 stopped: 0,
                 workspace_dir: null,
@@ -969,7 +997,7 @@ function mergeTeams(registry, tasks) {
     }
     return Array.from(byName.values()).sort((a, b) => new Date(b.modified_at).getTime() - new Date(a.modified_at).getTime());
 }
-function buildTasksFromSnapshots(agents) {
+async function buildTasksFromSnapshots(agents) {
     const byTeam = new Map();
     for (const agent of agents) {
         const teamAgents = byTeam.get(agent.task_name) || [];
@@ -981,6 +1009,7 @@ function buildTasksFromSnapshots(agents) {
         let pending = 0;
         let running = 0;
         let completed = 0;
+        let stranded = 0;
         let failed = 0;
         let stopped = 0;
         let earliestStart = null;
@@ -998,6 +1027,16 @@ function buildTasksFromSnapshots(agents) {
                 failed++;
             else if (status === AgentStatus.STOPPED)
                 stopped++;
+            // Stranded = completed with no PR and a dirty local worktree (PHNX-2951).
+            if (status === AgentStatus.COMPLETED &&
+                !agent.pr_url?.trim() &&
+                !agent.host &&
+                agent.workspace_dir) {
+                const dirty = await hasUncommittedChanges(agent.workspace_dir);
+                if (dirty) {
+                    stranded++;
+                }
+            }
             const startedAt = parseTimestamp(agent.started_at);
             if (startedAt && (!earliestStart || startedAt < earliestStart)) {
                 earliestStart = startedAt;
@@ -1017,6 +1056,7 @@ function buildTasksFromSnapshots(agents) {
             pending,
             running,
             completed,
+            stranded,
             failed,
             stopped,
             workspace_dir: workspaceDir,
@@ -1026,7 +1066,7 @@ 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 async function buildTeamRowsFromSnapshots(registry, agents, 
 /** team name -> the session that spawned it (see teamSpawners). */
 spawners) {
     const byTeam = new Map();
@@ -1035,7 +1075,26 @@ spawners) {
         details.push(snapshotToStatusDetail(agent));
         byTeam.set(agent.task_name, details);
     }
-    const teams = mergeTeams(registry, buildTasksFromSnapshots(agents));
+    const teams = mergeTeams(registry, await buildTasksFromSnapshots(agents));
+    // Recompute delivery for cached snapshots so `teams list` reflects stranded
+    // work discovered by probing the real worktree (PHNX-2951).
+    for (const details of byTeam.values()) {
+        for (const a of details) {
+            const snapshot = agents.find((s) => s.agent_id === a.agent_id);
+            if (snapshot &&
+                normalizeTeamListStatus(a.status) === AgentStatus.COMPLETED &&
+                !snapshot.pr_url?.trim() &&
+                !snapshot.host &&
+                snapshot.workspace_dir) {
+                const dirty = await hasUncommittedChanges(snapshot.workspace_dir);
+                a.delivery = resolveTeammateDelivery({
+                    status: a.status,
+                    prUrl: snapshot.pr_url,
+                    hasUncommittedChanges: dirty,
+                });
+            }
+        }
+    }
     return {
         teams,
         rows: teams.map((team) => ({
@@ -1107,7 +1166,7 @@ async function loadTeamRows(_mgr) {
     catch {
         // The index is an enrichment here — a missing/locked DB just drops the column.
     }
-    return buildTeamRowsFromSnapshots(registry, agents, spawners);
+    return await 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.
@@ -1271,7 +1330,7 @@ export function registerTeamsCommands(program) {
         .alias('ls')
         .description('List your teams, most recent activity first')
         .option('-a, --agent <agent>', 'Filter: only teams with this agent (e.g. claude or claude@2.1.112)')
-        .option('--status <status>', 'Filter: only teams with this status (working, done, failed, or empty)')
+        .option('--status <status>', 'Filter: only teams with this status (working, done, stranded, failed, or empty)')
         .option('--since <time>', 'Filter: teams active after this time (e.g. "2h", "7d", or ISO date)')
         .option('--until <time>', 'Filter: teams active before this time (e.g. "30d", or ISO date)')
         .option('-n, --limit <n>', 'Show at most this many teams (default: 20)', '20')
@@ -1298,7 +1357,7 @@ export function registerTeamsCommands(program) {
         catch {
             // The session index is an enrichment here; a missing one drops the column.
         }
-        let rows = buildTeamRowsFromSnapshots(registry, everyAgent, spawners).rows;
+        let rows = (await buildTeamRowsFromSnapshots(registry, everyAgent, spawners)).rows;
         // --- query: substring match on team name ---
         if (query) {
             const q = query.toLowerCase();
@@ -1318,7 +1377,7 @@ export function registerTeamsCommands(program) {
         // --- --status: classify each team, filter ---
         if (opts.status) {
             const want = opts.status.toLowerCase();
-            const validStatuses = ['working', 'done', 'failed', 'empty'];
+            const validStatuses = ['working', 'done', 'stranded', 'failed', 'empty'];
             if (!validStatuses.includes(want)) {
                 dieFriction('teams', 'invalid-status-filter', `Invalid --status '${opts.status}'. Use one of: ${validStatuses.join(', ')}`);
             }
@@ -1877,7 +1936,10 @@ export function registerTeamsCommands(program) {
             mgr.setCloudDispatcher(async (a) => {
                 const prov = resolveProvider(providerId);
                 const dispatchOpts = {
-                    prompt: a.prompt,
+                    // PHNX-3236: same self-merge boundary as the local/remote path — a
+                    // cloud teammate has no inherited merge-guard.sh, so the prompt is
+                    // its only layer.
+                    prompt: withTeammatePrPolicy(a.prompt, a.mode),
                     agent: a.agentType,
                     repo: opts.repo,
                     branch: opts.branch,

package/dist/index.js

@@ -72,6 +72,15 @@ if (process.argv[2] === '__shim') {
     const code = await execShimPassthrough(agent, rawArgs, process.cwd(), pinned || undefined);
     process.exit(code);
 }
+// gh overload delegate: the `gh` PATH shim routes `gh pr checks` here as
+// `agents __gh --real-gh <path> -- pr checks …`, so the rate-limit-prone read
+// runs over REST instead of GraphQL (PHNX-3501). Above bootstrap for the same
+// reason as __shim: no update check, no command-tree load — this is on the hot
+// path of an agent's CI watch, and the gh argv must pass through untouched.
+if (process.argv[2] === '__gh') {
+    const { runGhOverload } = await import('./lib/github/gh-overload.js');
+    process.exit(await runGhOverload(process.argv.slice(3)));
+}
 if (process.argv[2] === '__claude-statusline') {
     const { runClaudeStatusLine } = await import('./lib/claude-statusline.js');
     process.exit(await runClaudeStatusLine());

package/dist/lib/accounting/rotate.d.ts

@@ -8,6 +8,7 @@ import type { AgentId, RunStrategy } from '../types.js';
 import type { FallbackEntry } from '../exec.js';
 import { PROJECTION_HORIZON_MIN, capacityWeight } from './capacity.js';
 import { type AccountInfo, type CredentialPresence } from '../agents.js';
+import { type EventPayload } from '../feed/events.js';
 import { type UsageSnapshot } from './usage.js';
 import { type AuthVerdict } from '../auth-health.js';
 export interface RotateCandidate {
@@ -75,6 +76,21 @@ export interface RotateResult {
      * was silently reported as verified.)
      */
     usageUnverified?: boolean;
+    /**
+     * True when NO candidate carries a fresh usage snapshot AND at least one
+     * carries a STALE-but-present one — the "entirely stale usage" case
+     * (PHNX-2526). The INITIAL route MUST NOT be decided on a stale number that
+     * looks plausible but is wrong (the yosemite-s1 incident: 26h–2.7d-old
+     * snapshots read 48% while the account was at its weekly cap). `picked` is
+     * still populated (a stale candidate) so `healthy` stays intact for BOUNDED
+     * post-rejection failover, but a caller doing the initial selection MUST NOT
+     * launch it — it diverts to the account picker (interactive) or fails loud
+     * with NO_VERIFIED_USAGE (unattended). Distinct from a BLIND pool with no
+     * snapshot at all (a worker box whose usage endpoint 403s, RUSH-2392): that
+     * carries no misleading number, so it still draws a pick and this stays
+     * false.
+     */
+    noVerifiedUsage?: boolean;
 }
 export declare const RUN_STRATEGIES: RunStrategy[];
 /**
@@ -139,6 +155,20 @@ export declare const USAGE_DECISION_MAX_AGE_MS: number;
  * narrowing rule below exists to prevent.
  */
 export declare function isUsageVerified(candidate: RotateCandidate, nowMs?: number): boolean;
+/**
+ * Whether this candidate carries a STALE-but-present usage number: a snapshot
+ * with windows whose capture time is older than {@link USAGE_DECISION_MAX_AGE_MS}.
+ *
+ * This is the misleading case the initial route must refuse — the number reads
+ * "48% used" with the same confidence whether captured a minute or three days
+ * ago, and a box whose refresh is failing stays wrong indefinitely. It is
+ * deliberately NARROWER than "not verified": a BLIND candidate with no snapshot
+ * (or a plan-only meterless one with no windows) carries no number to be misled
+ * by — a worker box whose usage endpoint 403s (RUSH-2392), or a meterless Grok
+ * login — so it is not "stale", and an entirely-blind pool still draws a pick
+ * (PHNX-3392) rather than fail loud with NO_VERIFIED_USAGE.
+ */
+export declare function hasStaleUsage(candidate: RotateCandidate, nowMs?: number): boolean;
 /**
  * Whether a specific account can serve a run right now, and — when it can't —
  * why. `signed_out` covers a missing usable credential; `revoked` is a token the
@@ -291,6 +321,16 @@ export declare function earliestResetAcross(candidates: RotateCandidate[], nowMs
  * and `resets <time>` (parsed for the rotate cooldown). Do not deviate.
  */
 export declare function formatNoHealthyAccountError(agent: AgentId, strategy: RunStrategy, excluded: RotateCandidate[], nowMs?: number): string;
+/**
+ * The all-stale-usage error (PHNX-2526) an UNATTENDED `balanced`/`available`
+ * run fails loud with when no account's usage is fresh enough to route on. EXACT
+ * contract — it MUST contain the literal `NO_VERIFIED_USAGE` so a machine caller
+ * (and the Factory watchdog) can tail-detect it distinctly from the
+ * `no healthy` throttle error, which is a different condition (throttled vs
+ * merely stale). Names each candidate with how stale its snapshot is, so the
+ * operator can see the failing-refresh box rather than guess.
+ */
+export declare function formatNoVerifiedUsageError(agent: AgentId, strategy: RunStrategy, candidates: RotateCandidate[], nowMs?: number): string;
 /**
  * The zero-healthy-harness error for `agents run auto` — names each harness's
  * exclusion reason plus the earliest reset across all snapshots.
@@ -336,6 +376,16 @@ export declare function resolveAccountVersion(agent: AgentId, account: string):
 export declare function selectBalancedVersion(agent: AgentId): Promise<RotateResult | null>;
 /** Select the configured version if available, otherwise another available version. */
 export declare function selectAvailableVersion(agent: AgentId, preferredVersion?: string | null): Promise<RotateResult | null>;
+/**
+ * Build the enriched `rotation.resolved`/`rotation.unresolved` event payload:
+ * the full candidate pool as the router saw it, the pick and WHY, and a
+ * freshness tally. Replaces the old `{ version, healthy: <n>, excluded: <n> }`
+ * shape, which recorded only counts and a device-local version and so could not
+ * tell a blind-pool draw from a skewed-verified pick from a refused-stale route
+ * — the exact ambiguity that keeps a bad pick undebuggable from the log. All
+ * candidates share ONE `nowMs` so their `tier`/`ageMs` are mutually consistent.
+ */
+export declare function buildRotationDecisionEvent(rotation: RotateResult, agent: AgentId, strategy: RunStrategy): EventPayload;
 /**
  * Resolve the version `agents run` should use when the caller did not pin
  * one with `@version`. The caller supplies the effective strategy.
@@ -362,6 +412,19 @@ export declare function resolveRunVersion(agent: AgentId, strategy: RunStrategy,
      * path — there is no account to be "unhealthy").
      */
     exhausted?: RotateCandidate[];
+    /**
+     * Set (with `version: null`) for a `balanced`/`available` route when EVERY
+     * eligible account's usage is stale and none is verified (PHNX-2526). The
+     * initial selection MUST NOT auto-launch on a stale number: an interactive
+     * caller diverts to the account picker, an unattended one fails loud with
+     * NO_VERIFIED_USAGE (`formatNoVerifiedUsageError`). `rotation` is still
+     * returned — its `healthy` set (the stale candidates) is preserved ONLY for
+     * bounded post-rejection failover, never the initial pick. Undefined when a
+     * verified account exists, when the pool is entirely blind (no snapshots —
+     * the worker-box case still draws a pick), for `pinned`, and for the
+     * zero-healthy `exhausted` case.
+     */
+    noVerifiedUsage?: boolean;
 }>;
 /**
  * Cap on the number of healthy accounts a single run will re-dispatch through