@phnx-labs/agents-cli 1.22.107 → 1.22.110

package/dist/commands/sessions.js

@@ -37,6 +37,7 @@ import { inferSessionState } from '../lib/session/state.js';
 import { discoverSessions, queryIndexedSessions, countSessionsInScope, resolveSessionById, isCompleteSessionId, looksLikeSessionId, searchContentIndex, getSessionRoots, scopeToManaged } from '../lib/session/discover.js';
 import { findSessionsById, querySessions, readSessionContent, readArchivedSessionPreview } from '../lib/session/db.js';
 import { liveSessionMetas, fleetExecutionMachineById, reconcileLiveMetaMachine } from '../lib/session/live-metadata.js';
+import { sessionHeadline } from '../lib/session/title.js';
 import { filterTeamSessions, shouldShowTeamSessions, safeTeamText, groupSessionsByTeam, NO_TEAM_GROUP_KEY, } from '../lib/session/team-filter.js';
 import { parseSession } from '../lib/session/parse.js';
 import { runRemoteSessions, buildForwardedArgs, ensureWholeIndex } from '../lib/session/remote.js';
@@ -75,6 +76,7 @@ import { registerSessionsRenderCommand } from './sessions-render.js';
 import { registerSessionsTraceCommand } from './sessions-trace.js';
 import { registerSessionsShareCommand } from './sessions-share.js';
 import { registerSessionsImportCommand } from './sessions-import.js';
+import { registerSessionsBackupSetupCommand } from './sessions-backup-setup.js';
 import { registerSessionsMigrateCommand, registerSessionsMigrationsCommand } from './sessions-migrate.js';
 import { registerSessionsBackfillCommand } from './sessions-backfill.js';
 import { registerSessionsStatsCommand } from './sessions-stats.js';
@@ -350,6 +352,7 @@ export function buildSessionDescription(s) {
         return cleanPreview(parts.filter(Boolean).join(' · '));
     }
     // Terminal, headless, or sub-agent: todos + live preview, then label, then topic.
+    // ladder-exempt: the compact --active preview BASE (a live snippet), not the row's headline title.
     const base = s.preview || s.label || s.topic || '';
     return cleanPreview([todo, base].filter(Boolean).join(' · '));
 }
@@ -758,22 +761,39 @@ export function renderActiveRowLines(s, indent, termW) {
     // Line 2: label/topic + checklist (the identity, no longer buried) then the
     // jump locator. Skipped entirely when there is nothing to say. desc may carry a
     // clickable project link, so it also goes through fitCell.
+    const contIndent = indent + ' '.repeat(ROW_ID_W);
     const desc = formatActiveRowDescription(s);
     const loc = locatorBadge(s);
-    if (!desc && !loc)
-        return lines;
-    const contIndent = indent + ' '.repeat(ROW_ID_W);
-    const room2 = Math.max(0, termW - stringWidth(contIndent) - 2);
-    const locCell = fitCell(loc, room2);
-    const locW = stringWidth(locCell);
-    const descRoom = Math.max(0, room2 - (locW ? locW + 2 : 0));
-    const descCell = chalk.white(fitCell(desc || '-', descRoom));
-    let line2 = contIndent + chalk.dim('└ ') + descCell;
-    if (locCell)
-        line2 += '  ' + locCell;
-    if (stringWidth(line2) > termW)
-        line2 = truncateToWidth(line2, termW);
-    lines.push(line2);
+    if (desc || loc) {
+        const room2 = Math.max(0, termW - stringWidth(contIndent) - 2);
+        const locCell = fitCell(loc, room2);
+        const locW = stringWidth(locCell);
+        const descRoom = Math.max(0, room2 - (locW ? locW + 2 : 0));
+        const descCell = chalk.white(fitCell(desc || '-', descRoom));
+        let line2 = contIndent + chalk.dim('└ ') + descCell;
+        if (locCell)
+            line2 += '  ' + locCell;
+        if (stringWidth(line2) > termW)
+            line2 = truncateToWidth(line2, termW);
+        lines.push(line2);
+    }
+    // Secondary line (PHNX-3797 owner feedback): surface the most important recent
+    // agent message when it is a pending QUESTION or a NEEDS-YOU block — the urgency
+    // a rolling activity preview buries. Plain `activity` is already the preview on
+    // line 2, so it earns no extra line here; the full ranked message still rides
+    // the JSON/mirror feed for AGI EXT via `s.importantMessage`.
+    const important = s.importantMessage;
+    if (important && (important.kind === 'question' || important.kind === 'needs_you')) {
+        const glyph = important.kind === 'question' ? '? ' : '! ';
+        const room3 = Math.max(0, termW - stringWidth(contIndent) - 2 - glyph.length);
+        const msgCell = fitCell(cleanPreview(important.text), room3);
+        if (msgCell) {
+            let line3 = contIndent + chalk.dim(glyph + msgCell);
+            if (stringWidth(line3) > termW)
+                line3 = truncateToWidth(line3, termW);
+            lines.push(line3);
+        }
+    }
     return lines;
 }
 /** Render a single agent-session row inside an already-printed group header. */
