@phnx-labs/agents-cli 1.22.63 → 1.22.65

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # Changelog
 
+## 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).**
+  Attaching a Claude account to a version home on a headless worker now seeds the
+  home's identity and writes its `.oauth_token` from the account's non-rotating
+  setup-token already synced in the `auth` bundle, instead of refusing because the
+  home was never interactively signed in. This is what lets all accounts show as
+  logged in — and interactive worker runs authenticate (the shim's Linux
+  `.oauth_token` fallback) instead of dropping to the login screen. No rotating
+  OAuth credential is ever copied. Source: `apps/cli/src/commands/accounts.ts`,
+  `apps/cli/src/lib/claude-account-token.ts`.
+
+- Fixed Rush-backed feed channel sinks failing on Linux workers by handing delivery to a reachable macOS fleet peer with the Keychain-bound transport.
+
+- **Auto-produce the origin/main release attestation on merge (RUSH-2666).** A new
+  `attest-main.yml` workflow runs the full suite on every push to `main` and uploads
+  the exact-tree attestation + pretested tarball to a rolling `main-attestations`
+  GitHub Release, keyed by tree hash. `release.sh` now prefetches that proof into the
+  local store before waiting, so an ordinary release promotes without running the
+  suite inline — no more human running the suite by hand to unwedge a release. Purely
+  additive and fail-safe: on any fetch miss or error it falls back to exactly the
+  prior poll-then-`require` behavior, and a fetched proof is trusted only because the
+  existing exact-tree `require` re-verifies it. Source: `cli/scripts/release.sh`,
+  `.github/workflows/attest-main.yml`.
+
+- **Phoenix ID now uses the branded `id.byphoenix.com` API hostname by default (PHNX-3543).** New CLI sessions start and poll device authorization, resolve `whoami`, and bind managed share/traces Workers against the same canonical Phoenix ID base. The legacy hostname remains live for older installed clients. `PHOENIX_ID_BASE` remains an environment override for development and private deployments. Source: `src/lib/identity/client.ts`.
+
+- **A pre-launch `run.launch` event makes a launch into a logged-out version visible instead of silent.** `agents run <agent> --device auto --strategy balanced` (the VS Code "New Claude" flow) launched a version that was LOGGED OUT on the target box: `--device auto` (`applyDeviceAutoToOptions`) only ensures SOME account is ready on the device, not that the SPECIFIC version launched is signed in there, and the failure was invisible — the pinned/default path in `resolveRunVersion` returns without emitting `rotation.resolved`, and `run.dispatched` only fires at run FINALIZE (post-exit), but a logged-out agent sits at the login screen and never finalizes, so nothing was recorded. A new `run.launch` event is now emitted RIGHT BEFORE the harness child is spawned, on the device that will run it, so it fires even when the agent then sits stuck at a login screen. Both live launch paths are covered by one shared emitter: `spawnAgent` (after the tmux-durability gate, for the tmux-wrapped AND bare spawns) and the Windows `execShimPassthrough` shim (`resolvedVia: 'shim'`), which was the second blind spot. Payload: `module: 'run'`, `agent`, `version`, `strategy`, `signedIn` (the launchable-signed-in verdict for the SPECIFIC launched version on THIS device — REUSED from the rotated pick's `rotationResult.picked.signedIn` when the command already computed it, else derived via the new `isVersionLaunchableHere` helper, which applies the same `getVersionHomePath` -> `getAccountInfo` -> `isLaunchableSignedIn` gate as `collectRunCandidates`), `launchedLoggedOut` (the headline flag, `signedIn === false`), `email`, and `resolvedVia`; the device hostname is auto-stamped by `emit()`. It sits in the AUDIT lane — the sibling of `run.dispatched` and the more reliable stuck-launch signal — so `agents events --level audit --include runs` surfaces it. Purely additive observability — the emit is best-effort (it can never break a launch) and no routing/launch behavior changes; refusing to launch a logged-out version is a separate follow-up. Source: `cli/src/lib/exec.ts`, `cli/src/lib/accounting/rotate.ts`, `cli/src/lib/feed/events.ts`, `cli/src/lib/event-families.ts`, `cli/src/commands/exec.ts`.
+
+- **Live session rows carry outcome-card metrics and deliverables (PHNX-3574).** `agents sessions --active --json` and `agents sessions watch --json` now enrich each live row with indexed `tokenCount`, `durationMs`, and `subAgentCount`, plus created plan/artifact documents detected by the existing bounded transcript-tail state engine. Thin clients such as AGI EXT can render the initial request, progress, deliverables, team fan-out, runtime, and token use from the one canonical stream without polling or parsing transcripts themselves. Source: `cli/src/lib/session/active.ts`, `cli/src/lib/session/state.ts`.
+
 ## 1.22.63
 
 - **Managed share endpoint enforces a per-user storage quota, object limit, per-file size cap, and publish rate limit (PHNX-3542).** The managed `share.agents-cli.sh` Worker authenticated any Phoenix ID bearer and then accepted **unbounded** writes into shared R2 — no quota, no rate limit, no size cap — which blocked opening publishing to third parties. Each managed (Phoenix-identity) publish now charges a per-user usage ledger stored in R2 at `__usage/<owner>` (a conditional-put CAS object, mirroring the existing `__views`/`__handles` precedent — no Durable Object, no new binding): free tier is 200 MiB total, 150 canonical pages, 20 MiB per file, and 60 publishes/hour. Enforcement measures the **real request body** (bounded-buffered so a streaming body can't exceed the cap) and rejects on the true size **before any write**, so a spoofed-low declared size can't bypass the caps or destroy an existing page. It **fails loud** — `413` for a file, object-count, or byte-quota overage, `429` (with `Retry-After`) for the rate limit — and refunds bytes + object count on delete and on lazy expiry. Covers/views are server-generated overhead and excluded from the quota. BYO (`WRITE_TOKEN`) publishes write to the operator's own bucket at their own cost and are **unaffected** (a deliberate, documented policy). A `SHARE_PLANS` map is the seam for future paid tiers (billing follow-up PHNX-3569). Source: `cli/src/lib/share/worker-template.ts`.

package/dist/commands/accounts.d.ts

@@ -30,14 +30,15 @@ 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): void;
+export declare function writeClaudeInteractiveOauthToken(target: AttachTarget, targetAgent: AgentId, email?: string): void;
 export declare function parseBundleKey(raw: string): {
     bundle: string;
     key: string;

package/dist/commands/accounts.js

@@ -2,7 +2,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import chalk from 'chalk';
 import { password, select } from '@inquirer/prompts';
-import { resolveClaudeSetupToken } from '../lib/claude-account-token.js';
+import { readClaudeAccountEmail, resolveClaudeSetupToken, resolveClaudeSetupTokenForEmail, seedClaudeWorkerHomeIdentity } from '../lib/claude-account-token.js';
 import { setHelpSections } from '../lib/help.js';
 import { readMeta, updateMeta } from '../lib/state.js';
 import { ALL_AGENT_IDS, getAccountInfo, resolveAgentName } from '../lib/agents.js';
@@ -84,19 +84,25 @@ 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) {
+export function writeClaudeInteractiveOauthToken(target, targetAgent, email) {
     if (process.platform !== 'linux' || targetAgent !== 'claude' || target.kind !== 'installation')
         return;
     const versionHome = getVersionHomePath('claude', target.version);
     const tokenPath = path.join(versionHome, '.claude', '.oauth_token');
-    const token = resolveClaudeSetupToken(versionHome);
+    // Resolve by the attached account's email when known (a freshly-seeded worker
+    // home the `.claude.json` read below could not key on yet), else by the home's
+    // own recorded identity for a re-point/detach.
+    const token = email
+        ? resolveClaudeSetupTokenForEmail(email, versionHome)
+        : resolveClaudeSetupToken(versionHome);
     // A re-point (attach B over A, or a detach) can leave no setup-token resolving for
     // this version — B's may not be minted yet. A leftover file from the previous binding
     // would silently authenticate interactive runs as the OLD account (the shim's Linux
@@ -536,9 +542,30 @@ agents run codex#work`,
                 else {
                     if (t.kind !== 'installation')
                         throw new Error(`${account.agent} authentication is per-version. Attach '${account.name}' to a specific ${account.agent}@<version>.`);
-                    const identity = await nativeIdentityFromSource(target);
-                    if (identity.identityKey !== account.identityKey)
-                        throw new Error(`'${target}' is signed in to a different identity than account '${account.name}'.`);
+                    const versionHome = getVersionHomePath(t.agent, t.version);
+                    // The literal email keys the account's `auth`-bundle setup-token. It lives
+                    // in `identityLabel` — `identityKey` is a synthetic composite
+                    // (`claude:account=<uuid>:org=<uuid>`, agents.ts nativeIdentityKey), never
+                    // the address, so it must NOT be used to derive the token key.
+                    const accountEmail = account.identityLabel;
+                    // Headless-worker bootstrap: a keychain-less Linux worker home never had
+                    // an interactive login, so its `.claude.json` carries no identity and
+                    // `nativeIdentityFromSource` would reject the attach — yet the account's
+                    // non-rotating setup-token is already fleet-synced in the `auth` bundle.
+                    // Seed the identity (email only, no rotating credential) so the token
+                    // resolves; `writeClaudeInteractiveOauthToken` then writes `.oauth_token`.
+                    if (process.platform === 'linux' &&
+                        account.agent === 'claude' &&
+                        accountEmail &&
+                        !readClaudeAccountEmail(versionHome) &&
+                        resolveClaudeSetupTokenForEmail(accountEmail)) {
+                        seedClaudeWorkerHomeIdentity(versionHome, accountEmail);
+                    }
+                    else {
+                        const identity = await nativeIdentityFromSource(target);
+                        if (identity.identityKey !== account.identityKey)
+                            throw new Error(`'${target}' is signed in to a different identity than account '${account.name}'.`);
+                    }
                 }
             }
             else {
@@ -546,7 +573,7 @@ agents run codex#work`,
                 getAccountProvider(account.provider).envFor(targetAgent, account.auth);
             }
             bindAccount(name, target);
-            writeClaudeInteractiveOauthToken(t, targetAgent);
+            writeClaudeInteractiveOauthToken(t, targetAgent, account.kind === 'native' && account.agent === 'claude' ? account.identityLabel : undefined);
             console.log(chalk.green(`Attached ${account.name} to ${target}.`));
         });
     });

