@phnx-labs/agents-cli 1.22.26 → 1.22.27

package/dist/commands/insights.js

@@ -217,16 +217,27 @@ function renderReport(groups, dim, meta, actions, harnesses) {
         return;
     }
     // Per-group table — the headline, and the thing no sibling command produces.
+    // Includes silent-stall counts so harness/account laziness is visible without --json.
     out.push('');
     out.push(chalk.bold(`By ${dim}`));
-    const labelW = Math.min(Math.max(...groups.map((g) => stringWidth(g.label)), 5), Math.max(20, terminalWidth() - 46));
+    const labelW = Math.min(Math.max(...groups.map((g) => stringWidth(g.label)), 5), Math.max(16, terminalWidth() - 58));
     const sessW = Math.max(...groups.map((g) => String(g.sessions).length), 3);
+    const stallOf = (g) => Object.entries(g.facets.frictionSignals)
+        .filter(([k]) => k.startsWith('silent stall:'))
+        .reduce((n, [, c]) => n + c, 0);
+    const resumeOf = (g) => g.facets.correctionSignals['resume after silent stall'] ?? 0;
+    const stallW = Math.max(...groups.map((g) => String(stallOf(g)).length), 5);
+    out.push(chalk.gray(`  ${padToWidth('', labelW)}  ${''.padStart(sessW)}       ` +
+        `${''.padStart(9)}  ${''.padStart(8)}  ${'stalls'.padStart(stallW)}  resume`));
     for (const g of groups) {
         const cost = g.costUsd > 0 ? formatUsd(g.costUsd) : '—';
         const dur = g.durationMs > 0 ? formatDuration(g.durationMs) : '—';
+        const stalls = stallOf(g);
+        const resumes = resumeOf(g);
         out.push(`  ${padToWidth(truncateToWidth(g.label, labelW), labelW)}  ` +
             `${chalk.gray(String(g.sessions).padStart(sessW))} ${chalk.gray('sess')}  ` +
-            `${chalk.green(padToWidth(cost, 9))}  ${chalk.gray(dur)}`);
+            `${chalk.green(padToWidth(cost, 9))}  ${chalk.gray(padToWidth(dur, 8))}  ` +
+            `${chalk.cyan(String(stalls).padStart(stallW))}  ${chalk.cyan(String(resumes))}`);
     }
     // Everything below is the whole scope folded together; per-group detail is in --json.
     const all = newFacetAccumulator();
