@phnx-labs/agents-cli 1.22.57 → 1.22.59

package/dist/commands/sync.js

@@ -45,6 +45,7 @@ import { runLaunchSync } from '../lib/project-launch.js';
 import { formatKeptProjectResources } from '../lib/project-resources.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { runUmbrellaSync } from '../lib/sync-umbrella.js';
+import { verifyVersionConverged, formatResidualDrift } from '../lib/sync-status.js';
 import { addHostOption } from '../lib/hosts/option.js';
 import { syncRepoGit, adoptUserRepoIfNeeded, recordUserRepoRemote, resolveUserRepoRemoteUrl } from '../lib/git.js';
 import { getSystemAgentsDir, getUserAgentsDir, getEnabledExtraRepos } from '../lib/state.js';
@@ -53,6 +54,46 @@ import { registerStatusCommand } from './status.js';
 function emitJson(payload) {
     console.log(JSON.stringify(payload));
 }
+/**
+ * Post-reconcile verification (PHNX-3186): after a sync writes into a set of
+ * version homes, re-read each home and confirm it now matches its resolved
+ * sources. The `agents sync` success line MUST NOT read "reconciled" while the
+ * drift it was asked to fix stays put. Any residual drifted/missing resource
+ * sets a non-zero exit code and — outside `--json` — names the exact unfixed
+ * drift so the operator sees what did not converge instead of a false ✓. Orphans
+ * are excluded (sync never removes them). Returns the residual for `--json`.
+ */
+function verifyReconciled(pairs, cwd) {
+    const residual = [];
+    const seen = new Set();
+    for (const { agent, version } of pairs) {
+        const key = `${agent}@${version}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const r = verifyVersionConverged(agent, version, cwd);
+        if (r)
+            residual.push(r);
+    }
+    // Residual drift is reported loudly via `ok:false` + the printed ⚠ block, but
+    // does NOT change the exit code — matching the declined-write precedent
+    // (RUSH-2700). The fleet fan-out (`agents sync --device all`) THROWS on a
+    // non-zero peer exit (`hosts/passthrough.ts`), discarding that box's JSON, so a
+    // non-zero exit here would hide the very `residualDrift` payload it emitted.
+    // Callers that must treat an incomplete sync as failure read `ok`/`residualDrift`
+    // from `--json`, exactly as they already do for declines.
+    return residual;
+}
+/** Print the residual-drift block naming exactly what did not converge. */
+function printResidual(residual, errLog) {
+    if (residual.length === 0)
+        return;
+    const lines = formatResidualDrift(residual);
+    errLog(chalk.yellow(`⚠ sync did not fully reconcile — ${lines.length} resource(s) still drift after writing:`));
+    for (const line of lines)
+        errLog(chalk.yellow(`  ${line}`));
+    errLog(chalk.gray('  Re-run the sync; a gap that survives a re-run is a real unreconcilable drift — report it.'));
+}
 /**
  * Translate per-kind CLI flags into a `ResourceSelection` for `buildSelection`.
  * Returns `undefined` when no kind flag was given (caller should use full sync).
@@ -429,6 +470,7 @@ async function runUmbrella(opts, quiet, outLog, errLog, json = false) {
         await runInteractiveReconcile(opts, outLog, errLog);
         return;
     }
+    const cwd = opts.cwd || process.cwd();
     const flags = {
         repos: opts.repos,
         secrets: opts.secrets,
@@ -459,10 +501,18 @@ async function runUmbrella(opts, quiet, outLog, errLog, json = false) {
         // --cloud (fetch-only, no local reconcile).
         if (!opts.cloud)
             evictCentralBrowserProfilesForSync(quiet, json, outLog, errLog);
+        // Post-reconcile verification (PHNX-3186): re-read every version the reconcile
+        // wrote into and confirm it now matches source. Without this the umbrella
+        // printed `✓ sync: reconciled` unconditionally, the exact false-success the
+        // ticket reports. Residual drift downgrades the line and sets a non-zero exit.
+        const residual = result.reconciled
+            ? verifyReconciled(result.reconciledVersions.map((r) => ({ agent: r.agent, version: r.version })), cwd)
+            : [];
         if (json) {
             emitJson({
-                // A refused resource is not a clean sync (RUSH-2700).
-                ok: result.declined.length === 0,
+                // A refused resource OR residual drift is not a clean sync (RUSH-2700 +
+                // PHNX-3186).
+                ok: result.declined.length === 0 && residual.length === 0,
                 mode: 'umbrella',
                 plan: result.plan,
                 repos: result.repos,
@@ -470,6 +520,7 @@ async function runUmbrella(opts, quiet, outLog, errLog, json = false) {
                 devices: result.devices,
                 reconciled: result.reconciled,
                 declined: result.declined,
+                residualDrift: residual,
             });
             return;
         }
@@ -482,12 +533,18 @@ async function runUmbrella(opts, quiet, outLog, errLog, json = false) {
             if (result.secrets) {
                 parts.push(result.secrets.skipped ? 'secrets skipped' : `secrets ${result.secrets.pulled} pulled`);
             }
+            // Only claim "reconciled" when the reconcile actually converged. Residual
+            // drift is already printed loudly by verifyReconciled above; reflect it in
+            // the one-line summary rather than a bare ✓.
             if (result.reconciled)
-                parts.push('reconciled');
-            outLog(chalk.green(`✓ sync: ${parts.join(' · ') || 'nothing to do'}`));
+                parts.push(residual.length === 0 ? 'reconciled' : 'reconcile INCOMPLETE');
+            const symbol = residual.length === 0 ? chalk.green('✓') : chalk.yellow('⚠');
+            const line = `${symbol} sync: ${parts.join(' · ') || 'nothing to do'}`;
+            outLog(residual.length === 0 ? chalk.green(line) : chalk.yellow(line));
             const errs = [...(result.repos?.errors ?? []), ...(result.secrets?.errors ?? [])];
             for (const e of errs)
                 errLog(chalk.yellow(`  ! ${e}`));
+            printResidual(residual, errLog);
         }
     }
     catch (err) {
@@ -700,13 +757,23 @@ async function runSync(agentSpec, repoArg, opts) {
             if (!quiet && !json)
                 printSyncDetail(result, agentId, v, cwd);
         }
+        // Verify each version actually converged; a repo-scoped sync only touched
+        // that repo's kinds, so skip verification there (the other layers legitimately
+        // still differ and are not this run's responsibility).
+        const residual = repoScope
+            ? []
+            : verifyReconciled(versions.map(({ version: v }) => ({ agent: agentId, version: v })), cwd);
+        if (!quiet && !json)
+            printResidual(residual, errLog);
         if (json) {
             emitJson({
-                // Any version that refused a write makes the whole run not-ok (RUSH-2700).
-                ok: versions.every(({ result }) => result.declined.length === 0),
+                // Any version that refused a write, or any residual drift after the
+                // reconcile, makes the whole run not-ok (RUSH-2700 + PHNX-3186).
+                ok: versions.every(({ result }) => result.declined.length === 0) && residual.length === 0,
                 mode: 'agent-all',
                 agent: agentId,
                 repo: repoScope,
+                residualDrift: residual,
                 ...healedPointers,
                 versions: versions.map(({ version: v, result }) => ({
                     version: v,
@@ -901,6 +968,11 @@ async function runSync(agentSpec, repoArg, opts) {
         return;
     }
     const result = syncResourcesToVersion(agentId, version, selection, { projectDir, cwd, force, allowExecSurfaces: !!opts.allowExecSurfaces });
+    // Post-reconcile verification (PHNX-3186). Only for a FULL reconcile
+    // (`!selection`): an interactive subset-selection deliberately touched only the
+    // picked kinds, so the rest legitimately still differs and is not this run's
+    // failure. This is the exact path `agents sync <agent>[@version]` takes.
+    const residual = selection ? [] : verifyReconciled([{ agent: agentId, version }], cwd);
     // Compile project-scope rules into the workspace itself so each agent's
     // native loader picks up cwd/<INSTRUCTIONS_FILE>. projectDir is the
     // .agents/ directory; the workspace root is its parent.
@@ -910,8 +982,11 @@ async function runSync(agentSpec, repoArg, opts) {
         projectCompile = compileRulesForProject(projectRoot);
     }
     if (json) {
+        const base = agentSyncJson(agentId, version, result);
         emitJson({
-            ...agentSyncJson(agentId, version, result),
+            ...base,
+            ok: base.ok === true && residual.length === 0,
+            residualDrift: residual,
             ...healedPointers,
             projectCompile: projectCompile
                 ? {
@@ -928,6 +1003,7 @@ async function runSync(agentSpec, repoArg, opts) {
         return;
     // ---------- 6. Detailed output ----------
     printSyncDetail(result, agentId, version, cwd);
+    printResidual(residual, errLog);
     if (projectCompile?.compiled) {
         const linkInfo = projectCompile.symlinks.length > 0
             ? ` (+ ${projectCompile.symlinks.join(', ')})`

package/dist/commands/traces.js

@@ -109,6 +109,13 @@ async function handleSync(opts) {
         parts.push(chalk.dim('nothing new'));
     }
     console.log(parts.join(chalk.dim('  ·  ')));
+    // The per-session data can upload cleanly while the aggregated console shard
+    // fails to refresh (e.g. the sessions DB is locked by a running app). That used
+    // to be silent, so the console sat stale with no signal here (PHNX-3401).
+    if (result.indexError) {
+        console.log(chalk.yellow('  ⚠ console index not refreshed') +
+            chalk.dim(` (${result.indexError}) — dashboard may be stale; it will retry next sync`));
+    }
 }
 async function handleStatus() {
     const ledger = readSyncLedger();

package/dist/commands/versions.js

@@ -11,7 +11,7 @@ import { installVersion, removeVersion, listInstalledVersions, isVersionInstalle
 import { carryForwardSettings } from '../lib/settings-manifest.js';
 import { createShim, createVersionedAlias, supportsIsolatedInstall, isIsolationProtected, CONFIG_ENV_ISOLATED_AGENTS, removeShim, shimExists, getShimsDir, getShimPath, getPathShadowingExecutable, isShimsInPath, getPathSetupInstructions, addShimsToPath, switchConfigSymlink, switchHomeFileSymlinks, } from '../lib/installations/shims.js';
 import { isInteractiveTerminal, isPromptCancelled, requireInteractiveSelection } from './utils.js';
-import { tryAutoPull } from '../lib/git.js';
+import { tryAutoPullSystemRepo } from '../lib/git.js';
 import { getAgentsDir, getTrashVersionsDir } from '../lib/state.js';
 import { setHelpSections } from '../lib/help.js';
 import { updateSessionFilePaths } from '../lib/session/db.js';
@@ -630,10 +630,18 @@ export function registerVersionsCommands(program) {
     useCmd.action(async (agentArg, versionArg, options) => {
         try {
             const skipPrompts = options.yes || !isInteractiveTerminal();
-            // Auto-pull ~/.agents/.system if it's a git repo with remote (silent on success)
+            // Auto-pull ~/.agents/.system if it's a git repo tracking the EXPECTED
+            // system remote (silent on success). The system repo ships hooks that run
+            // as shell on tool events, so pulling from a repointed origin would be
+            // remote code execution — tryAutoPullSystemRepo refuses that (PHNX-2957).
             const agentsDir = getAgentsDir();
-            const pullResult = await tryAutoPull(agentsDir);
-            if (pullResult.pulled) {
+            const pullResult = await tryAutoPullSystemRepo(agentsDir);
+            if (pullResult.refused) {
+                console.error(chalk.red(`Refusing to auto-sync ~/.agents/.system: its origin (${pullResult.actualRemote}) is not the expected system repo.`));
+                console.error(chalk.gray('The system repo ships hooks that run on tool events; a fast-forward from an unexpected origin is not applied. ' +
+                    'Re-point it (git -C ~/.agents/.system remote set-url origin <expected>) or set AGENTS_SYSTEM_REPO, then re-run `agents setup --force`.'));
+            }
+            else if (pullResult.pulled) {
                 console.log(chalk.gray('Synced ~/.agents/.system from remote'));
             }
             // Support both "claude 2.0.65" and "claude@2.0.65" formats

package/dist/commands/view.js

@@ -4,7 +4,7 @@ import { termLink } from '../lib/format.js';
 import ora from 'ora';
 import * as fs from 'fs';
 import * as path from 'path';
-import { AGENTS, ALL_AGENT_IDS, accountDisplayLabel, getAllCliStates, getUnmanagedCliState, getAccountInfo, resolveAgentName, formatAgentError, agentLabel, colorAgent, } from '../lib/agents.js';
+import { AGENTS, ALL_AGENT_IDS, accountDisplayLabel, getAllCliStates, getUnmanagedCliState, getAccountInfo, credentialPresence, resolveAgentName, formatAgentError, agentLabel, colorAgent, } from '../lib/agents.js';
 import { ambientClaudeToken, loginHint } from '../lib/signin-badge.js';
 import { machineId } from '../lib/machine-id.js';
 import { authCacheKey, readAuthHealthCache } from '../lib/auth-health.js';
@@ -24,7 +24,7 @@ import { listNativeAccounts } from '../lib/account-registry.js';
 import { isGitRepo, getGitSyncStatus } from '../lib/git.js';
 import { getCentralRulesFileName } from '../lib/rules/rules.js';
 import { composeRulesFromState } from '../lib/rules/compose.js';
-import { getConfiguredRunStrategy } from '../lib/accounting/rotate.js';
+import { getConfiguredRunStrategy, isLaunchableSignedIn } from '../lib/accounting/rotate.js';
 import { resolveRunDefaults } from '../lib/run-defaults.js';
 import { resolveConfiguredModel } from '../lib/models.js';
 import { listProfiles, profileExists, profileSummary, readProfile } from '../lib/profiles.js';
@@ -1293,6 +1293,11 @@ export async function collectAgentsJson(filterAgentId, resourceSections, opts) {
             isolated: isVersionIsolated(agentId, version),
             isIsolatedDefault: getIsolatedDefault(agentId) === version,
             signedIn: info.signedIn,
+            // The strict per-version launch truth (vs the display `signedIn` above,
+            // which inherits the active/global HOME login). The same primitive
+            // `collectRunCandidates` uses locally, so remote `--device auto` placement
+            // is gated on identical launchability (PHNX-3466).
+            launchable: isLaunchableSignedIn(info.signedIn, credentialPresence(agentId, home)),
             authVerdict: authCache[authCacheKey(host, agentId, version)]?.verdict ?? null,
             email: info.email,
             accountId: info.accountId,

package/dist/index.d.ts

@@ -15,7 +15,7 @@
  *   - `__secrets-get` / `__secrets-ping` / `__secrets-lock` (SYNC_* tokens)
  *   - `__shim`
  *   - `__claude-statusline`
- *   - `__usage-ingest`
+ *   - `__usage-ingest` / `__usage-export`
  *   - `__daemon-run`
  *
  * The tokens are imported from the leaf module sync-commands.ts — the SAME

package/dist/index.js

@@ -15,7 +15,7 @@
  *   - `__secrets-get` / `__secrets-ping` / `__secrets-lock` (SYNC_* tokens)
  *   - `__shim`
  *   - `__claude-statusline`
- *   - `__usage-ingest`
+ *   - `__usage-ingest` / `__usage-export`
  *   - `__daemon-run`
  *
  * The tokens are imported from the leaf module sync-commands.ts — the SAME
@@ -84,6 +84,11 @@ if (process.argv[2] === '__usage-ingest') {
     const { runUsageIngest } = await import('./lib/accounting/usage-ingest.js');
     process.exit(await runUsageIngest());
 }
+if (process.argv[2] === '__usage-export') {
+    const { exportClaudeUsageCacheRows } = await import('./lib/accounting/usage.js');
+    process.stdout.write(JSON.stringify({ v: 1, rows: exportClaudeUsageCacheRows() }));
+    process.exit(0);
+}
 if (process.argv[2] === '__daemon-run') {
     const { runDaemon, log: daemonLog } = await import('./lib/daemon/daemon.js');
     // RUSH-2418: the daemon is the one always-on process here, and it ran with no

package/dist/lib/account-registry.d.ts

@@ -63,11 +63,15 @@ export declare function unbindAccount(nameOrId: string, target: string): void;
 /** Every target bound to `accountId`: this box's device-doc bindings merged over
  * the fleet-shared central bindings (PHNX-3315). */
 export declare function accountBindings(accountId: string, meta: Pick<Meta, 'accounts' | 'deviceAccounts'>): string[];
+export interface AccountSelection {
+    id: string;
+    source: 'explicit' | 'binding' | 'default';
+}
 /** Explicit selection wins over a configured per-harness default. */
 export declare function resolveAccountSelection(explicit: string | undefined, agent: AgentId, meta: Pick<Meta, 'accounts' | 'deviceAccounts'>, opts?: {
     useDefault?: boolean;
     target?: string;
-}): string | undefined;
+}): AccountSelection | undefined;
 export interface AddAccountOptions {
     baseUrl?: string;
 }

package/dist/lib/account-registry.js

@@ -20,6 +20,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as crypto from 'node:crypto';
 import * as yaml from 'yaml';
+import chalk from 'chalk';
 import { atomicWriteFileSync } from './fs-atomic.js';
 import { getUserAgentsDir, readMeta, updateMeta } from './state.js';
 import { deleteKeychainToken, getKeychainToken, hasKeychainToken } from './secrets/index.js';
@@ -307,18 +308,19 @@ export function accountBindings(accountId, meta) {
 /** Explicit selection wins over a configured per-harness default. */
 export function resolveAccountSelection(explicit, agent, meta, opts = {}) {
     if (explicit)
-        return explicit;
+        return { id: explicit, source: 'explicit' };
     // This box's device-doc bindings win over the fleet-shared central bindings
     // (PHNX-3315), so a per-box account attachment resolves without touching the
     // shared file. Defaults are genuinely fleet-shared and stay central.
     const bindings = { ...meta.accounts?.bindings, ...meta.deviceAccounts?.bindings };
     const bound = opts.target ? bindings[opts.target] : undefined;
     if (bound)
-        return bound;
+        return { id: bound, source: 'binding' };
     const deviceScoped = bindings[agent];
     if (deviceScoped)
-        return deviceScoped;
-    return opts.useDefault === false ? undefined : meta.accounts?.defaults?.[agent];
+        return { id: deviceScoped, source: 'binding' };
+    const defaulted = opts.useDefault === false ? undefined : meta.accounts?.defaults?.[agent];
+    return defaulted ? { id: defaulted, source: 'default' } : undefined;
 }
 function profileConsumers(name, base) {
     const dir = path.join(base, 'profiles');
@@ -371,19 +373,30 @@ export function renameAccount(oldName, newName, base = getUserAgentsDir()) {
     const rows = nativeRowsForNameOrId(meta, oldName);
     if (rows.length) {
         assertUniqueUnifiedName(newName, meta, doc, new Set(rows.map(account => account.id)));
-        // Sweep every row for the identity (PHNX-3206) in its owning store (PHNX-3315).
+        // Sweep every row for the identity (PHNX-3206) in its owning store (PHNX-3315)
+        // and any per-harness default that points to the old name or row ids.
         const rowScope = rows[0].scope;
+        const idsToRename = new Set([oldName, ...rows.map(row => row.id)]);
         updateMeta(current => {
+            const defaults = { ...current.accounts?.defaults };
+            for (const [agent, value] of Object.entries(defaults)) {
+                if (idsToRename.has(value))
+                    defaults[agent] = newName;
+            }
+            const next = { ...current, accounts: { ...current.accounts, defaults } };
             if (rowScope === 'device') {
                 const native = { ...current.deviceAccounts?.native };
                 for (const row of rows)
                     native[row.id] = { ...native[row.id], name: newName };
-                return { ...current, deviceAccounts: { ...current.deviceAccounts, native } };
+                next.deviceAccounts = { ...current.deviceAccounts, native };
             }
-            const native = { ...current.accounts?.native };
-            for (const row of rows)
-                native[row.id] = { ...native[row.id], name: newName };
-            return { ...current, accounts: { ...current.accounts, native } };
+            else {
+                const native = { ...current.accounts?.native };
+                for (const row of rows)
+                    native[row.id] = { ...native[row.id], name: newName };
+                next.accounts = { ...next.accounts, native };
+            }
+            return next;
         });
         return;
     }
@@ -391,6 +404,15 @@ export function renameAccount(oldName, newName, base = getUserAgentsDir()) {
     if (!account)
         throw new Error(`Unknown account '${oldName}'.`);
     assertUniqueUnifiedName(newName, meta, doc);
+    const idsToRename = new Set([account.name, account.id]);
+    updateMeta(current => {
+        const defaults = { ...current.accounts?.defaults };
+        for (const [agent, value] of Object.entries(defaults)) {
+            if (idsToRename.has(value))
+                defaults[agent] = newName;
+        }
+        return { ...current, accounts: { ...current.accounts, defaults } };
+    });
     renameBundle(account.name, newName); // moves metadata + secret, preserves ACCOUNT_ID
     renameProfileConsumers(account.name, newName, base);
 }
@@ -422,7 +444,7 @@ export function removeAccount(name, base = getUserAgentsDir()) {
     if (!account)
         throw new Error(`Unknown account '${name}'.`);
     const bindings = accountBindings(account.id, meta);
-    const defaults = Object.entries(meta.accounts?.defaults ?? {}).filter(([, id]) => id === account.id).map(([agent]) => agent);
+    const defaults = Object.entries(meta.accounts?.defaults ?? {}).filter(([, value]) => value === account.id || value === account.name).map(([agent]) => agent);
     if (bindings.length || defaults.length) {
         const refs = [...bindings.map(target => `binding ${target}`), ...defaults.map(agent => `default ${agent}`)];
         throw new Error(`Account '${account.name}' is still referenced by: ${refs.join(', ')}. Detach or clear those references before removing it.`);
@@ -505,9 +527,20 @@ export function resolveSpawnAccount(explicit, agent, version, meta, opts = {}) {
     const selection = resolveAccountSelection(explicit, agent, meta, { useDefault: opts.useDefault, target });
     if (!selection)
         return null;
-    const unified = findUnifiedAccount(selection, meta);
-    if (!unified)
-        throw new Error(`Unknown account '${selection}'.`);
+    const unified = findUnifiedAccount(selection.id, meta);
+    if (!unified) {
+        // A stale per-harness default is a preference, not a hard requirement: the
+        // machine stays runnable by falling back to balanced rotation. Bindings and
+        // explicit --account are intentional, so they still fail loud.
+        if (selection.source === 'default') {
+            process.stderr.write(chalk.yellow(`[agents] default account '${selection.id}' for ${agent} no longer exists on this machine; falling back to balanced selection. Clear the stale default with: agents accounts clear-default ${agent}\n`));
+            return null;
+        }
+        const remedy = selection.source === 'binding'
+            ? `Detach the stale binding with: agents accounts detach ${selection.id} ${target}`
+            : `Add an account named '${selection.id}' or remove the --account override.`;
+        throw new Error(`Unknown account '${selection.id}' for ${agent} harness. ${remedy}`);
+    }
     if (unified.kind === 'native') {
         if (unified.agent !== agent) {
             throw new Error(`Account '${unified.name}' is a ${unified.agent} login and cannot authenticate the ${agent} harness.`);

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

@@ -10,15 +10,26 @@
  * floor, so an account racing toward its 5h cap loses priority before it maxes.
  */
 export declare const PROJECTION_HORIZON_MIN = 30;
+/**
+ * The weight an account with NO usage snapshot draws. Absence of a usage signal
+ * is NOT capacity (specifications.md GWT-E5c, SING-1a): a null snapshot means
+ * "unverifiable", not "empty" — on a worker box every account reads null
+ * (setup-token lacks the `user:profile` scope, RUSH-2392), so scoring null as
+ * full capacity made the blind pool's top pick an account that was actually
+ * weekly-exhausted (PHNX-3392). Floored at 1, never 0: an all-unverified pool
+ * must still draw a pick rather than strand the launch.
+ */
+export declare const UNVERIFIED_WEIGHT = 1;
 /**
  * Weight one candidate by remaining routing capacity, deprioritized by how soon
  * it is projected to cap. The base is weekly headroom (`max(1, 100 - used)`);
- * an account with no live snapshot is treated as full-capacity (100) since there
- * is no signal to deprioritize it. `minutesToLimit` (the daemon's burn-rate
- * projection on the 5h session window) then scales that base: >= horizon (or
- * unknown) keeps full weight, and closer-to-cap scales toward the floor of 1 —
- * so a launch avoids an account projected to cap soon, not just a 100%-maxed
- * one. Pure + exported so the deprioritization is unit-tested directly (a
- * weighted-random draw is not).
+ * an account with no live snapshot is NOT full-capacity — absence of a usage
+ * signal is not evidence of headroom, so it draws `UNVERIFIED_WEIGHT` and any
+ * verified-healthy account outranks it (GWT-E5c). `minutesToLimit` (the daemon's
+ * burn-rate projection on the 5h session window) then scales that base: >=
+ * horizon (or unknown) keeps full weight, and closer-to-cap scales toward the
+ * floor of 1 — so a launch avoids an account projected to cap soon, not just a
+ * 100%-maxed one. Pure + exported so the deprioritization is unit-tested
+ * directly (a weighted-random draw is not).
  */
 export declare function capacityWeight(usedPercent: number | null, minutesToLimit: number | null): number;

package/dist/lib/accounting/capacity.js

@@ -10,19 +10,30 @@
  * floor, so an account racing toward its 5h cap loses priority before it maxes.
  */
 export const PROJECTION_HORIZON_MIN = 30;
+/**
+ * The weight an account with NO usage snapshot draws. Absence of a usage signal
+ * is NOT capacity (specifications.md GWT-E5c, SING-1a): a null snapshot means
+ * "unverifiable", not "empty" — on a worker box every account reads null
+ * (setup-token lacks the `user:profile` scope, RUSH-2392), so scoring null as
+ * full capacity made the blind pool's top pick an account that was actually
+ * weekly-exhausted (PHNX-3392). Floored at 1, never 0: an all-unverified pool
+ * must still draw a pick rather than strand the launch.
+ */
+export const UNVERIFIED_WEIGHT = 1;
 /**
  * Weight one candidate by remaining routing capacity, deprioritized by how soon
  * it is projected to cap. The base is weekly headroom (`max(1, 100 - used)`);
- * an account with no live snapshot is treated as full-capacity (100) since there
- * is no signal to deprioritize it. `minutesToLimit` (the daemon's burn-rate
- * projection on the 5h session window) then scales that base: >= horizon (or
- * unknown) keeps full weight, and closer-to-cap scales toward the floor of 1 —
- * so a launch avoids an account projected to cap soon, not just a 100%-maxed
- * one. Pure + exported so the deprioritization is unit-tested directly (a
- * weighted-random draw is not).
+ * an account with no live snapshot is NOT full-capacity — absence of a usage
+ * signal is not evidence of headroom, so it draws `UNVERIFIED_WEIGHT` and any
+ * verified-healthy account outranks it (GWT-E5c). `minutesToLimit` (the daemon's
+ * burn-rate projection on the 5h session window) then scales that base: >=
+ * horizon (or unknown) keeps full weight, and closer-to-cap scales toward the
+ * floor of 1 — so a launch avoids an account projected to cap soon, not just a
+ * 100%-maxed one. Pure + exported so the deprioritization is unit-tested
+ * directly (a weighted-random draw is not).
  */
 export function capacityWeight(usedPercent, minutesToLimit) {
-    const base = usedPercent === null ? 100 : Math.max(1, 100 - usedPercent);
+    const base = usedPercent === null ? UNVERIFIED_WEIGHT : Math.max(1, 100 - usedPercent);
     if (minutesToLimit === null || !Number.isFinite(minutesToLimit))
         return base;
     const factor = Math.max(0, Math.min(1, minutesToLimit / PROJECTION_HORIZON_MIN));

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

@@ -1,8 +1,9 @@
 import { type DeviceProfile } from '../devices/registry.js';
 import { type ConfiguredDeviceRole } from '../device-config.js';
-import { type CachedUsageSnapshot } from './usage.js';
+import { type CachedUsageSnapshot, type UsageSnapshot } from './usage.js';
 /** How long a single peer push may take before it is abandoned for this tick. */
 export declare const USAGE_PUSH_DEADLINE_MS = 20000;
+export declare const USAGE_PULL_DEADLINE_MS = 20000;
 /** The stdin envelope the `__usage-ingest` verb reads. `v` guards the shape. */
 export interface UsageSyncPayload {
     v: 1;
@@ -62,6 +63,33 @@ export interface UsageSyncDeps {
         message?: string;
     };
 }
+export interface UsagePullResult {
+    pulledFrom: string | null;
+    merged: number;
+    skipped: string | null;
+    error: string | null;
+}
+export interface UsagePullDeps {
+    selfRole?: () => ConfiguredDeviceRole | undefined;
+    listDevices?: () => DeviceProfile[];
+    listRoles?: () => Record<string, ConfiguredDeviceRole>;
+    isPinned?: (name: string) => boolean;
+    exportRows?: () => Record<string, CachedUsageSnapshot>;
+    readRow?: (usageKey: string) => Pick<UsageSnapshot, 'windows'> | null;
+    ingestRows?: (rows: Record<string, CachedUsageSnapshot>) => number;
+    /** Read the versioned payload from the primary. Default: ssh `__usage-export`. */
+    pull?: (device: DeviceProfile) => {
+        ok: boolean;
+        stdout?: string;
+        message?: string;
+    };
+}
+/**
+ * Pull usage from the fleet's primary headed device when this worker's local
+ * cache is empty or contains an expired row. `personal` is the primary role;
+ * a `desktop` is used only when the fleet has no personal device.
+ */
+export declare function pullUsageFromPrimary(deps?: UsagePullDeps): UsagePullResult;
 /**
  * Push the local identity-keyed usage snapshot to every reachable, pinned,
  * non-headed peer. A no-op on a non-headed box or when the local cache is empty.

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

@@ -25,16 +25,17 @@
  * The planner is pure so tests cover every skip/push branch with no SSH.
  */
 import { sshExec } from '../ssh-exec.js';
-import { buildRemoteAgentsInvocation, buildWindowsStdinAgentsCommand, remoteShellFor } from '../hosts/remote-cmd.js';
+import { buildRemoteAgentsInvocation, buildWindowsStdinAgentsCommand, remoteShellFor, stripClixml } from '../hosts/remote-cmd.js';
 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 { machineId, normalizeHost } from '../session/sync/config.js';
 import { isHeadedDeviceRole, listConfiguredDeviceRoles, selfConfiguredDeviceRole, } from '../device-config.js';
-import { exportClaudeUsageCacheRows } from './usage.js';
+import { exportClaudeUsageCacheRows, ingestPeerClaudeUsageRows, readClaudeUsageCache, } from './usage.js';
 /** How long a single peer push may take before it is abandoned for this tick. */
 export const USAGE_PUSH_DEADLINE_MS = 20_000;
+export const USAGE_PULL_DEADLINE_MS = 20_000;
 /**
  * Decide, per peer, whether to push the local usage snapshot. Pure.
  *
@@ -84,6 +85,79 @@ function defaultUsagePush(device, payload) {
         return { ok: false, message: res.stderr.trim() || `remote exit ${res.code}` };
     return { ok: true };
 }
+/** Production pull: read the primary's cache through its hidden export verb. */
+function defaultUsagePull(device) {
+    const target = sshTargetFor(device);
+    const os = resolveRemoteOsSync(device.name);
+    const remoteCmd = buildRemoteAgentsInvocation(['__usage-export'], undefined, os);
+    const res = sshExec(target, remoteCmd, { timeoutMs: USAGE_PULL_DEADLINE_MS });
+    if (res.timedOut)
+        return { ok: false, message: 'timed out' };
+    if (res.code !== 0)
+        return { ok: false, message: res.stderr.trim() || `remote exit ${res.code}` };
+    return { ok: true, stdout: res.stdout };
+}
+/**
+ * Pull usage from the fleet's primary headed device when this worker's local
+ * cache is empty or contains an expired row. `personal` is the primary role;
+ * a `desktop` is used only when the fleet has no personal device.
+ */
+export function pullUsageFromPrimary(deps = {}) {
+    const result = { pulledFrom: null, merged: 0, skipped: null, error: null };
+    if ((deps.selfRole ?? selfConfiguredDeviceRole)() !== 'worker') {
+        result.skipped = 'this device is not a worker';
+        return result;
+    }
+    const localRows = (deps.exportRows ?? exportClaudeUsageCacheRows)();
+    const readRow = deps.readRow ?? readClaudeUsageCache;
+    const localEntries = Object.entries(localRows);
+    if (localEntries.length > 0 && localEntries.every(([key, row]) => {
+        const fresh = readRow(key);
+        return fresh !== null && fresh.windows.length === row.windows.length;
+    })) {
+        result.skipped = 'local usage cache is fresh';
+        return result;
+    }
+    const devices = deps.listDevices?.() ?? Object.values(loadDevicesSync());
+    const roles = deps.listRoles?.() ?? (deps.listDevices
+        ? listConfiguredDeviceRoles(devices.map((device) => device.name))
+        : listConfiguredDeviceRoles());
+    const isPinned = deps.isPinned ?? isHostPinned;
+    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));
+    if (!primary) {
+        result.error = 'no reachable, pinned personal or desktop device is configured as the usage primary';
+        return result;
+    }
+    const outcome = (deps.pull ?? defaultUsagePull)(primary);
+    if (!outcome.ok) {
+        result.error = outcome.message ?? 'pull failed';
+        return result;
+    }
+    let payload;
+    try {
+        // A Windows usage primary's `agents.ps1` shim prepends a PowerShell CLIXML
+        // progress banner to stdout, exactly as every other remote-JSON boundary
+        // strips (remote-cmd.ts:325). Without this, a headed Windows box (win-mini
+        // is a live fleet device) makes every pull fail as "malformed JSON", the
+        // worker's cache stays null, and the PHNX-3392 capacity floor silently
+        // becomes the only thing standing between a blind pool and an exhausted pick.
+        payload = JSON.parse(stripClixml(outcome.stdout ?? ''));
+    }
+    catch {
+        result.error = 'primary returned malformed JSON';
+        return result;
+    }
+    if (!payload || payload.v !== 1 || typeof payload.rows !== 'object' || payload.rows === null || Array.isArray(payload.rows)) {
+        result.error = 'primary returned an unrecognized usage-sync payload shape';
+        return result;
+    }
+    result.pulledFrom = primary.name;
+    result.merged = (deps.ingestRows ?? ingestPeerClaudeUsageRows)(payload.rows);
+    return result;
+}
 /**
  * Push the local identity-keyed usage snapshot to every reachable, pinned,
  * non-headed peer. A no-op on a non-headed box or when the local cache is empty.