package/dist/commands/exec.js

@@ -2356,6 +2356,18 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
         // synthesize a same-agent fallback chain from the other healthy accounts
         // (issue #348). Stays null unless a non-pinned strategy actually rotated.
         let rotationResult = null;
+        // Precomputed launchable-signed-in verdict for the ACTUAL launched
+        // candidate, fed to the pre-launch `run.launch` event so it need not
+        // re-probe. Sourced per resolution branch from the candidate that WON, not
+        // the original auto-pick: the interactive picker (RUSH-2334 / PHNX-2526)
+        // deliberately lets the user launch a LOGGED-OUT account, which is a
+        // different candidate than `rotationResult.picked` — reading the verdict off
+        // the auto-pick there would report `launchedLoggedOut:false` for a version
+        // that is actually logged out, the exact false-negative this event exists to
+        // prevent. Left undefined for pinned-default / explicit-pin so emitRunLaunch
+        // falls back to probing the version home itself.
+        let launchSignedIn;
+        let launchEmail;
         // Set when the zero-healthy path already announced a deliberate
         // launch-to-sign-in, so the login preflight below does not repeat it.
         let signInLaunch = false;
@@ -2460,6 +2472,11 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                             if (!selected)
                                 return;
                             version = selected.version;
+                            // Source the run.launch verdict from the account the user ACTUALLY
+                            // picked — the picker may deliberately return a logged-out one
+                            // (RUSH-2334), so it can differ from rotationResult.picked.
+                            launchSignedIn = selected.signedIn;
+                            launchEmail = selected.email;
                             // Keep the rotation so mid-run failover can still cascade across
                             // the other (stale) healthy accounts after a real rejection.
                             rotationResult = resolved.rotation;
