@phnx-labs/agents-cli 1.22.26 → 1.22.28

package/dist/commands/output.js

@@ -12,6 +12,7 @@ import { terminalWidth, truncateToWidth, padToWidth } from '../lib/session/width
 import { collectGitOutput } from '../lib/output/git-output.js';
 import { loadDevices, isControlDevice } from '../lib/devices/registry.js';
 import { machineId } from '../lib/session/sync/config.js';
+import { stripClixml } from '../lib/hosts/remote-cmd.js';
 const execFileAsync = promisify(execFile);
 export function registerOutputCommand(program) {
     addHostOption(program.command('output'))
@@ -24,16 +25,21 @@ export function registerOutputCommand(program) {
         .option('--login <login...>', 'Count PRs for these GitHub logins (default: current gh user)')
         .option('--no-prs', 'Skip the GitHub PR lookup (commits only)')
         .option('--all-hosts', 'Aggregate across every online device (ag devices) over SSH')
+        .option('--pricing <scenario>', 'Cost scenario: actual (default, cache-discounted) or no-cache (cache read/write billed at the full input rate)')
         .addHelpText('after', `
 Examples:
   agents output                       Last 7 days: burn, output tokens, PRs, commits, ratios
   agents output --since 24h           Last 24 hours
   agents output --since 1mo           Last month  (units: 1h 24h 7d 4w 1mo 1y, or ISO date)
+  agents output --pricing no-cache    Model the burn as if prompt caching were off
   agents output --all-hosts           Fleet-wide, folding in every online machine
   agents output --by day --json       Machine-readable daily burn/output rollup
 
 Burn (cost) is computed offline from a versioned per-model price table (${PRICING_VERSION}).
 Output tokens are the real generated tokens — NOT the cache-inflated total token count.
+The burn is split into input / cache-read / cache-write where the harness records it
+(Claude/Codex/Gemini/Droid). --pricing no-cache reprices cached tokens at the input rate,
+so you can see what caching is saving. --json always carries both actual and no-cache costs.
 `)
         .action(async (options) => {
         await outputAction(options);
@@ -47,6 +53,14 @@ function resolveGroup(by) {
     console.error(chalk.red('error: --by must be one of: agent, project, day, account'));
     process.exit(1);
 }
+function resolvePricing(pricing) {
+    if (pricing === undefined || pricing === 'actual')
+        return 'actual';
+    if (pricing === 'no-cache')
+        return 'no-cache';
+    console.error(chalk.red('error: --pricing must be one of: actual, no-cache'));
+    process.exit(1);
+}
 /** Compact token formatter: 38.6M, 4.1K, 10.6B. */
 function formatCompact(n) {
     const abs = Math.abs(n);
@@ -59,13 +73,27 @@ function formatCompact(n) {
     return String(n);
 }
 function emptyBurn() {
-    return { costUsd: 0, outputTokens: 0, tokenCount: 0, sessionCount: 0, durationMs: 0 };
+    return {
+        costUsd: 0,
+        costUsdNoCache: 0,
+        outputTokens: 0,
+        tokenCount: 0,
+        inputTokens: 0,
+        cacheReadTokens: 0,
+        cacheWriteTokens: 0,
+        sessionCount: 0,
+        durationMs: 0,
+    };
 }
 function sumBurn(rows) {
     return rows.reduce((acc, r) => {
         acc.costUsd += r.costUsd;
+        acc.costUsdNoCache += r.costUsdNoCache;
         acc.outputTokens += r.outputTokens;
         acc.tokenCount += r.tokenCount;
+        acc.inputTokens += r.inputTokens;
+        acc.cacheReadTokens += r.cacheReadTokens;
+        acc.cacheWriteTokens += r.cacheWriteTokens;
         acc.sessionCount += r.sessionCount;
         acc.durationMs += r.durationMs;
         return acc;
@@ -122,7 +150,9 @@ async function fetchRemotePayload(device, options) {
             timeout: 120_000,
             maxBuffer: 64 * 1024 * 1024,
         });
-        const parsed = JSON.parse(stdout);
+        // A Windows device relays its payload through PowerShell, which can prefix a
+        // CLIXML banner ahead of the JSON — strip it before parsing (RUSH-2286).
+        const parsed = JSON.parse(stripClixml(stdout));
         parsed.machine = parsed.machine || device;
         return parsed;
     }
@@ -141,13 +171,17 @@ async function fetchRemotePayload(device, options) {
 }
 async function outputAction(options) {
     const includePrs = options.prs !== false;
+    // Validate --pricing up front so a bad value errors even under --json. The JSON
+    // payload always carries BOTH costs regardless of the scenario — the flag only
+    // chooses which one the text renderer leads with.
+    const scenario = resolvePricing(options.pricing);
     if (!options.allHosts) {
         const payload = await computeLocalPayload(options, includePrs);
         if (options.json) {
             process.stdout.write(JSON.stringify(withRatios(payload, [payload]), null, 2) + '\n');
             return;
         }
-        renderSingle(payload);
+        renderSingle(payload, scenario);
         return;
     }
     // Fleet: local payload + every online device, folded in over SSH.
@@ -166,7 +200,7 @@ async function outputAction(options) {
         process.stdout.write(JSON.stringify(withRatios(mergeMachines(machines, options), machines), null, 2) + '\n');
         return;
     }
-    renderFleet(machines, options);
+    renderFleet(machines, options, scenario);
 }
 /** Merge per-machine payloads into a combined one (burn + commits summed; PRs local-only). */
 function mergeMachines(machines, options) {
@@ -179,8 +213,12 @@ function mergeMachines(machines, options) {
     const uncosted = new Set();
     for (const m of machines) {
         burn.costUsd += m.burn.costUsd;
+        burn.costUsdNoCache += m.burn.costUsdNoCache;
         burn.outputTokens += m.burn.outputTokens;
         burn.tokenCount += m.burn.tokenCount;
+        burn.inputTokens += m.burn.inputTokens;
+        burn.cacheReadTokens += m.burn.cacheReadTokens;
+        burn.cacheWriteTokens += m.burn.cacheWriteTokens;
         burn.sessionCount += m.burn.sessionCount;
         burn.durationMs += m.burn.durationMs;
         for (const s of m.output.commitShas)
@@ -188,15 +226,23 @@ function mergeMachines(machines, options) {
         for (const a of m.uncostedAgents)
             uncosted.add(a);
         for (const r of m.breakdown.rows) {
-            const cur = byKey.get(r.key) ?? { key: r.key, label: r.label, costUsd: 0, durationMs: 0, sessionCount: 0, tokenCount: 0, outputTokens: 0 };
+            const cur = byKey.get(r.key) ?? {
+                key: r.key, label: r.label, costUsd: 0, costUsdNoCache: 0, durationMs: 0,
+                sessionCount: 0, tokenCount: 0, outputTokens: 0,
+                inputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0,
+            };
             // Peers resolve their own labels; keep the first non-empty one so a machine that
             // has not indexed an account yet does not blank a label another machine supplied.
             cur.label ??= r.label;
             cur.costUsd += r.costUsd;
+            cur.costUsdNoCache += r.costUsdNoCache;
             cur.durationMs += r.durationMs;
             cur.sessionCount += r.sessionCount;
             cur.tokenCount += r.tokenCount;
             cur.outputTokens += r.outputTokens;
+            cur.inputTokens += r.inputTokens;
+            cur.cacheReadTokens += r.cacheReadTokens;
+            cur.cacheWriteTokens += r.cacheWriteTokens;
             byKey.set(r.key, cur);
         }
     }
@@ -226,47 +272,76 @@ function withRatios(payload, machines) {
         machines: machines.length > 1 ? machines.map(m => ({ machine: m.machine, burn: m.burn, commits: m.output.commits, error: m.error })) : undefined,
     };
 }
-/** Shared header line: burned · output tokens · PRs · commits, plus ratios. */
-function headerLines(payload) {
+/** The cost the text renderer leads with for the chosen scenario. */
+function scenarioCost(x, scenario) {
+    return scenario === 'no-cache' ? x.costUsdNoCache : x.costUsd;
+}
+/** Shared header line: burned · output tokens · PRs · commits, plus ratios + burn split. */
+function headerLines(payload, scenario) {
     const prsTotal = payload.output.prsOpened + payload.output.prsMerged;
+    const burn = payload.burn;
+    const cost = scenarioCost(burn, scenario);
     const out = [];
     out.push('  ' +
-        `${chalk.green(formatUsd(payload.burn.costUsd))} burned` +
+        `${chalk.green(formatUsd(cost))} burned${scenario === 'no-cache' ? chalk.gray(' (no-cache)') : ''}` +
         chalk.gray('  ·  ') +
-        `${chalk.cyan(formatCompact(payload.burn.outputTokens))} output tokens` +
+        `${chalk.cyan(formatCompact(burn.outputTokens))} output tokens` +
         chalk.gray('  ·  ') +
         `${chalk.yellow(String(prsTotal))} PRs ${chalk.gray(`(${payload.output.prsMerged} merged)`)}` +
         chalk.gray('  ·  ') +
         `${chalk.yellow(String(payload.output.commits))} commits`);
     const ratios = [];
     if (prsTotal > 0)
-        ratios.push(`${formatUsd(payload.burn.costUsd / prsTotal)}/PR`);
+        ratios.push(`${formatUsd(cost / prsTotal)}/PR`);
     if (payload.output.commits > 0)
-        ratios.push(`${formatUsd(payload.burn.costUsd / payload.output.commits)}/commit`);
-    if (payload.burn.costUsd > 0)
-        ratios.push(`${formatCompact(Math.round(payload.burn.outputTokens / payload.burn.costUsd))} out-tok/$`);
+        ratios.push(`${formatUsd(cost / payload.output.commits)}/commit`);
+    if (cost > 0)
+        ratios.push(`${formatCompact(Math.round(burn.outputTokens / cost))} out-tok/$`);
     if (ratios.length > 0)
         out.push(chalk.gray('  ' + ratios.join('  ·  ')));
+    // Burn split — only for harnesses that recorded one (input/cache totals > 0).
+    const splitTotal = burn.inputTokens + burn.cacheReadTokens + burn.cacheWriteTokens;
+    if (splitTotal > 0) {
+        out.push(chalk.gray('  burn split: ') +
+            `${chalk.cyan(formatCompact(burn.inputTokens))} input` +
+            chalk.gray('  ·  ') +
+            `${chalk.cyan(formatCompact(burn.cacheReadTokens))} cache-read` +
+            chalk.gray('  ·  ') +
+            `${chalk.cyan(formatCompact(burn.cacheWriteTokens))} cache-write`);
+    }
+    // No-cache comparison — shown whenever caching actually moved the number, so an
+    // operator sees the saving in `actual` mode too (RUSH-2287: "both if useful").
+    if (burn.costUsdNoCache > burn.costUsd && burn.costUsd > 0) {
+        const saved = burn.costUsdNoCache - burn.costUsd;
+        const pct = Math.round((saved / burn.costUsdNoCache) * 100);
+        out.push(chalk.gray('  caching: ') +
+            `actual ${chalk.green(formatUsd(burn.costUsd))}` +
+            chalk.gray('  vs  ') +
+            `no-cache ${chalk.yellow(formatUsd(burn.costUsdNoCache))}` +
+            chalk.gray(`  (saved ${formatUsd(saved)}, ${pct}%)`));
+    }
     return out;
 }
 /** Render the per-group burn/output table. */
-function renderBreakdown(rows, groupBy) {
+function renderBreakdown(rows, groupBy, scenario) {
     const out = [chalk.bold(`By ${groupBy}`)];
     if (rows.length === 0)
         return out;
+    const rowCost = (r) => scenarioCost(r, scenario);
     const cols = terminalWidth();
-    const burnW = Math.max(...rows.map(r => formatUsd(r.costUsd).length), 4);
+    const burnHeader = scenario === 'no-cache' ? 'burn(nc)' : 'burn';
+    const burnW = Math.max(...rows.map(r => formatUsd(rowCost(r)).length), burnHeader.length);
     const outW = Math.max(...rows.map(r => formatCompact(r.outputTokens).length), 6);
     const sessW = Math.max(...rows.map(r => String(r.sessionCount).length), 3);
     const fixedW = 2 + 2 + burnW + 2 + outW + 2 + sessW + 8;
     const display = (r) => r.label ?? r.key;
     const keyW = Math.max(8, Math.min(Math.max(...rows.map(r => display(r).length), groupBy.length), cols - fixedW));
-    out.push('  ' + chalk.gray(padToWidth('', keyW)) + '  ' + chalk.gray(padToWidth('burn', burnW)) + '  ' + chalk.gray(padToWidth('output', outW)) + '  ' + chalk.gray('sessions'));
+    out.push('  ' + chalk.gray(padToWidth('', keyW)) + '  ' + chalk.gray(padToWidth(burnHeader, burnW)) + '  ' + chalk.gray(padToWidth('output', outW)) + '  ' + chalk.gray('sessions'));
     for (const r of rows) {
         out.push('  ' +
             padToWidth(truncateToWidth(display(r), keyW), keyW) +
             '  ' +
-            chalk.green(padToWidth(formatUsd(r.costUsd), burnW)) +
+            chalk.green(padToWidth(formatUsd(rowCost(r)), burnW)) +
             '  ' +
             chalk.cyan(padToWidth(formatCompact(r.outputTokens), outW)) +
             '  ' +
@@ -274,17 +349,17 @@ function renderBreakdown(rows, groupBy) {
     }
     return out;
 }
-function renderSingle(payload) {
+function renderSingle(payload, scenario) {
     const out = [];
     out.push(chalk.bold('Output') + chalk.gray(`  ·  pricing ${payload.pricingVersion}  ·  since ${payload.since}`));
-    out.push(...headerLines(payload));
+    out.push(...headerLines(payload, scenario));
     out.push('');
     if (payload.burn.sessionCount === 0) {
         out.push(chalk.gray('No sessions with cost data found. Run `agents sessions --all` to index, then retry.'));
         console.log(out.join('\n'));
         return;
     }
-    out.push(...renderBreakdown(payload.breakdown.rows, payload.breakdown.by));
+    out.push(...renderBreakdown(payload.breakdown.rows, payload.breakdown.by, scenario));
     out.push('');
     out.push(chalk.bold('Shipped'));
     out.push(`  ${chalk.yellow(String(payload.output.commits))} commits across ${payload.output.reposScanned} repos` + chalk.gray(`  (authors: ${payload.output.authors.length > 0 ? payload.output.authors.join(', ') : 'none detected'})`));
@@ -300,22 +375,22 @@ function renderSingle(payload) {
         out.push(chalk.gray(`agent wall-clock: ${formatDuration(payload.burn.durationMs)}`));
     console.log(out.join('\n'));
 }
-function renderFleet(machines, options) {
+function renderFleet(machines, options, scenario) {
     const merged = mergeMachines(machines, options);
     const out = [];
     out.push(chalk.bold('Output') + chalk.gray(`  ·  fleet (${machines.length} machines)  ·  pricing ${merged.pricingVersion}  ·  since ${merged.since}`));
-    out.push(...headerLines(merged));
+    out.push(...headerLines(merged, scenario));
     out.push('');
     // By machine.
     out.push(chalk.bold('By machine'));
     const nameW = Math.max(...machines.map(m => m.machine.length), 7);
-    const burnW = Math.max(...machines.map(m => formatUsd(m.burn.costUsd).length), 4);
+    const burnW = Math.max(...machines.map(m => formatUsd(scenarioCost(m.burn, scenario)).length), 4);
     for (const m of machines) {
         const note = m.error ? chalk.red(`  (${m.error})`) : '';
         out.push('  ' +
             padToWidth(m.machine, nameW) +
             '  ' +
-            chalk.green(padToWidth(formatUsd(m.burn.costUsd), burnW)) +
+            chalk.green(padToWidth(formatUsd(scenarioCost(m.burn, scenario)), burnW)) +
             '  ' +
             chalk.cyan(padToWidth(formatCompact(m.burn.outputTokens), 7)) +
             '  ' +
@@ -323,7 +398,7 @@ function renderFleet(machines, options) {
             note);
     }
     out.push('');
-    out.push(...renderBreakdown(merged.breakdown.rows, merged.breakdown.by));
+    out.push(...renderBreakdown(merged.breakdown.rows, merged.breakdown.by, scenario));
     out.push('');
     out.push(chalk.gray(notCountedLine(merged.uncostedAgents)));
     console.log(out.join('\n'));

package/dist/commands/perf.d.ts

@@ -23,6 +23,16 @@ interface PerfGlobalOpts {
 }
 /** Map warehouse rows shaped like hook.fire into the existing HookProfileRow UI. */
 export declare function asHookRows(rows: PerfAggregateRow[]): HookProfileRow[];
+/**
+ * `err:12% block:40% to:4%` when any rate is present, else ''.
+ * Exit 2 (intentional deny) is `block:`, not `err:` — so a deny-by-design
+ * guard no longer reads as a crashing hook in the table.
+ */
+export declare function formatRateColumn(r: {
+    errorRate?: number;
+    blockRate?: number;
+    timeoutRate?: number;
+}): string;
 export declare function renderHookTable(rows: HookProfileRow[], warnMs: number): void;
 /**
  * Prefer SQLite samples; fall back to the legacy daily JSONL so existing

package/dist/commands/perf.js

@@ -43,6 +43,8 @@ export function asHookRows(rows) {
         cacheMissPct: r.cacheMissPct ?? 0,
         errorCount: r.errorCount ?? 0,
         errorRate: r.errorRate,
+        blockCount: r.blockCount ?? 0,
+        blockRate: r.blockRate,
         timeoutRate: r.timeoutRate,
         project: r.project,
     }));
@@ -57,11 +59,17 @@ function printTable(headers, widths, lines, slowFlags) {
         console.log(slowFlags[i] ? chalk.yellow(line) : line);
     }
 }
-/** `err:12% to:4%` when either rate is present, else ''. */
-function formatRateColumn(r) {
+/**
+ * `err:12% block:40% to:4%` when any rate is present, else ''.
+ * Exit 2 (intentional deny) is `block:`, not `err:` — so a deny-by-design
+ * guard no longer reads as a crashing hook in the table.
+ */
+export function formatRateColumn(r) {
     const parts = [];
     if (r.errorRate)
         parts.push(`err:${Math.round(r.errorRate * 100)}%`);
+    if (r.blockRate)
+        parts.push(`block:${Math.round(r.blockRate * 100)}%`);
     if (r.timeoutRate)
         parts.push(`to:${Math.round(r.timeoutRate * 100)}%`);
     return parts.join(' ');
@@ -73,7 +81,7 @@ export function renderHookTable(rows, warnMs) {
         console.log(chalk.gray('Hooks write via cache/matches shims into the spool; run a session or resync hooks.'));
         return;
     }
-    const widths = { hook: 36, n: 5, p50: 7, p95: 7, p99: 7, mean: 7, max: 7, cache: 22, rate: 14 };
+    const widths = { hook: 36, n: 5, p50: 7, p95: 7, p99: 7, mean: 7, max: 7, cache: 22, rate: 22 };
     const pad = (s, w) => (s.length >= w ? s.slice(0, w) : s + ' '.repeat(w - s.length));
     const header = [
         pad('HOOK', widths.hook),
@@ -84,7 +92,7 @@ export function renderHookTable(rows, warnMs) {
         pad('MEAN', widths.mean),
         pad('MAX', widths.max),
         pad('CACHE', widths.cache),
-        pad('ERR/TIMEOUT', widths.rate),
+        pad('ERR/BLOCK/TO', widths.rate),
     ].join(' ');
     console.log(chalk.bold(header));
     console.log(chalk.gray('─'.repeat(header.length)));
@@ -112,8 +120,8 @@ function renderLabelTable(title, rows, warnMs, limit) {
         console.log(chalk.gray(`No ${title} samples yet.`));
         return;
     }
-    const widths = [40, 5, 7, 7, 7, 7, 7, 14];
-    printTable(['LABEL', 'N', 'P50', 'P95', 'P99', 'MEAN', 'MAX', 'ERR/TIMEOUT'], widths, sliced.map((r) => [
+    const widths = [40, 5, 7, 7, 7, 7, 7, 22];
+    printTable(['LABEL', 'N', 'P50', 'P95', 'P99', 'MEAN', 'MAX', 'ERR/BLOCK/TO'], widths, sliced.map((r) => [
         r.label,
         String(r.n),
         formatMs(r.p50Ms),

package/dist/commands/projects.js

@@ -20,9 +20,9 @@ import { machineId } from '../lib/machine-id.js';
 import { getActiveSessions } from '../lib/session/active.js';
 import { gatherRemoteActive } from '../lib/session/remote-active.js';
 import { gatherRemoteAgentsJson } from '../lib/remote-agents-json.js';
-import { formatFleetWorkspaces, parseRemoteProbe, probeProjectWorkspaces, workspaceTargetsForDef, workspaceWarnings, } from '../lib/project-probe.js';
+import { formatFleetSummary, formatFleetWorkspaces, parseRemoteProbe, probeProjectWorkspaces, workspaceTargetsForDef, workspaceWarnings, } from '../lib/project-probe.js';
 import { listProjectDefs, loadProjectDef, writeProjectDef, removeProjectDef, projectDefPath, isSafeProjectName, validateProjectDef, } from '../lib/projects.js';
-import { rollupSessionsByProject, withDefaultMachine, isDeadStatus, liveDeadSplit, enrichProjectSignals, formatProjectMembersByHost, formatProjectWarnings, } from '../lib/project-status.js';
+import { rollupSessionsByProject, withDefaultMachine, isDeadStatus, formatDeadSummary, liveDeadSplit, enrichProjectSignals, formatProjectMembersByHost, formatProjectWarnings, } from '../lib/project-status.js';
 import { fetchLinearProjectCounts } from '../lib/linear-project-counts.js';
 import { listLinearProjects, pickLinearProject } from '../lib/linear-projects.js';
 import { checkRepoSlug } from '../lib/project-doctor.js';
@@ -302,8 +302,7 @@ warnWorkspaces = []) {
     if (split.dead > 0) {
         // Wreckage is worth a number of its own — 19 crashed sessions is a thing to
         // go fix, not a throughput signal to fold into the headline.
-        const deadDetail = split.deadByStatus.map((d) => `${d.n} ${d.status}`).join(', ');
-        console.log(`  ${chalk.dim('dead')}     ${chalk.yellow(`${split.dead} finished or lost`)} ${chalk.dim(`(${deadDetail})`)}`);
+        console.log(`  ${chalk.dim('dead')}     ${formatDeadSummary(split)}`);
     }
     // Live only, grouped by host when machine stamps exist so "who is on which
     // box" is visible. Flat collapse hid that when harness×status matched across hosts.
@@ -327,7 +326,8 @@ warnWorkspaces = []) {
     if (ships.length)
         console.log(`  ${chalk.dim('ships')}    ${ships.join(' · ')}`);
     if (linear) {
-        console.log(`  ${chalk.dim('linear')}   ${linear.done}/${linear.total}${linear.truncated ? '+' : ''} done · ${linear.inProgress} in progress`);
+        const pct = linear.total > 0 ? ` ${chalk.dim(`(${Math.round((linear.done / linear.total) * 100)}%)`)}` : '';
+        console.log(`  ${chalk.dim('linear')}   ${linear.done}/${linear.total}${linear.truncated ? '+' : ''} done${pct} · ${linear.inProgress} in progress`);
     }
     for (const line of formatMilestoneLines(linear?.milestones ?? [], linear?.nextMilestone, nowMs, milestoneLimit)) {
         console.log(line);
@@ -346,13 +346,18 @@ warnWorkspaces = []) {
         console.log(`  ${chalk.dim('tickets')}  ${r.tickets.slice(0, 8).join(' · ')}${r.tickets.length > 8 ? ' …' : ''}`);
     }
     if (fleet) {
-        const lines = formatFleetWorkspaces(fleet);
-        if (lines.length === 0) {
+        const table = formatFleetWorkspaces(fleet);
+        if (table.length === 0) {
             console.log(`  ${chalk.dim('fleet')}    ${chalk.gray('no workspace paths (set root or repos[].path)')}`);
         }
-        lines.forEach((line, i) => {
-            console.log(`  ${chalk.dim((i === 0 ? 'fleet' : '').padEnd(5))}    ${line}`);
-        });
+        else {
+            // A compact health line first (scan without reading every host), then the
+            // full per-host table under it. The grouped footer carries the actionable
+            // subset; this line + the table carry the whole picture.
+            [formatFleetSummary(fleet), ...table].forEach((line, i) => {
+                console.log(`  ${chalk.dim((i === 0 ? 'fleet' : '').padEnd(5))}    ${line}`);
+            });
+        }
     }
     if (remote?.artifacts) {
         const last = remote.lastArtifact ? `  ${chalk.dim(`· last: ${remote.lastArtifact}`)}` : '';
@@ -639,6 +644,15 @@ export function registerProjectsCommands(program) {
         }
         // Compact rollup shows the next milestone; `view` shows every declared one.
         const milestoneLimit = detail ? Number.POSITIVE_INFINITY : 1;
+        // Stamp the fleet-wide rollup with when it was taken, so a scrollback isn't
+        // mistaken for a live snapshot. A single named `view` skips it (one card, and
+        // its own detail makes the freshness obvious).
+        if (!detail) {
+            const t = new Date(nowMs);
+            const hhmm = `${String(t.getHours()).padStart(2, '0')}:${String(t.getMinutes()).padStart(2, '0')}`;
+            console.log(chalk.dim(`fleet snapshot · as of ${hhmm}`));
+            console.log('');
+        }
         for (const d of defs) {
             renderCard(d, roll.get(d.name), remote.get(d.name), fleetFor(d), linear.get(d.name), nowMs, milestoneLimit, focus.get(d.name) ?? [], detail, 
             // Always feed workspace rows into the warnings footer so behind/dirty

package/dist/commands/resume.d.ts

@@ -5,7 +5,18 @@ interface ResumeOptions {
     headless?: boolean;
     cwd?: string;
     quiet?: boolean;
+    /** Run on THIS machine even when the session belongs to a peer (escape hatch). */
+    here?: boolean;
 }
+/**
+ * The argv to re-run this resume on the machine that owns the session.
+ *
+ * Deliberately carries no "don't route again" FLAG — that rides the
+ * {@link RESUME_PINNED_ENV} export instead, so the hop also works against a peer
+ * on an older CLI (see the constant's docs). Every argv token here exists in the
+ * released surface.
+ */
+export declare function buildResumeRemoteArgs(sessionId: string, prompt: string | undefined, options: ResumeOptions): string[];
 /** Translate `agents resume <id>` to the canonical `agents run` surface after
  * resolving the source identity. The run command remains the only executor. */
 export declare function buildResumeRunArgs(session: {

package/dist/commands/resume.js

@@ -3,6 +3,29 @@ import { spawn } from 'child_process';
 import chalk from 'chalk';
 import { setHelpSections } from '../lib/help.js';
 import { resolveSessionMetadataValue } from './sessions.js';
+import { sessionOwnerDevice, consumeResumePinned, RESUME_PINNED_ENV } from '../lib/session/resume-owner.js';
+/**
+ * The argv to re-run this resume on the machine that owns the session.
+ *
+ * Deliberately carries no "don't route again" FLAG — that rides the
+ * {@link RESUME_PINNED_ENV} export instead, so the hop also works against a peer
+ * on an older CLI (see the constant's docs). Every argv token here exists in the
+ * released surface.
+ */
+export function buildResumeRemoteArgs(sessionId, prompt, options) {
+    const args = ['resume', sessionId, ...(prompt === undefined ? [] : [prompt])];
+    if (options.mode)
+        args.push('--mode', options.mode);
+    if (options.interactive)
+        args.push('--interactive');
+    if (options.headless)
+        args.push('--headless');
+    if (options.cwd)
+        args.push('--cwd', options.cwd);
+    if (options.quiet)
+        args.push('--quiet');
+    return args;
+}
 /** Translate `agents resume <id>` to the canonical `agents run` surface after
  * resolving the source identity. The run command remains the only executor. */
 export function buildResumeRunArgs(session, prompt, options) {
@@ -29,7 +52,11 @@ export function registerResumeCommand(program) {
         .option('--headless', 'Resume headlessly (a prompt is required)')
         .option('--cwd <path>', 'Override the recorded working directory')
         .option('-q, --quiet', 'Suppress routing banners')
+        .option('--here', 'Run on this machine even if the session belongs to another device')
         .action(async (sessionId, prompt, options) => {
+        // Read (and clear) the routing pin before anything else, so it can never
+        // reach the agent's own children.
+        const pinnedHere = consumeResumePinned() || !!options.here;
         const outcome = await resolveSessionMetadataValue(sessionId.trim());
         if (outcome.kind === 'partial') {
             console.error(chalk.red(`Could not resolve session while these devices were unavailable: ${outcome.failedPeers.join(', ')}`));
@@ -46,6 +73,29 @@ export function registerResumeCommand(program) {
             process.exitCode = 1;
             return;
         }
+        // The harness keeps its conversation state on the machine that produced
+        // the session, so a peer-owned session MUST resume there. Running it here
+        // starts the agent against state this box does not have — silently, since
+        // a synced mirror makes the transcript look local (RUSH-2022).
+        const owner = pinnedHere ? undefined : sessionOwnerDevice(outcome.session);
+        if (owner) {
+            if (!options.quiet) {
+                process.stderr.write(chalk.gray(`[agents] session ${outcome.session.shortId} belongs to ${owner} → resuming there\n`));
+            }
+            // `runOnPeer` is the existing transport for "this session's transcript
+            // and agent binary are on that box" (lib/session/remote-list.ts) — the
+            // same one the picker already uses. Not the `--host` passthrough: that
+            // one re-discovers locally and marks the run AGENTS_FLEET_REMOTE, which
+            // a long-lived resumed session must not inherit.
+            const { runOnPeer } = await import('../lib/session/remote-list.js');
+            const rc = await runOnPeer(buildResumeRemoteArgs(outcome.session.id, prompt, options), owner, { tty: !!process.stdout.isTTY, env: { [RESUME_PINNED_ENV]: '1' } });
+            if (rc === 'no-target') {
+                console.error(chalk.red(`Session ${outcome.session.shortId} lives on ${owner}, which isn't a reachable device right now.`));
+                console.error(chalk.gray(`Register/wake it (agents devices), or run there: agents ssh ${owner}`));
+                process.exitCode = 1;
+            }
+            return;
+        }
         const args = buildResumeRunArgs(outcome.session, prompt, options);
         const child = spawn(process.execPath, [process.argv[1], ...args], {
             stdio: 'inherit',
@@ -82,6 +132,7 @@ export function registerResumeCommand(program) {
       agents resume 019fd0c8-b3e9-77a2-a1a4-444698c4d897 --mode edit`,
         notes: `
       A full ID resolves from the local session database first (zero SSH) and, on a local miss, fans out with the first peer holding it cancelling the rest. An exact label always consults the fleet (labels are not globally unique) and auto-resumes the one match; a cross-machine label collision surfaces as an ambiguity.
+      A session that ran on another device resumes ON that device over SSH — the harness's conversation state lives there, so running it here would start against state this machine does not have. --here overrides that and runs locally.
       Use agents run auto --resume <id> when the original account is unavailable and another harness may continue.`,
     });
 }

package/dist/commands/routines.js

@@ -1560,8 +1560,17 @@ export function registerRoutinesCommands(program) {
             const unknown = [...selectedSet].filter((device) => !all.includes(device));
             if (unknown.length > 0)
                 throw new Error(`Unknown device${unknown.length === 1 ? '' : 's'}: ${unknown.join(', ')}`);
+            // --set/--clear fan out to every registered device so peers outside the
+            // new set get paused. An asleep/offline peer must not abort the whole
+            // pin: the target may already be applied, and an unreachable box cannot
+            // be running the routine (it picks up the enabled set on next sync).
+            // Exit non-zero only when a *selected* device could not be enabled
+            // (github.com/phnx-labs/agents-cli#2118).
+            const skipped = [];
+            const failedTargets = [];
             for (const device of all) {
                 const action = selectedSet.has(device) ? 'resume' : 'pause';
+                const isTarget = selectedSet.has(device);
                 if (device === normalizeHost(machineId())) {
                     setJobEnabled(name, action === 'resume');
                     if (isDaemonRunning())
@@ -1570,12 +1579,30 @@ export function registerRoutinesCommands(program) {
                 }
                 const launch = getCliLaunch(['routines', action, name, '--host', device]);
                 const result = spawnSync(launch.command, launch.args, { stdio: 'inherit', env: process.env });
-                if ((result.status ?? 1) !== 0)
-                    throw new Error(`Could not ${action} '${name}' on ${device}`);
+                if ((result.status ?? 1) !== 0) {
+                    if (isTarget) {
+                        failedTargets.push(device);
+                    }
+                    else {
+                        skipped.push({ device, action });
+                    }
+                }
             }
+            for (const s of skipped) {
+                console.log(chalk.yellow(`Skipped ${s.action} of '${name}' on ${s.device} (unreachable; will sync when online)`));
+            }
+            if (failedTargets.length > 0) {
+                const offlineNote = skipped.length > 0
+                    ? ` (also skipped offline: ${skipped.map((s) => s.device).join(', ')})`
+                    : '';
+                throw new Error(`Could not enable '${name}' on: ${failedTargets.join(', ')}${offlineNote}`);
+            }
+            const offlineNote = skipped.length > 0
+                ? ` (${skipped.length} offline device${skipped.length === 1 ? '' : 's'} skipped)`
+                : '';
             console.log(chalk.green(selected.length === 0
-                ? `Routine '${name}' disabled on every registered device`
-                : `Routine '${name}' enabled on: ${selected.join(', ')}`));
+                ? `Routine '${name}' disabled on every registered device${offlineNote}`
+                : `Routine '${name}' enabled on: ${selected.join(', ')}${offlineNote}`));
         };
         if (options.clear) {
             await applyDevices([]);

package/dist/commands/run-account-picker.d.ts

@@ -4,11 +4,48 @@ export interface RunAccountChoice {
     name: string;
     value: string;
     disabled?: string;
+    /** Can serve a run right now: signed in, authenticated, and under quota. */
     ready: boolean;
+    /**
+     * Selectable, but picking it launches the harness so you can authenticate
+     * first (RUSH-2334). Mutually exclusive with `ready`; never `disabled`.
+     */
+    signInRequired: boolean;
 }
 /** Human-readable remaining capacity for every window the provider exposes. */
 export declare function formatAccountLimits(candidate: RotateCandidate): string;
 /** Build aligned picker rows with usable accounts first and unsafe rows disabled. */
 export declare function buildRunAccountChoices(candidates: RotateCandidate[], globalDefault: string | null): RunAccountChoice[];
+/**
+ * Whether a zero-healthy run may recover by launching for a login, or must keep
+ * failing loud. Three inputs, all of which have to hold:
+ *
+ * - `recoverable` — at least one excluded account is only auth-blocked. An
+ *   all-throttled set is never launched (RUSH-2132): only a window reset clears it.
+ * - `tty` — a login needs a human present; off a TTY nobody can complete one.
+ * - `json` — `--json` marks a MACHINE consumer, which must never be handed a
+ *   picker or dropped into a login TUI. This mirrors the canonical
+ *   `Surface.interactive = tty && !json` in `commands/utils.ts`; a `--json` caller
+ *   gets the parseable fail-loud error instead.
+ */
+export declare function signInLaunchDecision(input: {
+    recoverable: number;
+    tty: boolean;
+    json: boolean;
+}): 'launch' | 'fail-loud';
+/**
+ * Choose which installed version to launch so the user can authenticate, when a
+ * strategy found zero healthy accounts but at least one is merely signed out
+ * (RUSH-2334). Returns the version to launch, or null if the user cancelled.
+ *
+ * A single candidate does NOT prompt — a one-item picker is pure noise, and the
+ * only thing to decide has one answer. Several candidates fall through to the
+ * normal account picker, which shows every account with its state so the choice
+ * is informed (throttled rows stay disabled there).
+ *
+ * Callers MUST have already confirmed an interactive terminal: off a TTY there
+ * is nobody to complete the login, and the run should fail loud instead.
+ */
+export declare function pickSignInLaunchVersion(agent: AgentId, recoverable: RotateCandidate[], quiet?: boolean): Promise<string | null>;
 /** Prompt for one safe installed account/version. A cancelled picker launches nothing. */
 export declare function pickRunAccountCandidate(agent: AgentId): Promise<RotateCandidate | null>;