@@ -235,16 +246,32 @@ function renderReport(groups, dim, meta, actions, harnesses) {
     renderCounts('Top tools', topEntries(all.toolCounts, 8), out);
     renderCounts('Languages', topEntries(all.languages, 6), out);
     renderCounts('Models', topEntries(all.models, 6), out);
+    renderCounts('Silent stalls by model', topEntries(all.silentStallsByModel ?? {}, 8), out);
     // Friction — the section that earns the command.
     const gaps = all.responseGaps;
+    const silentStalls = Object.entries(all.frictionSignals)
+        .filter(([k]) => k.startsWith('silent stall:'))
+        .reduce((n, [, c]) => n + c, 0);
+    const resumeNudges = all.correctionSignals['resume after silent stall'] ?? 0;
     out.push('');
     out.push(chalk.bold('Friction'));
     out.push(`  ${padToWidth('interruptions', 18)}  ${chalk.cyan(String(all.interruptions))}` +
         chalk.gray('   turns you cut short'));
     out.push(`  ${padToWidth('tool errors', 18)}  ${chalk.cyan(String(all.errorCount))}`);
     if (gaps.length > 0) {
-        out.push(`  ${padToWidth('your reply time', 18)}  ` +
-            chalk.cyan(`p50 ${Math.round(percentile(gaps, 50))}s`) + chalk.gray(` · p90 ${Math.round(percentile(gaps, 90))}s`));
+        // Same timestamps as silent stalls; this line is the distribution. Silent
+        // stalls (below) are the agent-attributed long gaps after the model stopped.
+        out.push(`  ${padToWidth('gap until next msg', 18)}  ` +
+            chalk.cyan(`p50 ${Math.round(percentile(gaps, 50))}s`) + chalk.gray(` · p90 ${Math.round(percentile(gaps, 90))}s`) +
+            chalk.gray('   after assistant last spoke'));
+    }
+    if (silentStalls > 0) {
+        out.push(`  ${padToWidth('silent stalls', 18)}  ${chalk.cyan(String(silentStalls))}` +
+            chalk.gray('   agent idle ≥5m until you resumed (also in By ' + dim + ' table)'));
+    }
+    if (resumeNudges > 0) {
+        out.push(`  ${padToWidth('resume nudges', 18)}  ${chalk.cyan(String(resumeNudges))}` +
+            chalk.gray('   "continue"/"keep going" after a silent stall'));
     }
     const errs = topEntries(all.errorCategories, 6);
     if (errs.length > 0) {
@@ -321,7 +348,7 @@ function renderReport(groups, dim, meta, actions, harnesses) {
         out.push(chalk.yellow(`  ${meta.unreadable} transcripts could not be read; their behaviour is missing from these totals.`));
     }
     if (all.gapsOverCeiling > 0) {
-        out.push(chalk.gray(`  ${all.gapsOverCeiling} reply gaps over an hour excluded from the percentiles.`));
+        out.push(chalk.gray(`  ${all.gapsOverCeiling} gaps over an hour excluded from p50/p90 (still counted as silent stall: 1h+ when the assistant last spoke).`));
     }
     out.push('');
     out.push(chalk.gray('  `agents insights --by project` to see it per repo'));
@@ -341,6 +368,13 @@ async function renderNarrative(payload) {
         '2. What is costing you — split into the assistant\'s fault vs your own workflow.',
         '3. Quick wins — concrete, tied to a number in the data.',
         '4. Worth trying — one more ambitious workflow change.',
+        '',
+        'Silent stalls (required): if frictionSignals contain "silent stall: …" or',
+        'correctionSignals contain "resume after silent stall" / "continue / keep going",',
+        'call that out explicitly in section 2 or 3 with the counts. Those mean the model',
+        'stopped mid-session and sat idle until the human pinged it (timestamps: last',
+        'assistant event → next user message ≥ 5 minutes). Do not reframe them as the',
+        'user being slow unless the data only shows short reply gaps.',
         'Be specific and cite the numbers. No preamble, no flattery, no bullet padding.',
         '',
         JSON.stringify(payload),

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/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/sessions-picker.js

@@ -19,12 +19,17 @@ import { renderMarkdown } from '../lib/markdown.js';
 import { itemPicker } from '../lib/picker.js';
 import { classifyFileChanges, changeCounts, toolHistogram, detectTestResult } from '../lib/session/digest.js';
 import { extractArtifacts, extractHooks, extractLinks, extractRepos, extractSkills } from '../lib/session/highlights.js';
-/** A session whose transcript lives on another machine (folded in over the live
- * cross-machine fan-out): its `filePath` is on that peer's disk, so the preview
- * can't parse it locally — it shows metadata + a "resume there" note instead.
- * Keys off `_remote`, not the machine tag, so locally-readable synced mirrors
- * still parse their file normally. */
-function remoteMachineOf(session) {
+/** A session whose transcript FILE is on another machine (folded in over the
+ * live cross-machine fan-out): its `filePath` is on that peer's disk, so the
+ * preview can't parse it locally — it shows metadata + a "resume there" note
+ * instead. Keys off `_remote`, not the machine tag, so locally-readable synced
+ * mirrors still parse their file normally.
+ *
+ * This is the READ rule and only the read rule. Whether a session may be
+ * RESUMED here is a different question with a different answer — a mirror is
+ * readable but not resumable — and `sessionOwnerDevice`
+ * (lib/session/resume-owner.ts) is the single place that answers it (RUSH-2022). */
+function transcriptOnPeerOf(session) {
     return session._remote ? session.machine : undefined;
 }
 /**
@@ -98,7 +103,7 @@ function sanitizeMeta(s) {
 const previewCache = new Map();
 /** Build a cached multi-line preview string for display in the session picker. */
 export function buildPreview(session) {
-    const remote = remoteMachineOf(session);
+    const remote = transcriptOnPeerOf(session);
     const cacheKey = remote ? `${remote}:${session.id}` : session.id;
     const cached = previewCache.get(cacheKey);
     if (cached)

package/dist/commands/sessions.d.ts

@@ -11,7 +11,7 @@ interface SessionFilterOptions {
     all?: boolean;
     teams?: boolean;
     inTeam?: string;
-    routine?: boolean;
+    routine?: boolean | string;
     since?: string;
     until?: string;
 }
@@ -389,6 +389,22 @@ export declare function isBareBrowserListing(options: SessionsOptions, query: st
  * `runSessionBrowser` picker cannot represent.
  */
 export declare function hasNoBrowserDisqualifyingFlags(options: SessionsOptions, query: string | undefined): boolean;
+/** Resolve a typed routine selector by exact name, substring, or one unambiguous typo. */
+export declare function resolveRoutineName(query: string, names: readonly string[]): string | null;
+export interface RoutineRunGroup {
+    runId: string;
+    timestamp: string;
+    sessions: SessionMeta[];
+}
+export interface RoutineChoice {
+    name: string;
+    lastRunAt: string;
+    runCount: number;
+    latestRunSessionCount: number;
+}
+export declare function buildRoutineRunGroups(sessions: SessionMeta[]): RoutineRunGroup[];
+export declare function buildRoutineChoices(sessions: SessionMeta[]): RoutineChoice[];
+export declare function filterSessionsByRoutine(sessions: SessionMeta[], routine: boolean | string, interactive: boolean): Promise<SessionMeta[] | null>;
 /** Resolve a session by id/query globally and print its compact preview (no pager).
  * Backs `--preview` — the fast path for the "peek before resume" hot loop. */
 export declare function renderSessionPreview(query: string, scope: {
@@ -478,6 +494,10 @@ export declare function buildOverviewGroups(pool: SessionMeta[], perProjectCap:
     groups: OverviewGroup[];
     projectCount: number;
 };
+export declare function printRoutineRunOverview(sessions: SessionMeta[], liveIndex: Map<string, ActiveSession> | undefined, opts?: {
+    hiddenCount?: number;
+    hiddenUnmanaged?: number;
+}): void;
 /**
  * Render a resolved session to stdout — the non-follow view behind
  * `agents logs <sessionId>`. Defaults to the concise `summary` digest (same as
@@ -577,6 +597,16 @@ export declare function pickSessionInteractive(sessions: SessionMeta[], message?
 export declare const LIVE_ROW_PREFIX = "live:";
 export declare function isIdlessLiveRow(s: SessionMeta): boolean;
 export declare function handlePickedSession(picked: PickedSession): Promise<void>;
+/**
+ * Resume `session` on the machine that owns it, when that is not this one.
+ * Returns true when it handled the resume (hopped, or reported an unreachable
+ * owner), false when the session is local and the caller should take over here.
+ *
+ * The one hop for a foreground, one-session-at-a-time resume — shared by the
+ * `agents sessions` picker and by `sessions resume`'s no-tab-backend path, which
+ * would otherwise reach `resumeSessionInPlace` and be refused (RUSH-2022).
+ */
+export declare function resumeOnOwnerIfRemote(session: SessionMeta): Promise<boolean>;
 /**
  * Resume a session in the current terminal — a foreground takeover of this
  * process. Used by the single-select picker and by `sessions resume` when the
@@ -647,6 +677,22 @@ export declare function resolveSessionQuery(pool: SessionMeta[], query: string,
 export declare function fleetNotFoundMessage(query: string, deviceCount: number, unreachable: string[]): string[];
 /** Filter and rank sessions by a multi-term search query across metadata and content. */
 export declare function filterSessionsByQuery(sessions: SessionMeta[], query: string | undefined): SessionMeta[];
+/**
+ * Narrow a session list by --project and --agent before search resolution.
+ * Without this, a query like "scoped search" could match sessions in BOTH
+ * the project you specified AND elsewhere, producing an ambiguity error
+ * even though the user already pointed at the correct scope.
+ */
+export declare function applyScopeFilters(sessions: SessionMeta[], scope: {
+    agent?: string;
+    project?: string;
+    routine?: boolean | string;
+}): SessionMeta[];
+export declare function artifactLookupScope(agent?: string, project?: string, routine?: boolean | string): {
+    agent?: string;
+    project?: string;
+    routine?: boolean | string;
+};
 /**
  * Whether a missed local id lookup should widen to a cross-machine sweep.
  *