@@ -2476,6 +2493,12 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                     else if (resolved.version) {
                         version = resolved.version;
                         rotationResult = resolved.rotation;
+                        // The auto-pick already computed the launchable-signed-in verdict for
+                        // this exact version via the same gate — reuse it for run.launch.
+                        if (resolved.rotation) {
+                            launchSignedIn = resolved.rotation.picked.signedIn;
+                            launchEmail = resolved.rotation.picked.email;
+                        }
                         // A balanced/available pick of a PROVIDER account (setup-token /
                         // API-key) carries `providerAccount`. Resolve its env through the
                         // same `resolveSpawnAccount` path an explicit `--account` uses, so
@@ -2818,6 +2841,23 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             // forwards `--emit-session-id`): print the resolved session id as a
             // stdout sentinel so the launcher captures the id this run coined.
             emitSessionId: options.emitSessionId === true,
+            // Observability-only: carried onto the pre-launch `run.launch` event so
+            // the stream records HOW this version was chosen. Neither affects the
+            // spawn. `resolvedVia` attributes the version source cheaply — an
+            // explicit @version pin, a strategy rotation, or the pinned default.
+            strategy,
+            resolvedVia: rawVersion
+                ? 'explicit-pin'
+                : rotationResult
+                    ? 'rotated'
+                    : 'pinned-default',
+            // Launchable-signed-in verdict for the ACTUAL launched candidate, set per
+            // resolution branch above (auto-pick from rotation.picked; interactive
+            // picker from the user's `selected`, which may be logged out). Undefined
+            // for a pinned-default / explicit-pin launch, where spawnAgent probes the
+            // version home itself.
+            launchSignedIn,
+            launchEmail,
         };
         if (options.interactive && options.headless) {
             console.error(chalk.red('--interactive and --headless are mutually exclusive. Pass one, or neither (mode is inferred from prompt presence).'));

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

@@ -131,6 +131,28 @@ export declare function setGlobalRunStrategy(agent: AgentId, strategy: RunStrate
  * existing `signedIn` signal.
  */
 export declare function isLaunchableSignedIn(signedIn: boolean, presence: Pick<CredentialPresence, 'knownLocation' | 'perVersion'>): boolean;
+/** Launchable-signed-in verdict for ONE specific version on THIS device. */
+export interface VersionLaunchState {
+    /** True iff this exact version home can spawn a signed-in agent right now. */
+    launchable: boolean;
+    /** The version home's account email when launchable, else null. */
+    email: string | null;
+}
+/**
+ * Whether a SPECIFIC installed version is launchable-signed-in on THIS device,
+ * plus the account email when it is. Mirrors EXACTLY the per-version gate
+ * {@link collectRunCandidates} applies (getVersionHomePath -> getAccountInfo ->
+ * {@link isLaunchableSignedIn} over {@link credentialPresence}), so the
+ * pre-launch `run.launch` event can report the same signed-in verdict the
+ * balanced router computes for that version.
+ *
+ * The point is to make a launch into a logged-out version VISIBLE at spawn time:
+ * `--device auto` only guarantees SOME account is ready on the device, not that
+ * the specific version launched is signed in there (the yosemite-m3 2.1.219
+ * incident — 2.1.219 was logged out, the router correctly excluded it, yet it
+ * launched). Non-fatal by construction: callers wrap it best-effort.
+ */
+export declare function isVersionLaunchableHere(agent: AgentId, version: string): Promise<VersionLaunchState>;
 /**
  * How old a usage snapshot may be and still settle a routing DECISION.
  *
@@ -141,6 +163,27 @@ export declare function isLaunchableSignedIn(signedIn: boolean, presence: Pick<C
  * 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.
@@ -156,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;
 /**