@@ -2199,7 +2219,7 @@ export function printToolSearch(envelope) {
             ? truncate(sanitizeForTerminal(session.machine).replace(/\s+/g, ' '), 80)
             : '';
         const machine = machineName ? ` @ ${machineName}` : '';
-        const rawHeading = session.label || session.topic || session.project || session.shortId;
+        const rawHeading = sessionHeadline(session) || session.project || session.shortId;
         const heading = truncate(sanitizeForTerminal(rawHeading).replace(/\s+/g, ' '), Math.max(30, terminalWidth() - 20));
         console.log(`${chalk.cyan(session.shortId)}${chalk.gray(machine)}  ${heading}`);
         for (const call of session.calls) {
@@ -3373,7 +3393,7 @@ function printTeamsView(pool, liveIndex, hiddenUnmanaged = 0) {
     // degradation the --active teams rows use (active.ts resolveOrchestratorLabels).
     const labelById = new Map();
     for (const s of pool) {
-        const label = s.label || s.topic;
+        const label = sessionHeadline(s);
         if (label)
             labelById.set(s.id, cleanPreview(label));
     }
@@ -3503,7 +3523,7 @@ function renderArchivedSession(session, mode, options = {}) {
     const shown = sessionDisplayAgent(session);
     const agentColor = colorAgent(shown);
     const absTime = formatAbsoluteTime(session.timestamp);
-    const title = session.label || session.topic;
+    const title = sessionHeadline(session);
     console.log('');
     if (title)
         console.log(chalk.bold.white(title));
@@ -3561,9 +3581,10 @@ async function renderSession(session, mode, filters, options = {}) {
         const modelStr = stats.models.length > 0 ? chalk.yellow(`  ${stats.models.join(', ')}`) : '';
         const branchStr = session.gitBranch ? chalk.gray(` (${session.gitBranch})`) : '';
         const absTime = formatAbsoluteTime(session.timestamp);
-        // Auto-inferred title headline (user /rename > Claude ai-title > first-prompt
-        // topic) — the fastest way to recognize which task this session is.
-        const title = session.label || session.topic;
+        // Auto-inferred title headline (user /rename > Claude ai-title >
+        // daemon-generated title > first-prompt topic) — the fastest way to
+        // recognize which task this session is.
+        const title = sessionHeadline(session);
         if (title) {
             const badges = signalBadges(metaSignals(session));
             console.log(chalk.bold.white(title) + (badges ? '  ' + badges : ''));
@@ -4455,7 +4476,7 @@ async function renderArtifactsGlobal(query, listAll, name, scope) {
             spinner.stop();
             console.error(chalk.red(`Multiple sessions match "${query}":`));
             for (const m of queryMatches.slice(0, 10)) {
-                console.error(chalk.cyan(`  ${m.shortId}  ${m.id}  ${m.label ?? m.topic ?? ''}`));
+                console.error(chalk.cyan(`  ${m.shortId}  ${m.id}  ${sessionHeadline(m) ?? ''}`));
             }
             console.error(chalk.gray(ambiguityHint(byId, completeId)));
             process.exit(1);
@@ -4612,7 +4633,7 @@ async function renderOneSession(query, mode, scope) {
                 spinner.stop();
                 console.error(chalk.red(`Multiple sessions match "${query}":`));
                 for (const match of queryMatches.slice(0, 10)) {
-                    console.error(chalk.cyan(`  ${match.shortId}  ${match.id}  ${match.label ?? match.topic ?? ''}`));
+                    console.error(chalk.cyan(`  ${match.shortId}  ${match.id}  ${sessionHeadline(match) ?? ''}`));
                 }
                 console.error(chalk.gray(ambiguityHint(byId, completeId)));
                 process.exit(1);
@@ -5066,7 +5087,7 @@ export async function resolveSessionMetadata(selector, scope, deps = { gatherRem
         for (const candidate of outcome.candidates) {
             const session = candidate.hits[0].session;
             const machines = candidate.hits.map(hit => hit.machine).join(', ');
-            console.error(chalk.cyan(`  ${session.shortId}  ${session.id}`) + chalk.gray(`  ${machines}  ${session.label ?? session.topic ?? ''}`));
+            console.error(chalk.cyan(`  ${session.shortId}  ${session.id}`) + chalk.gray(`  ${machines}  ${sessionHeadline(session) ?? ''}`));
         }
         console.error(chalk.gray(looksLikeSessionId(selector) ? 'Pass a longer ID to narrow it down.' : 'Narrow the keywords to one session.'));
         process.exit(1);
@@ -5106,7 +5127,7 @@ export async function resolveSessionAcrossFleet(query, mode, hosts, deps = { gat
         console.error(chalk.red(`Multiple sessions match "${query}" across the fleet:`));
         for (const candidate of candidates) {
             const s = candidate.hits[0].session;
-            const label = s.label ?? s.topic ?? '';
+            const label = sessionHeadline(s) ?? '';
             const machines = candidate.hits.map(hit => hit.machine).join(', ');
             console.error(chalk.cyan(`  ${s.shortId}  ${s.id}`) + chalk.gray(`  ${machines}  ${s.agent}${s.version ? ` ${s.version}` : ''}  ${label}`));
         }
@@ -5387,6 +5408,7 @@ export function registerSessionsCommands(program) {
     registerSessionsTraceCommand(sessionsCmd);
     registerSessionsShareCommand(sessionsCmd);
     registerSessionsImportCommand(sessionsCmd);
+    registerSessionsBackupSetupCommand(sessionsCmd);
     registerSessionsMigrateCommand(sessionsCmd);
     registerSessionsMigrationsCommand(sessionsCmd);
     registerSessionsBackfillCommand(sessionsCmd);

package/dist/commands/share.js

@@ -10,13 +10,13 @@ import { formatBytes } from '../lib/format.js';
 import { Argument, Option } from 'commander';
 import chalk from 'chalk';
 import { DEFAULT_BUCKET_NAME, DEFAULT_CF_BUNDLE, DEFAULT_SHARE_DOMAIN, DEFAULT_WORKER_NAME, generateWriteToken, readCloudflareCreds, readShareConfig, readWriteToken, readWriteTokenEnv, readWriteTokenFromBundle, storeWriteToken, writeShareConfig, } from '../lib/share/config.js';
-import { addCustomDomain, configureBucketLifecycle, createBucket, deployWorker, enableWorkersDev, findZoneId, hashWorkerScript, putWorkerSecret, updateWorker, WORKER_PHOENIX_ID_BASE_SECRET, setWorkerSecret, } from '../lib/share/provision.js';
+import { addCustomDomain, configureBucketLifecycle, createBucket, deployWorker, enableWorkersDev, findZoneId, hashWorkerScript, putWorkerSecret, updateWorker, WORKER_PHOENIX_ID_BASE_SECRET, WORKER_COLLAB_BASE_SECRET, WORKER_COLLAB_SERVICE_TOKEN_SECRET, setWorkerSecret, } from '../lib/share/provision.js';
 import { publishFile, resolveShareUsername, parseMetaEntries, sanitizeLabel, scanShareContent, formatSensitiveContentError, unlistedNotPrivateWarning, SHARE_VISIBILITY_LEVELS, PUBLISH_VISIBILITY_LEVELS, } from '../lib/share/publish.js';
 import { deleteShare, resolveDeleteTarget } from '../lib/share/delete.js';
 import { renderWorkerBundle } from '../lib/share/worker-template.js';
 import { analyticsEnabled } from '../lib/share/analytics.js';
 import { extractShareHttpError, formatShareHttpErrorDetail } from '../lib/share/http-error.js';
-import { phoenixIdBaseForDeploy, resolveShareBackend, shouldUseManaged, } from '../lib/share/backend.js';
+import { collabConfigForDeploy, phoenixIdBaseForDeploy, resolveShareBackend, shouldUseManaged, } from '../lib/share/backend.js';
 import { publishVisibility } from '../lib/storage/visibility.js';
 import { resolveGitHubUsername } from '../lib/git.js';
 import { refreshSessionAvatar } from '../lib/identity/index.js';
@@ -1271,6 +1271,15 @@ export async function runShareProvision(opts) {
             await putWorkerSecret(apiToken, accountId, workerName, WORKER_PHOENIX_ID_BASE_SECRET, phoenixIdBase, provisionOpts);
             spin.text = `Worker '${workerName}' Phoenix ID base set`;
         }
+        // Managed collaboration backend (PHNX-3835). Dormant unless BOTH
+        // PRIX_ARTIFACT_COLLAB_BASE and ARTIFACT_COLLAB_SERVICE_TOKEN are set in the
+        // deploy env; the service token rides the Secrets API, never rendered HTML.
+        const collab = collabConfigForDeploy({ managed: opts.managed }, { baseUrl, domain });
+        if (collab.collabBase && collab.collabServiceToken) {
+            await putWorkerSecret(apiToken, accountId, workerName, WORKER_COLLAB_BASE_SECRET, collab.collabBase, provisionOpts);
+            await putWorkerSecret(apiToken, accountId, workerName, WORKER_COLLAB_SERVICE_TOKEN_SECRET, collab.collabServiceToken, provisionOpts);
+            spin.text = `Worker '${workerName}' collaboration backend set`;
+        }
         spin.succeed('Provisioned');
         const cfg = {
             baseUrl,
@@ -1336,10 +1345,14 @@ export async function runShareUpdate(opts = {}) {
     }
     const writeToken = readWriteToken();
     const phoenixIdBase = phoenixIdBaseForDeploy({ managed: opts.managed }, cfg);
+    const collab = collabConfigForDeploy({ managed: opts.managed }, cfg);
     const provisionOpts = {
         ...(opts.request ? { request: opts.request } : {}),
         force: opts.force,
         ...(phoenixIdBase !== undefined ? { phoenixIdBase } : {}),
+        ...(collab.collabBase !== undefined
+            ? { collabBase: collab.collabBase, collabServiceToken: collab.collabServiceToken }
+            : {}),
     };
     const result = await updateWorker(apiToken, accountId, cfg.workerName, cfg.bucketName, worker, writeToken, cfg.templateHash, provisionOpts);
     if (!result.skipped) {

package/dist/commands/sync.js

@@ -190,7 +190,7 @@ export function registerSyncCommand(program) {
         .option('-y, --yes', 'Skip the interactive preview and auto-sync all detected resources', false)
         .option('--force', 'Re-sync even if no changes are detected since the last sync', false)
         .option('--quiet', 'Suppress all output (exit code indicates success)', false)
-        .option('--dry-run', 'Show what would be synced without making any changes', false)
+        .option('--dry-run', 'Show what would be synced without making any changes — requires an agent scope (e.g. agents sync claude --dry-run); the umbrella verb refuses it', false)
         .option('--allow-exec-surfaces', 'Allow syncing plugin exec surfaces (scripts, binaries) — off by default for safety', false)
         .option('--json', 'Emit machine-readable JSON (also accepted so fleet fan-out via --device all can parse each peer)', false)
         // Umbrella verb (no agent given): make this machine current.
@@ -480,6 +480,35 @@ function evictCentralBrowserProfilesForSync(quiet, json, outLog, errLog) {
  * a one-line summary. Stage failures are non-fatal and surfaced as warnings.
  */
 async function runUmbrella(opts, quiet, outLog, errLog, json = false) {
+    // `--dry-run` on the umbrella verb is NOT supported and must fail LOUD before
+    // touching anything (PHNX-3923). The umbrella composes stages that only exist
+    // as mutating operations — repo `git pull`, a full `refresh()` reconcile into
+    // every installed version home, central browser-profile eviction, device sync,
+    // and `repairAfterSync` — none of which carry a non-mutating preview mode. The
+    // old code ignored `opts.dryRun` entirely, ran `runUmbrellaSync` + evict +
+    // repair, and so MUTATED every native home despite `--dry-run`. Rather than
+    // ship a partial preview that silently skips the stages it cannot model (a
+    // lying "would sync" that contradicts the flag's promise), refuse here and
+    // point at the scoped path, which DOES honor `--dry-run` non-destructively.
+    if (opts.dryRun) {
+        const installed = MANAGED_AGENT_IDS.filter((id) => listInstalledVersions(id).length > 0);
+        const example = installed[0] ?? 'claude';
+        const error = '`agents sync --dry-run` has no umbrella preview: the machine-wide sync pulls repos, ' +
+            'reconciles every installed version, syncs devices, and repairs homes — stages that ' +
+            'cannot be previewed without making changes.';
+        const hint = `Preview one agent instead (this is non-destructive): agents sync ${example} --dry-run [--repo <repo>]`;
+        if (json) {
+            emitJson({ ok: false, mode: 'umbrella', dryRun: true, error, hint, installedAgents: installed });
+        }
+        else {
+            errLog(chalk.red(error));
+            errLog(chalk.gray(hint));
+            if (installed.length > 0)
+                errLog(chalk.gray(`Installed agents: ${installed.join(', ')}`));
+        }
+        process.exitCode = 1;
+        return;
+    }
     // Interactive bare `agents sync` (a TTY, no --yes, no scope flag) drops into
     // the two-checklist picker: which repos to sync from, which agents to sync
     // into. Any explicit flag, --yes, or --json keeps the non-interactive path.

package/dist/commands/utils.d.ts

@@ -45,6 +45,15 @@ export interface Surface {
  * to a single `const s = resolveSurface(cmd)` without changing its flag surface.
  */
 export declare function resolveSurface(cmd: Command): Surface;
+/**
+ * Coerce a `--device` value that may arrive as a scalar or an array to a single
+ * host string. A subcommand whose own `--device` collides in name with an
+ * ancestor's variadic `-D, --device <target...>` (e.g. `sessions inject`,
+ * `sessions resume` under the parent `sessions` command) can receive an array
+ * even when the command only ever targets one device — fail loud on more than
+ * one rather than guessing the first (PHNX-3688, PHNX-3940).
+ */
+export declare function normalizeSingleDeviceOption(value: string | string[] | undefined, commandLabel: string): string | undefined;
 /**
  * Exit with a clean message when a picker would be required in a non-interactive shell.
  */

package/dist/commands/utils.js

@@ -59,6 +59,24 @@ export function resolveSurface(cmd) {
         interactive: tty && !json,
     };
 }
+/**
+ * Coerce a `--device` value that may arrive as a scalar or an array to a single
+ * host string. A subcommand whose own `--device` collides in name with an
+ * ancestor's variadic `-D, --device <target...>` (e.g. `sessions inject`,
+ * `sessions resume` under the parent `sessions` command) can receive an array
+ * even when the command only ever targets one device — fail loud on more than
+ * one rather than guessing the first (PHNX-3688, PHNX-3940).
+ */
+export function normalizeSingleDeviceOption(value, commandLabel) {
+    const list = value == null ? [] : Array.isArray(value) ? value : [value];
+    const hosts = list.map((v) => String(v).trim()).filter((v) => v.length > 0);
+    if (hosts.length === 0)
+        return undefined;
+    if (hosts.length > 1) {
+        throw new Error(`${commandLabel} targets a single device, but --device named ${hosts.length}: ${hosts.join(', ')}.`);
+    }
+    return hosts[0];
+}
 /**
  * Exit with a clean message when a picker would be required in a non-interactive shell.
  */

package/dist/commands/watchdog.js

@@ -27,6 +27,7 @@ import { isWatchdogRotateEnabled, listRotateStates, setWatchdogRotateEnabled } f
 import { loadWatchdogSessions, runWatchdogPass } from '../lib/watchdog/service.js';
 import { readWatchdogEvents, WATCHDOG_LOG_PATH } from '../lib/watchdog/log.js';
 import { selectWatchdogHistory } from '../lib/watchdog/history.js';
+import { sessionHeadline } from '../lib/session/title.js';
 /** Default state dir the runner and these subcommands share. */
 function stateDir() {
     return path.join(getRuntimeStateDir(), 'watchdog');
@@ -99,7 +100,9 @@ export function formatWatchdogTickLines(result, willInject, verbose = false) {
                     : o.decision === 'nudge' ? 'WOULD-NUDGE'
                         : 'skip';
         const id = o.sessionId?.slice(0, 8) ?? 'no-session-id';
-        const title = o.label || o.name || o.topic;
+        // `name` is the `agents run --name` launch handle — a user-given name, so it
+        // ranks with the label; everything below it is the shared headline ladder.
+        const title = o.label || o.name || sessionHeadline(o);
         lines.push(`  ${tag.padEnd(11)} ${id}${title ? ` · ${title}` : ''}`);
         const metadata = [
             o.kind,

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

@@ -178,6 +178,14 @@ 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 *synced* snapshot (arrived from the account's poller through the
+ * fleet store) may be and still settle a routing decision. Matches the
+ * usage-sync tick so a worker that only ever sees 15-minute-old rows does not
+ * drop to the account picker. Local captures (`poll` / `statusline`) keep
+ * {@link USAGE_DECISION_MAX_AGE_MS}.
+ */
+export declare const USAGE_SYNC_TRUST_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.
@@ -212,6 +220,7 @@ export declare const USAGE_STALE_REFUSAL_MAX_AGE_MS: number;
  * running it refreshes that log. That self-reinforcing pin is exactly what the
  * narrowing rule below exists to prevent.
  */
+export declare function usageVerifiedMaxAgeMs(snapshot: UsageSnapshot | null | undefined): number;
 export declare function isUsageVerified(candidate: RotateCandidate, nowMs?: number): boolean;
 /**
  * Whether this candidate carries a GENUINELY-STALE usage number: a snapshot with

package/dist/lib/accounting/rotate.js

@@ -140,6 +140,14 @@ export async function isVersionLaunchableHere(agent, version) {
  * 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 *synced* snapshot (arrived from the account's poller through the
+ * fleet store) may be and still settle a routing decision. Matches the
+ * usage-sync tick so a worker that only ever sees 15-minute-old rows does not
+ * drop to the account picker. Local captures (`poll` / `statusline`) keep
+ * {@link USAGE_DECISION_MAX_AGE_MS}.
+ */
+export const USAGE_SYNC_TRUST_MS = 15 * 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.
@@ -174,12 +182,18 @@ export const USAGE_STALE_REFUSAL_MAX_AGE_MS = 40 * 60 * 1000;
  * running it refreshes that log. That self-reinforcing pin is exactly what the
  * narrowing rule below exists to prevent.
  */
+export function usageVerifiedMaxAgeMs(snapshot) {
+    // D8: a row that arrived via sync from the account's own poller is trusted
+    // for the sync cadence. A locally captured row (poll / statusline / unset)
+    // keeps the 5-minute bar — the poller is on this box and can refresh it.
+    return snapshot?.freshness?.source === 'sync' ? USAGE_SYNC_TRUST_MS : USAGE_DECISION_MAX_AGE_MS;
+}
 export function isUsageVerified(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() <= usageVerifiedMaxAgeMs(snapshot);
 }
 /**
  * Whether this candidate carries a GENUINELY-STALE usage number: a snapshot with
@@ -996,6 +1010,8 @@ function describeRotationCandidate(c, nowMs) {
         tier,
         source: snap?.source ?? null,
         sourceLabel: snap?.sourceLabel ?? null,
+        captureSource: snap?.freshness?.source ?? null,
+        pollerDevice: snap?.freshness?.poller ?? null,
         capturedAt: snap?.capturedAt ? snap.capturedAt.toISOString() : null,
         ageMs: capturedAtMs === null ? null : nowMs - capturedAtMs,
         windows: (snap?.windows ?? []).map((w) => ({ key: w.key, usedPercent: Math.round(w.usedPercent) })),

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

@@ -9,6 +9,16 @@
  */
 import { type ConfiguredDeviceRole } from '../device-config.js';
 import { type CachedUsageSnapshot } from './usage.js';
+/** Cadence of the usage-sync git tick — the trust window for a `sync` snapshot. */
+export declare const USAGE_SYNC_INTERVAL_MS: number;
+/** Re-publish an unchanged windowed row at least this often so workers' 15-min trust does not lapse. */
+export declare const USAGE_PUBLISH_HEARTBEAT_MS: number;
+/**
+ * Keep the previously published `capturedAt` when meters have not moved and
+ * the last publish is still inside the heartbeat. Stops statusline re-renders
+ * from dirtying the shared store (and taking the git lock) every few seconds.
+ */
+export declare function mergeUsageRowsForPublish(previous: Record<string, CachedUsageSnapshot> | undefined, next: Record<string, CachedUsageSnapshot>, nowMs?: number): Record<string, CachedUsageSnapshot>;
 /** Legacy hidden ingest/export envelope kept for older fleet CLI compatibility. */
 export interface UsageSyncPayload {
     v: 1;
@@ -29,6 +39,18 @@ export interface PublishUsageSnapshotResult {
 }
 /** Publish this headed device's stable usage snapshot into its owned store file. */
 export declare function publishUsageSnapshotToSharedStore(options?: PublishUsageSnapshotOptions): Promise<PublishUsageSnapshotResult>;
+/**
+ * Publish a changed snapshot immediately and exchange the shared repo so
+ * workers see it without waiting for the 15-minute tick. No-ops when the
+ * serialized store is unchanged (statusline re-renders with the same windows).
+ */
+export declare function pushUsageSnapshotNow(options?: PublishUsageSnapshotOptions & {
+    lockPath?: string;
+    timeoutMs?: number;
+}): Promise<{
+    published: PublishUsageSnapshotResult;
+    transport?: import('../fleet-shared-repo-sync.js').FleetSharedRepoSyncResult;
+}>;
 export interface ConsumeUsageSnapshotsOptions {
     userAgentsDir?: string;
     cachePath?: string;

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

@@ -12,6 +12,41 @@ import { readFleetSharedDeviceStates, updateFleetSharedDeviceStateAsync, } from
 import { getUserAgentsDir } from '../state.js';
 import { machineId, normalizeHost } from '../session/sync/config.js';
 import { exportClaudeUsageCacheRows, ingestPeerClaudeUsageRows, } from './usage.js';
+/** Cadence of the usage-sync git tick — the trust window for a `sync` snapshot. */
+export const USAGE_SYNC_INTERVAL_MS = 15 * 60_000;
+/** Re-publish an unchanged windowed row at least this often so workers' 15-min trust does not lapse. */
+export const USAGE_PUBLISH_HEARTBEAT_MS = 10 * 60_000;
+function usageMeterSignature(row) {
+    return JSON.stringify({
+        windows: row.windows,
+        plan: row.plan ?? null,
+        unavailable: row.unavailable ?? null,
+        freshnessSource: row.freshnessSource ?? null,
+        pollerDevice: row.pollerDevice ?? null,
+    });
+}
+/**
+ * Keep the previously published `capturedAt` when meters have not moved and
+ * the last publish is still inside the heartbeat. Stops statusline re-renders
+ * from dirtying the shared store (and taking the git lock) every few seconds.
+ */
+export function mergeUsageRowsForPublish(previous, next, nowMs = Date.now()) {
+    if (!previous)
+        return next;
+    const out = {};
+    for (const [key, row] of Object.entries(next)) {
+        const prior = previous[key];
+        if (prior && usageMeterSignature(prior) === usageMeterSignature(row)) {
+            const priorMs = prior.capturedAt ? Date.parse(prior.capturedAt) : NaN;
+            if (Number.isFinite(priorMs) && nowMs - priorMs < USAGE_PUBLISH_HEARTBEAT_MS) {
+                out[key] = { ...row, capturedAt: prior.capturedAt };
+                continue;
+            }
+        }
+        out[key] = row;
+    }
+    return out;
+}
 /** Publish this headed device's stable usage snapshot into its owned store file. */
 export async function publishUsageSnapshotToSharedStore(options = {}) {
     const result = {
@@ -26,13 +61,19 @@ export async function publishUsageSnapshotToSharedStore(options = {}) {
         result.skipped = 'this device is not a usage publisher (mark it personal or desktop)';
         return result;
     }
-    const rows = exportClaudeUsageCacheRows(options.cachePath);
-    if (Object.keys(rows).length === 0) {
+    const rawRows = exportClaudeUsageCacheRows(options.cachePath);
+    if (Object.keys(rawRows).length === 0) {
         result.skipped = 'no local usage snapshot to publish';
         return result;
     }
     try {
-        const write = await updateFleetSharedDeviceStateAsync(options.device ?? machineId(), { usage: { rows } }, options.userAgentsDir ?? getUserAgentsDir());
+        const device = options.device ?? machineId();
+        const userAgentsDir = options.userAgentsDir ?? getUserAgentsDir();
+        const prior = readFleetSharedDeviceStates(userAgentsDir).states
+            .find((state) => normalizeHost(state.device) === normalizeHost(device))
+            ?.usage?.rows;
+        const rows = mergeUsageRowsForPublish(prior, rawRows);
+        const write = await updateFleetSharedDeviceStateAsync(device, { usage: { rows } }, userAgentsDir);
         result.published = true;
         result.changed = write.changed;
         result.path = write.path;
@@ -42,6 +83,24 @@ export async function publishUsageSnapshotToSharedStore(options = {}) {
     }
     return result;
 }
+/**
+ * Publish a changed snapshot immediately and exchange the shared repo so
+ * workers see it without waiting for the 15-minute tick. No-ops when the
+ * serialized store is unchanged (statusline re-renders with the same windows).
+ */
+export async function pushUsageSnapshotNow(options = {}) {
+    const published = await publishUsageSnapshotToSharedStore(options);
+    if (!published.changed)
+        return { published };
+    const { syncFleetSharedStateRepo } = await import('../fleet-shared-repo-sync.js');
+    const transport = await syncFleetSharedStateRepo({
+        userAgentsDir: options.userAgentsDir,
+        device: options.device,
+        timeoutMs: options.timeoutMs,
+        lockPath: options.lockPath,
+    });
+    return { published, transport };
+}
 function capturedAtMs(row) {
     if (!row.capturedAt)
         return null;
@@ -70,15 +129,20 @@ export function consumeUsageSnapshotsFromSharedStore(options = {}) {
         for (const [identity, incoming] of Object.entries(state.usage.rows)) {
             if (!incoming || !Array.isArray(incoming.windows) || incoming.windows.length === 0)
                 continue;
+            const stamped = {
+                ...incoming,
+                freshnessSource: 'sync',
+                pollerDevice: incoming.pollerDevice ?? state.device,
+            };
             const current = rows[identity];
             if (!current) {
-                rows[identity] = incoming;
+                rows[identity] = stamped;
                 continue;
             }
-            const incomingMs = capturedAtMs(incoming);
+            const incomingMs = capturedAtMs(stamped);
             const currentMs = capturedAtMs(current);
             if (incomingMs !== null && (currentMs === null || incomingMs > currentMs))
-                rows[identity] = incoming;
+                rows[identity] = stamped;
         }
     }
     result.sources.sort();

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

@@ -157,6 +157,12 @@ export declare function claudeAccessTokenNeedsRefresh(expiresAt: number | null |
 export declare function setClaudeUsageCachePathForTest(cachePath: string | null): string | null;
 /** Discriminator for usage window types. */
 export type UsageWindowKey = 'session' | 'week' | 'sonnet_week' | 'month';
+/**
+ * How this box obtained a usage row (delta-spec D8). Distinct from
+ * {@link UsageSnapshot.source} (`live` | `last_seen`), which is how the
+ * number was collected from the harness/API.
+ */
+export type UsageCaptureSource = 'poll' | 'statusline' | 'sync';
 /** A single rate-limit window with utilization percentage and reset time. */
 export interface UsageWindow {
     key: UsageWindowKey;
@@ -203,6 +209,16 @@ export interface UsageSnapshot {
         reason: 'session_limit' | 'out_of_credits';
         resetsAt?: Date;
     };
+    /**
+     * D8 freshness provenance. A `sync` row arrived from the account's poller
+     * through the fleet store and is trusted for the sync cadence; `poll` and
+     * `statusline` are local captures and keep the 5-minute decision bar.
+     */
+    freshness?: {
+        source: UsageCaptureSource;
+        /** Device that polled or ingested the authoritative reading. */
+        poller?: string;
+    };
 }
 /** Usage data plus any error encountered while fetching. */
 export interface UsageInfo {
@@ -257,6 +273,13 @@ interface UsageOptions {
      * an unattended loop never transmits the interactive login to Anthropic.
      */
     allowInteractiveLogin?: boolean;
+    /**
+     * Headed usage poller: skip the setup-token and the ACL keychain, and read
+     * only `<home>/.claude/.credentials.json` (the native rotating blob). A
+     * setup-token 403s on `/api/oauth/usage`; the keychain pops Touch ID. The
+     * file blob is the Linux headed native login, and a no-op when absent.
+     */
+    nativeFileLogin?: boolean;
 }
 /** Canonical input for a single usage fetch operation. */
 export interface UsageFetchInput {
@@ -317,6 +340,10 @@ export interface CachedUsageSnapshot {
      * usage bucket.
      */
     modelRefusals?: Record<string, CachedModelRefusal>;
+    /** D8: `poll` | `statusline` | `sync`. Survives export → ingest. */
+    freshnessSource?: UsageCaptureSource;
+    /** D8: device that polled or ingested the authoritative reading. */
+    pollerDevice?: string;
 }
 /** The single registry of agent usage sources and their transport. */
 declare const USAGE_SOURCES: {
@@ -406,6 +433,8 @@ export interface UsageLookupOptions {
      * `loadClaudeOauth`. Unset for every other lookup.
      */
     allowInteractiveLogin?: boolean;
+    /** Headed poller: native `.credentials.json` only, never the setup-token. */
+    nativeFileLogin?: boolean;
 }
 export declare function getUsageInfoByIdentity(inputs: UsageIdentityInput[], opts?: UsageLookupOptions): Promise<{
     canonicalByUsageKey: Map<string, AccountInfo>;
@@ -712,10 +741,13 @@ export declare function normalizeDroidWindows(data: DroidBillingLimitsResponse):
  * `.credentials.json` only. Used by the daemon usage refresher so a background
  * tick can never pop Touch ID.
  */
+/** True when `<home>/.claude/.credentials.json` is a native rotating OAuth blob. */
+export declare function claudeHomeHasNativeOauthFile(home?: string): boolean;
 export declare function loadClaudeOauth(home?: string, opts?: {
     accessTokenCache?: boolean;
     fileOnly?: boolean;
     allowInteractiveLogin?: boolean;
+    nativeFileLogin?: boolean;
 }): Promise<ClaudeOauthCredentials | null>;
 /**
  * Save Claude OAuth credentials to the system keychain/keyring.