@phnx-labs/agents-cli 1.22.64 → 1.22.66

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## 1.22.66
+
+- **Fleet usage/auth sync now reaches FQDN-only-pinned workers (PHNX-3505).** The
+  usage-sync and reserved-auth-sync push/pull planners judged a peer "pinned" by its
+  bare device name, but a tailnet-discovered worker's host key is pinned under its
+  FQDN (`yosemite-m6.tail….ts.net`). So every worker not also pinned under its short
+  name was silently skipped — its `claude-usage.json` went days stale and `balanced`
+  routed into weekly-maxed accounts, and its auth token never propagated. The pin
+  check now resolves the same host string the ssh connection dials
+  (`isDevicePinned`), matching either form. Source:
+  `cli/src/lib/devices/known-hosts.ts`, `cli/src/lib/accounting/usage-sync.ts`,
+  `cli/src/lib/secrets/reserved-sync.ts`.
+
+## 1.22.65
+
+- **`agents view` shows the last-known usage number with its age instead of hiding it (PHNX-3453).** When the usage endpoint 429-backs-off an account so a window is not refreshed within its own lifetime (Claude's 5h session window) or a billing period rolls over (Grok's weekly credit window), the view now renders the last reading with a staleness suffix — `S: █▌░░░ 30% · 6h old`, `W: ██▏░░ 42% · stale (period ended 1h ago)` — instead of `S: ┄┄┄┄┄ unavailable` or a numberless `run grok once to refresh usage`. The dropped windows ride a new VIEW-ONLY `UsageSnapshot.staleWindows` field; routing still reads only `windows`, so `isUsageVerified`/`hasStaleUsage`/`deriveUsageStatusFromSnapshot` continue to treat a stale/expired number as unverified and never route on it. Source: `cli/src/lib/accounting/usage.ts`.
+
+- **A worker's interactive Claude run no longer lands on the login screen (PHNX-3502).** `claudeAdapter.applyExecConfigEnv` deferred to the per-version native login for EVERY interactive run (`ctx.interactive || headedDevice`), even on a `worker`-role device that has no such login — only a headless run on a worker injected the `auth`-bundle setup-token. A keychain-less worker with no `.credentials.json`/`.oauth_token` therefore got no credential at all on `agents run claude --interactive --device <worker>`, landing on Claude Code's theme-picker/login screen. The condition now keys purely on device role: only a `personal`/`desktop` (headed) device defers to its native login; every worker run, interactive or headless, injects the setup-token. The `credentialPresence` routing gate that feeds `--strategy balanced` is also fixed to stop reading a false-healthy signal: its claude entry now requires the REAL credential (`.credentials.json`/`.oauth_token`, via the same floor `getAccountInfo` applies) rather than the bare presence of `.claude.json` (stale account metadata a version can carry with no usable credential behind it). Relatedly, a provider account folded into the run-candidate pool now derives `signedIn` from its record's `secretPresent` field instead of a hardcoded `true` — keeping that field honest rather than changing today's routing, since `localRegistryRecords` already filters out token-less accounts before the map. Source: `cli/src/lib/harness/adapters/claude.ts`, `cli/src/lib/agent-spec/agents.ts`, `cli/src/lib/accounting/account-pool.ts`, `cli/src/lib/accounting/account-pool-collect.ts`.
+
+- **Include clickable ticket links in every feed broadcast (PHNX-3572).** Ticket-backed posts now put the canonical Linear URL in the shared message delivered to private owner destinations and configured Slack channel sinks; repeated URL lines are deduplicated. Source: `cli/src/lib/feed-broadcast.ts`, `cli/src/commands/feed.ts`.
+
+- **`agents view <agent> --device <host>` no longer flashes and vanishes from a real terminal (PHNX-3583).** The `--device` passthrough set `interactive = process.stdout.isTTY` and forwarded read-only renders over `ssh -tt` — a forced PTY. On the render's clean exit the PTY teardown + local-terminal restore (`restoreLocalTerminal` / `TERMINAL_MODE_RESET`) wiped the just-drawn output, so the whole view flashed and disappeared, leaving the prior screen. The piped (non-TTY) path never had this problem. Pure read-only render commands (`view`, `inspect`, `insights`, `doctor`) now forward over a plain pipe instead of a PTY, and inject `FORCE_COLOR=1` plus `COLUMNS`/`LINES` into the remote env so the piped render still comes back colored and correctly wrapped (`terminalWidth()` already reads `$COLUMNS` for exactly this reason); `FORCE_COLOR` is withheld under `--json` so machine output stays clean. A render command's narrow interactive sub-path — `view --prune`'s confirm — keeps the PTY, and every genuinely interactive command (`run`, `secrets browse`, pickers) is untouched. Source: `cli/src/lib/hosts/passthrough.ts`, `cli/src/lib/hosts/passthrough.test.ts`.
+
+- **Remote provisional Claude tabs reopen once instead of bouncing across the fleet (PHNX-3587).** When VS Code reloaded before an offloaded Claude launch had written its first transcript, `agents sessions resume` found the dispatcher's synthetic session row, hopped to the target, then let the target search the fleet and rediscover the same synthetic row. The repeated routing printed reconnect banners and eventually returned to the shell without Claude. An owner hop now performs one local lookup: it resumes a materialized transcript, or recreates the exact forced Claude session identity when the transcript has not materialized yet. Source: `cli/src/commands/resume.ts`.
+
+- **Cap and smooth the daemon's usage-refresh traffic with a per-provider budget.** The
+  refresher enforced only a per-account hourly cap, so endpoint load scaled linearly
+  with account count: 8 Claude accounts × 12/hr = ~96 usage calls/hr from one box,
+  against Anthropic's ~100/hr `/api/oauth/usage` ceiling — which 429'd accounts into
+  Retry-After parks (measured on `zion`: 7 of 8 accounts parked, never refreshed in
+  their window, so `agents view` showed `S: unavailable` and balanced routing read
+  stale usage). A per-provider budget (`PROVIDER_HOURLY_BUDGET`, 30/hr across all of a
+  network provider's accounts) now bounds aggregate traffic at a fixed rate that no
+  longer grows with account count, paced smoothly (one fetch per ~2 min, round-robin,
+  stalest account first) so it never bursts-then-stalls. Actively-used accounts stay
+  fresh for free via the statusline ingest, which now also re-derives their headroom
+  and suppresses a redundant API refresh. Source: `cli/src/lib/usage-refresh.ts`,
+  `cli/src/lib/daemon-ticks.ts`.
+- **Route-refuse only on genuinely stale usage, not merely budget-paced usage.** Because
+  proactive refreshes are now paced, an idle account is deliberately refreshed on a
+  stretched cadence. Routing keeps its tight 5-min bar for *weighting* an account, but
+  the fail-loud `NO_VERIFIED_USAGE` refusal now fires on a wider 40-min bar
+  (`USAGE_STALE_REFUSAL_MAX_AGE_MS`) — so a budget-paced fleet routes normally while a
+  genuinely broken refresh (hours-old readings) still refuses. Source:
+  `cli/src/lib/accounting/rotate.ts`.
+
 ## 1.22.64
 
 - **`agents accounts attach` bootstraps a keychain-less Linux worker (PHNX-3502).**

package/dist/commands/accounts.d.ts

@@ -30,12 +30,13 @@ export declare function classifyAttachTarget(target: string): AttachTarget;
 /**
  * Persist the attached setup-token to a per-version `.oauth_token` file so an
  * INTERACTIVE Claude launch on a keychain-less Linux worker can authenticate from it.
- * Headless runs inject the token via `buildExecEnv`, but an interactive launch defers to
- * the per-version login (`claudeAdapter.applyExecConfigEnv`), and the shim's Linux fallback
- * (`claudeAdapter.shimConfigEnvBash`) reads exactly this file. Without writing it, a
- * freshly-attached setup-token was invisible to interactive runs on a worker. macOS keeps
- * the credential in the keychain, so `resolveClaudeSetupToken` returns null there and this
- * is a no-op off Linux.
+ * Headless runs inject the token via `buildExecEnv`. Since PHNX-3502 an interactive
+ * launch on a worker-role device ALSO injects it through `claudeAdapter.applyExecConfigEnv`
+ * (only a headed `personal`/`desktop` device defers to its per-version native login), and
+ * the shim's Linux fallback (`claudeAdapter.shimConfigEnvBash`) reads exactly this file —
+ * so writing it is what makes a freshly-attached setup-token visible to that shim fallback
+ * on a worker. macOS keeps the credential in the keychain, so `resolveClaudeSetupToken`
+ * returns null there and this is a no-op off Linux.
  */
 export declare function writeClaudeInteractiveOauthToken(target: AttachTarget, targetAgent: AgentId, email?: string): void;
 export declare function parseBundleKey(raw: string): {

package/dist/commands/accounts.js

@@ -84,12 +84,13 @@ export function classifyAttachTarget(target) {
 /**
  * Persist the attached setup-token to a per-version `.oauth_token` file so an
  * INTERACTIVE Claude launch on a keychain-less Linux worker can authenticate from it.
- * Headless runs inject the token via `buildExecEnv`, but an interactive launch defers to
- * the per-version login (`claudeAdapter.applyExecConfigEnv`), and the shim's Linux fallback
- * (`claudeAdapter.shimConfigEnvBash`) reads exactly this file. Without writing it, a
- * freshly-attached setup-token was invisible to interactive runs on a worker. macOS keeps
- * the credential in the keychain, so `resolveClaudeSetupToken` returns null there and this
- * is a no-op off Linux.
+ * Headless runs inject the token via `buildExecEnv`. Since PHNX-3502 an interactive
+ * launch on a worker-role device ALSO injects it through `claudeAdapter.applyExecConfigEnv`
+ * (only a headed `personal`/`desktop` device defers to its per-version native login), and
+ * the shim's Linux fallback (`claudeAdapter.shimConfigEnvBash`) reads exactly this file —
+ * so writing it is what makes a freshly-attached setup-token visible to that shim fallback
+ * on a worker. macOS keeps the credential in the keychain, so `resolveClaudeSetupToken`
+ * returns null there and this is a no-op off Linux.
  */
 export function writeClaudeInteractiveOauthToken(target, targetAgent, email) {
     if (process.platform !== 'linux' || targetAgent !== 'claude' || target.kind !== 'installation')

package/dist/commands/apply.js

@@ -14,7 +14,7 @@ import chalk from 'chalk';
 import { setHelpSections } from '../lib/help.js';
 import { machineId } from '../lib/session/sync/config.js';
 import { loadDevices } from '../lib/devices/registry.js';
-import { isHostPinned, managedKnownHostsPath } from '../lib/devices/known-hosts.js';
+import { isHostPinned, isDevicePinned, managedKnownHostsPath } from '../lib/devices/known-hosts.js';
 import { ensureDevicesRegistered } from '../lib/devices/sync.js';
 import { readFleetFile, resolveDesired, emptyTargetsMessage } from '../lib/fleet/manifest.js';
 import { snapshotAuth } from '../lib/fleet/auth-sync.js';
@@ -233,7 +233,14 @@ async function runApply(opts) {
         provisionSecrets: opts.provisionSecrets === true,
         forceSecrets: opts.force === true,
         // Portable secret values only ever go to a host whose key is already pinned.
-        isHostPinned: (device) => isHostPinned(device, managedKnownHostsPath()),
+        // Resolve the device to its profile so the pin is checked against the FQDN the
+        // ssh connection dials (isDevicePinned), not the bare name — a tailnet worker
+        // pinned only under its FQDN would otherwise be refused as "not pinned"
+        // (PHNX-3505). A name with no profile falls back to the raw host-string check.
+        isHostPinned: (device) => {
+            const p = nameToProfile.get(device);
+            return p ? isDevicePinned(p) : isHostPinned(device, managedKnownHostsPath());
+        },
     });
     // --only filter.
     if (opts.only) {

package/dist/commands/feed.js

@@ -3,6 +3,7 @@ import { ensureFeedPublishHook, listAskStats, listBlocks, recordNotified, buildD
 import { ensureActivityLogHook, readRecentActivity, formatActivityLine, formatProgressUpdate, mergeActivityEvents, parseActivityPayload, } from '../lib/feed/activity.js';
 import { projectKeyFromCwd } from '../lib/project-key.js';
 import { postFeedStatus } from '../lib/feed-post.js';
+import { linearIssueUrl } from '../lib/session/linear.js';
 import { parseFeedPostLevel, planFeedBroadcast, runFeedBroadcast, effectiveBroadcastConfig, withDesktopNotify, blockBroadcastContext, blockDeliveryFailure, } from '../lib/feed-broadcast.js';
 import { getSessionById } from '../lib/session/db.js';
 import { readMeta } from '../lib/state.js';
@@ -697,6 +698,7 @@ async function broadcastPostedEvent(event, level, meta, notify = false) {
         text: event.detail ?? '',
         level,
         ticket,
+        ticketUrl: linearIssueUrl(ticket),
         project: event.project,
         agent: event.agent,
         host: event.host,

package/dist/commands/resume.d.ts

@@ -1,3 +1,4 @@
+export declare const RESUME_SOURCE_ENV = "AGENTS_RESUME_SOURCE_JSON";
 export interface StrictResumeOptions {
     mode?: string;
     interactive?: boolean;
@@ -23,6 +24,13 @@ export declare function buildResumeRunArgs(session: {
     agent: string;
     version?: string;
 }, prompt: string | undefined, options: StrictResumeOptions): string[];
+/** Recreate a remote Claude launch whose forced id never materialized a transcript. */
+export declare function buildProvisionalRunArgs(session: {
+    id: string;
+    agent: string;
+    version?: string;
+    cwd?: string;
+}, prompt: string | undefined, options: StrictResumeOptions): string[];
 /** True when the caller asked for the strict resume path (prompt and/or flags). */
 export declare function wantsStrictResume(prompt: string | undefined, options: StrictResumeOptions): boolean;
 /**

package/dist/commands/resume.js

@@ -7,6 +7,7 @@ import { spawn } from 'child_process';
 import chalk from 'chalk';
 import { resolveSessionMetadataValue } from './sessions.js';
 import { sessionOwnerDevice, consumeResumePinned, RESUME_PINNED_ENV } from '../lib/session/resume-owner.js';
+export const RESUME_SOURCE_ENV = 'AGENTS_RESUME_SOURCE_JSON';
 /**
  * The argv to re-run this resume on the machine that owns the session.
  *
@@ -46,6 +47,38 @@ export function buildResumeRunArgs(session, prompt, options) {
         args.push('--quiet');
     return args;
 }
+/** Recreate a remote Claude launch whose forced id never materialized a transcript. */
+export function buildProvisionalRunArgs(session, prompt, options) {
+    const spec = session.version ? `${session.agent}@${session.version}` : session.agent;
+    const args = ['run', spec, ...(prompt === undefined ? [] : [prompt]), '--session-id', session.id];
+    if (options.mode)
+        args.push('--mode', options.mode);
+    if (options.interactive)
+        args.push('--interactive');
+    if (options.headless)
+        args.push('--headless');
+    const cwd = options.cwd ?? session.cwd;
+    if (cwd)
+        args.push('--cwd', cwd);
+    if (options.quiet)
+        args.push('--quiet');
+    return args;
+}
+function consumeResumeSource() {
+    const raw = process.env[RESUME_SOURCE_ENV];
+    delete process.env[RESUME_SOURCE_ENV];
+    if (!raw)
+        return undefined;
+    try {
+        const value = JSON.parse(raw);
+        if (typeof value?.id === 'string' && typeof value?.agent === 'string')
+            return value;
+    }
+    catch {
+        // The routing pin is authoritative; malformed optional context is ignored.
+    }
+    return undefined;
+}
 /** True when the caller asked for the strict resume path (prompt and/or flags). */
 export function wantsStrictResume(prompt, options) {
     return (prompt !== undefined ||
@@ -63,8 +96,17 @@ export function wantsStrictResume(prompt, options) {
 export async function runStrictResume(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());
+    const routedHop = consumeResumePinned();
+    const pinnedHere = routedHop || !!options.here;
+    const routedSource = routedHop ? consumeResumeSource() : undefined;
+    if (routedSource && routedSource.id !== sessionId.trim()) {
+        console.error(chalk.red(`Resume routing metadata names session ${routedSource.id}, not requested session ${sessionId.trim()}.`));
+        process.exitCode = 1;
+        return;
+    }
+    // An owner hop must inspect only the owner's index. Fleet fan-out here can
+    // rediscover the dispatcher's synthetic row and bounce the same id forever.
+    const outcome = await resolveSessionMetadataValue(sessionId.trim(), pinnedHere ? { local: true } : {});
     if (outcome.kind === 'partial') {
         // RUSH-2492: an unreachable peer is a warning, not a hard failure. The
         // resolver already resolves an id found on the reachable fleet (SES-9a),
@@ -78,6 +120,19 @@ export async function runStrictResume(sessionId, prompt, options) {
         return;
     }
     if (outcome.kind === 'not-found') {
+        if (routedHop && routedSource?.filePath === '' && routedSource.agent === 'claude') {
+            const args = buildProvisionalRunArgs(routedSource, prompt, options);
+            const child = spawn(process.execPath, [process.argv[1], ...args], {
+                stdio: 'inherit',
+                env: process.env,
+            });
+            const exitCode = await new Promise((resolve) => {
+                child.once('error', () => resolve(127));
+                child.once('exit', (code, signal) => resolve(code ?? (signal ? 1 : 0)));
+            });
+            process.exitCode = exitCode;
+            return;
+        }
         console.error(chalk.red(`No session matching "${sessionId}".`));
         process.exitCode = 1;
         return;
@@ -102,7 +157,14 @@ export async function runStrictResume(sessionId, prompt, options) {
         // 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' }, sessionId: outcome.session.id });
+        const rc = await runOnPeer(buildResumeRemoteArgs(outcome.session.id, prompt, options), owner, {
+            tty: !!process.stdout.isTTY,
+            env: {
+                [RESUME_PINNED_ENV]: '1',
+                [RESUME_SOURCE_ENV]: JSON.stringify(outcome.session),
+            },
+            sessionId: outcome.session.id,
+        });
         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}`));
@@ -118,7 +180,7 @@ export async function runStrictResume(sessionId, prompt, options) {
             // Avoid repeating the fleet lookup in the delegated local `run`
             // process. The value is metadata-only and is not forwarded over SSH;
             // the owner performs its own local SQLite lookup.
-            AGENTS_RESUME_SOURCE_JSON: JSON.stringify(outcome.session),
+            [RESUME_SOURCE_ENV]: JSON.stringify(outcome.session),
         },
     });
     const exitCode = await new Promise((resolve) => {

package/dist/lib/accounting/account-pool-collect.js

@@ -13,7 +13,7 @@ import { registryPoolCandidates } from './account-pool.js';
 function localRegistryRecords() {
     return Object.values(readAccountRegistry().accounts)
         .filter((a) => hasKeychainToken(a.secretRef))
-        .map((a) => ({ name: a.name, provider: a.provider, auth: a.auth }));
+        .map((a) => ({ name: a.name, provider: a.provider, auth: a.auth, secretPresent: true }));
 }
 /**
  * PURE: fold provider-account candidates into the native version-home list.
@@ -45,7 +45,12 @@ export function foldRegistryCandidates(agent, inputs) {
         usageError: null,
         usageMinutesToLimit: null,
         plan: null,
-        signedIn: true,
+        // Derive from the record's real secret-presence field rather than a bare
+        // `true` literal (PHNX-3502). Inert on today's only producer
+        // (`localRegistryRecords` already filters token-less accounts before the
+        // map), but keeps the field honest for any injected record that carries
+        // `secretPresent: false`.
+        signedIn: r.secretPresent,
         authVerdict: null,
         lastActive: null,
         providerAccount: r.name,

package/dist/lib/accounting/account-pool.d.ts

@@ -16,6 +16,16 @@ export interface RegistryAccountRecord {
     name: string;
     provider: string;
     auth: AccountAuthKind;
+    /**
+     * Whether this account's secret is actually present on THIS device
+     * (`hasKeychainToken(secretRef)`, checked by the record's builder). Carried
+     * through rather than assumed, so a candidate's `signedIn` reflects a real
+     * check instead of a literal disconnected from it (PHNX-3502) — a registry
+     * entry can exist with no local secret (added on another device, or
+     * revoked), and folding it in as unconditionally signed-in would let
+     * `--strategy balanced` pick an account that fails at spawn.
+     */
+    secretPresent: boolean;
 }
 /** A registry account eligible to run one harness, ready to map to a candidate. */
 export interface RegistryAccountInput {
@@ -25,6 +35,8 @@ export interface RegistryAccountInput {
     name: string;
     provider: string;
     auth: AccountAuthKind;
+    /** See {@link RegistryAccountRecord.secretPresent}. */
+    secretPresent: boolean;
 }
 /**
  * Which provider accounts can authenticate `agent`. An account is a candidate for

package/dist/lib/accounting/account-pool.js

@@ -27,6 +27,7 @@ export function registryPoolCandidates(records, agent) {
             name: r.name,
             provider: r.provider,
             auth: r.auth,
+            secretPresent: r.secretPresent,
         });
     }
     return out;

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

@@ -163,6 +163,27 @@ export declare function isVersionLaunchableHere(agent: AgentId, version: string)
  * launched into it while the account was actually at its weekly cap.
  */
 export declare const USAGE_DECISION_MAX_AGE_MS: number;
+/**
+ * How old a usage snapshot may be before routing REFUSES to run at all
+ * (NO_VERIFIED_USAGE), as opposed to merely declining to *weight* by its number.
+ *
+ * These are two different risks and now two different bars. Weighting on a
+ * slightly-old number is cheap to get wrong (a floored weight, {@link
+ * USAGE_DECISION_MAX_AGE_MS} = 5 min); refusing to launch at all is expensive to
+ * get wrong — it fails the user's `agents run` outright. The daemon's usage
+ * refresher paces proactive fetches under a fixed per-provider budget
+ * (`usage-refresh.ts`, PROVIDER_HOURLY_BUDGET), so on a multi-account fleet an
+ * IDLE account is deliberately refreshed on a stretched round-robin cadence
+ * (bounded at N × spacing — ~16 min at 8 accounts, ~32 min at 16) rather than
+ * every 5 min, which would 429 the endpoint and park it for up to an hour. A
+ * budget-paced idle reading of 10–30 min is NOT the failure this refusal exists
+ * to catch. That failure is the `yosemite-s1` case: a box whose refresh is
+ * genuinely BROKEN, holding readings 26 h – 2.7 d old. 40 min sits comfortably
+ * above the worst-case budget cadence and still an order of magnitude below the
+ * multi-hour staleness of a broken box — and actively-used accounts refresh for
+ * free via the statusline ingest, so a *busy* account is never even this old.
+ */
+export declare const USAGE_STALE_REFUSAL_MAX_AGE_MS: number;
 /**
  * Whether this candidate's usage number is recent enough to route on. A missing
  * snapshot is unverified by definition — there is no number to trust.
@@ -178,17 +199,23 @@ export declare const USAGE_DECISION_MAX_AGE_MS: number;
  */
 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}.
+ * Whether this candidate carries a GENUINELY-STALE usage number: a snapshot with
+ * windows whose capture time is older than {@link USAGE_STALE_REFUSAL_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.
+ * ago, and a box whose refresh is failing stays wrong indefinitely. Two things
+ * make it NARROWER than "not verified":
+ *   1. It uses the wider REFUSAL bar, not the 5-min weighting bar. A merely
+ *      budget-paced idle account (10–30 min old) is not-verified — so it weights
+ *      at the floor, conservatively — but it is NOT "stale" and must not, on its
+ *      own, drive the whole provider to a NO_VERIFIED_USAGE refusal. Only a
+ *      genuinely broken refresh (hours old) trips this.
+ *   2. 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;
 /**

package/dist/lib/accounting/rotate.js

@@ -131,6 +131,27 @@ function isAvailableEligible(candidate) {
  * launched into it while the account was actually at its weekly cap.
  */
 export const USAGE_DECISION_MAX_AGE_MS = 5 * 60 * 1000;
+/**
+ * How old a usage snapshot may be before routing REFUSES to run at all
+ * (NO_VERIFIED_USAGE), as opposed to merely declining to *weight* by its number.
+ *
+ * These are two different risks and now two different bars. Weighting on a
+ * slightly-old number is cheap to get wrong (a floored weight, {@link
+ * USAGE_DECISION_MAX_AGE_MS} = 5 min); refusing to launch at all is expensive to
+ * get wrong — it fails the user's `agents run` outright. The daemon's usage
+ * refresher paces proactive fetches under a fixed per-provider budget
+ * (`usage-refresh.ts`, PROVIDER_HOURLY_BUDGET), so on a multi-account fleet an
+ * IDLE account is deliberately refreshed on a stretched round-robin cadence
+ * (bounded at N × spacing — ~16 min at 8 accounts, ~32 min at 16) rather than
+ * every 5 min, which would 429 the endpoint and park it for up to an hour. A
+ * budget-paced idle reading of 10–30 min is NOT the failure this refusal exists
+ * to catch. That failure is the `yosemite-s1` case: a box whose refresh is
+ * genuinely BROKEN, holding readings 26 h – 2.7 d old. 40 min sits comfortably
+ * above the worst-case budget cadence and still an order of magnitude below the
+ * multi-hour staleness of a broken box — and actively-used accounts refresh for
+ * free via the statusline ingest, so a *busy* account is never even this old.
+ */
+export const USAGE_STALE_REFUSAL_MAX_AGE_MS = 40 * 60 * 1000;
 /**
  * Whether this candidate's usage number is recent enough to route on. A missing
  * snapshot is unverified by definition — there is no number to trust.
@@ -152,24 +173,30 @@ export function isUsageVerified(candidate, nowMs = Date.now()) {
     return nowMs - capturedAt.getTime() <= USAGE_DECISION_MAX_AGE_MS;
 }
 /**
- * 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}.
+ * Whether this candidate carries a GENUINELY-STALE usage number: a snapshot with
+ * windows whose capture time is older than {@link USAGE_STALE_REFUSAL_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.
+ * ago, and a box whose refresh is failing stays wrong indefinitely. Two things
+ * make it NARROWER than "not verified":
+ *   1. It uses the wider REFUSAL bar, not the 5-min weighting bar. A merely
+ *      budget-paced idle account (10–30 min old) is not-verified — so it weights
+ *      at the floor, conservatively — but it is NOT "stale" and must not, on its
+ *      own, drive the whole provider to a NO_VERIFIED_USAGE refusal. Only a
+ *      genuinely broken refresh (hours old) trips this.
+ *   2. 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 function hasStaleUsage(candidate, nowMs = Date.now()) {
     const snapshot = candidate.usageSnapshot;
     const capturedAt = snapshot?.capturedAt;
     if (!capturedAt || !snapshot?.windows.length)
         return false;
-    return nowMs - capturedAt.getTime() > USAGE_DECISION_MAX_AGE_MS;
+    return nowMs - capturedAt.getTime() > USAGE_STALE_REFUSAL_MAX_AGE_MS;
 }
 function hasUsageAvailable(candidate) {
     const snapshot = candidate.usageSnapshot;
@@ -629,7 +656,7 @@ export function formatNoVerifiedUsageError(agent, strategy, candidates, nowMs =
             const staleness = age === null ? 'no usage snapshot' : `usage ${age}m old`;
             return `${c.version} (${staleness})`;
         }).join(', ');
-    const maxAgeMin = Math.round(USAGE_DECISION_MAX_AGE_MS / 60_000);
+    const maxAgeMin = Math.round(USAGE_STALE_REFUSAL_MAX_AGE_MS / 60_000);
     return `agents: NO_VERIFIED_USAGE — no signed-in ${agent} account has usage newer than ${maxAgeMin}m under strategy '${strategy}', so routing refuses to guess on a stale number: ${detail}. Refresh usage (agents view ${agent}) or pin the default with --strategy pinned.`;
 }
 /**

package/dist/lib/accounting/usage-sync.js

@@ -29,7 +29,7 @@ import { buildRemoteAgentsInvocation, buildWindowsStdinAgentsCommand, remoteShel
 import { resolveRemoteOsSync } from '../hosts/remote-os.js';
 import { loadDevicesSync } from '../devices/registry.js';
 import { sshTargetFor } from '../devices/connect.js';
-import { isHostPinned } from '../devices/known-hosts.js';
+import { isHostPinned, isDevicePinned } from '../devices/known-hosts.js';
 import { machineId, normalizeHost } from '../session/sync/config.js';
 import { isHeadedDeviceRole, listConfiguredDeviceRoles, selfConfiguredDeviceRole, } from '../device-config.js';
 import { exportClaudeUsageCacheRows, ingestPeerClaudeUsageRows, } from './usage.js';
@@ -154,7 +154,7 @@ export function pullUsageFromPrimary(deps = {}) {
     const primary = devices
         .filter((device) => roles[device.name] === 'personal')
         .concat(devices.filter((device) => roles[device.name] === 'desktop'))
-        .find((device) => device.tailscale?.online !== false && isPinned(device.name));
+        .find((device) => device.tailscale?.online !== false && isDevicePinned(device, isPinned));
     if (!primary) {
         result.error = 'no reachable, pinned personal or desktop device is configured as the usage primary';
         return result;
@@ -205,7 +205,7 @@ export function syncFleetUsageSnapshots(deps = {}) {
         name: d.name,
         role: roles[d.name],
         online: d.tailscale?.online !== false,
-        pinned: isPinned(d.name),
+        pinned: isDevicePinned(d, isPinned),
     }));
     const rows = (deps.exportRows ?? exportClaudeUsageCacheRows)();
     const plan = planUsagePush(isHeadedDeviceRole(selfRole), Object.keys(rows).length > 0, targets);

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

@@ -172,6 +172,18 @@ export interface UsageSnapshot {
     sourceLabel: string;
     capturedAt: Date | null;
     windows: UsageWindow[];
+    /**
+     * Last-known windows the freshness gate DROPPED from `windows` — expired by
+     * `resetsAt`/`windowMinutes`, or from a rolled-over billing period. VIEW-ONLY:
+     * `agents view` renders these with a staleness age ("30% · 6h old") so the
+     * user always sees the last number instead of a bare "unavailable". Routing
+     * MUST NEVER read this field — `isUsageVerified`/`hasStaleUsage`/
+     * `hasUsageAvailable`/`deriveUsageStatusFromSnapshot` consult only `windows`,
+     * so a stale number rendered here can never make a stale account read as
+     * verified or eligible (the RUSH-2858 property). Never serialized to the
+     * on-disk cache or `--json` (both project `windows` explicitly).
+     */
+    staleWindows?: UsageWindow[];
     plan?: string | null;
     /** Action that makes an event-fed source emit a current reading. */
     refreshHint?: string | null;