@phnx-labs/agents-cli 1.22.109 → 1.22.110

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.

package/dist/lib/accounting/usage.js

@@ -431,6 +431,7 @@ export async function getUsageInfoForIdentity(input, opts) {
             organizationId: input.info.organizationId,
             fileOnly: opts?.fileOnly,
             allowInteractiveLogin: opts?.allowInteractiveLogin,
+            nativeFileLogin: opts?.nativeFileLogin,
             signal: opts?.signal,
         });
     }
@@ -469,6 +470,7 @@ export async function getUsageInfoForIdentity(input, opts) {
     // Explicit refresh: block on the shared device collector.
     return fetchLiveUsageDeduped(input, usageKey, cached, opts?.fileOnly === true, {
         allowInteractiveLogin: opts?.allowInteractiveLogin === true,
+        nativeFileLogin: opts?.nativeFileLogin === true,
         signal: opts?.signal,
     });
 }
@@ -501,6 +503,7 @@ async function fetchLiveUsageDeduped(input, usageKey, cached, fileOnly, opts) {
                 usageScope: usageKey,
                 fileOnly,
                 allowInteractiveLogin: opts?.allowInteractiveLogin === true,
+                nativeFileLogin: opts?.nativeFileLogin === true,
                 signal: opts?.signal,
             });
             if (usage.snapshot) {
@@ -935,9 +938,10 @@ async function getClaudeUsageInfo(options) {
         // requires (the setup-token is user:inference → 403, RUSH-2392). It is unset
         // for every background caller, so the RUSH-1822 guarantee is untouched there.
         const oauth = await loadClaudeOauth(options?.home, {
-            accessTokenCache: true,
-            fileOnly: options?.fileOnly === true,
+            accessTokenCache: options?.nativeFileLogin !== true,
+            fileOnly: options?.fileOnly === true || options?.nativeFileLogin === true,
             allowInteractiveLogin: options?.allowInteractiveLogin === true,
+            nativeFileLogin: options?.nativeFileLogin === true,
         });
         if (!oauth?.accessToken) {
             // NOT the shared no-credential message: "sign in" is not a remedy here.
@@ -1612,7 +1616,33 @@ function deleteCachedClaudeOauth(service) {
  * `.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 function claudeHomeHasNativeOauthFile(home) {
+    return readClaudeNativeCredentialsFile(home) !== null;
+}
+function readClaudeNativeCredentialsFile(home) {
+    const credsPath = path.join(home ?? os.homedir(), '.claude', '.credentials.json');
+    try {
+        if (!fs.existsSync(credsPath))
+            return null;
+        const parsed = parseClaudeOauthPayload(fs.readFileSync(credsPath, 'utf-8'));
+        // A native rotating blob has a refresh token. A setup-token-shaped file
+        // (access only) is not a native login and must not be polled as one.
+        if (!parsed?.accessToken?.trim() || !parsed.refreshToken?.trim())
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
 export async function loadClaudeOauth(home, opts) {
+    // Headed usage poller: the native rotating blob in `.credentials.json` is
+    // the only credential that carries `user:profile` without opening the ACL
+    // keychain (Touch ID) or firing a setup-token that 403s on /oauth/usage.
+    if (opts?.nativeFileLogin === true) {
+        return readClaudeNativeCredentialsFile(home);
+    }
     // Read-only usage/probe callers (accessTokenCache) authenticate ONLY with a
     // file-based setup-token from the `auth` bundle — never Claude Code's
     // interactive login. The usage endpoint accepts any sk-ant-oat01 bearer, and
@@ -1963,6 +1993,8 @@ function serializeClaudeUsageSnapshot(snapshot) {
             resetsAt: window.resetsAt?.toISOString() || null,
             windowMinutes: window.windowMinutes,
         })),
+        freshnessSource: snapshot.freshness?.source,
+        pollerDevice: snapshot.freshness?.poller,
     };
 }
 /**
@@ -2028,6 +2060,9 @@ function deserializeClaudeUsageSnapshot(snapshot, now) {
         plan: snapshot.plan ?? null,
         refreshHint: snapshot.refreshHint ?? null,
         unavailable,
+        freshness: snapshot.freshnessSource
+            ? { source: snapshot.freshnessSource, poller: snapshot.pollerDevice }
+            : undefined,
     };
 }
 /**

package/dist/lib/auth-health.js

@@ -25,6 +25,8 @@ import { getCacheDir, readMeta } from './state.js';
 import { probeClaudeStatus, probeDroidStatus, probeKimiStatus, USAGE_HEADLESS_SCOPE_MARKER, readClaudeUsageCache, } from './accounting/usage.js';
 import { getVersionHomePath, listInstalledVersions } from './installations/versions.js';
 import { atomicWriteFileSync, ensureLockTarget, withFileLock } from './fs-atomic.js';
+import { selfConfiguredDeviceRole } from './device-config.js';
+import { mayIssueUsageEndpointProbe, trySpendUsageApiCall } from './usage-refresh.js';
 /** Maximum age of an auth verdict used for automatic routing decisions. */
 export const AUTH_PROBE_MAX_AGE_MS = 20 * 60_000;
 /** Agents with a live network probe wired up today. The rest are best-effort. */
@@ -455,6 +457,23 @@ export async function probeAuthHealth(agent, home, opts) {
             if (derived)
                 return derived;
         }
+        if (!mayIssueUsageEndpointProbe({
+            role: selfConfiguredDeviceRole(),
+            forceLive: opts?.forceLive,
+        })) {
+            return {
+                verdict: 'unverified',
+                checkedAt,
+                detail: 'setup-token box does not probe the usage endpoint',
+            };
+        }
+        if (opts?.forceLive !== true && usageScope && !trySpendUsageApiCall(usageScope, agent, checkedAt)) {
+            return {
+                verdict: 'unverified',
+                checkedAt,
+                detail: 'usage-endpoint budget already spent this hour',
+            };
+        }
         let probe;
         if (agent === 'claude')
             probe = await probeClaudeStatus(home, opts?.cliVersion, usageScope, opts?.signal);

package/dist/lib/claude-statusline.js

@@ -8,6 +8,7 @@ import { atomicWriteFileSync } from './fs-atomic.js';
 import { mergeClaudeUsageCacheWindows } from './accounting/usage.js';
 import { loadReminders, pickReminderForSession } from './reminders.js';
 import { readMeta } from './state.js';
+import { machineId } from './machine-id.js';
 export const CLAUDE_STATUSLINE_COMMAND = 'agents __claude-statusline';
 const DELEGATE_FILE = path.join('.agents', 'claude-statusline-delegate');
 // The private subcommand this feature runs. It is only ever invoked internally,
@@ -77,7 +78,11 @@ export function ingestClaudeStatusLineUsage(payload, identity) {
         sourceLabel: 'Claude response rate limits',
         capturedAt: new Date(),
         windows,
+        freshness: { source: 'statusline', poller: machineId() },
     });
+    void import('./accounting/usage-sync.js')
+        .then((mod) => mod.pushUsageSnapshotNow())
+        .catch(() => { });
     return true;
 }
 /**

package/dist/lib/computer/sessions-list.js

@@ -61,6 +61,7 @@
 import { query, truncate } from '../feed/events.js';
 import { formatRelativeTime } from '../session/relative-time.js';
 import { getSessionById, listComputerSessionRecords, pruneToolSessions } from '../session/db.js';
+import { sessionHeadline } from '../session/title.js';
 import { buildLaunchSessionIndex, resolveLaunchSession, } from '../browser/sessions-list.js';
 /** Max chars of a `run --task` description persisted to the ledger — see the
  *  module docblock's retention/privacy note. */
@@ -315,7 +316,7 @@ export function renderComputerSessionRows(rows) {
         const where = r.remoteHost ? `${r.machine} -> ${r.remoteHost}` : r.machine;
         const label = r.task ? truncate(r.task, 60) : (r.bundle ?? `pid ${r.pid}`);
         const link = r.linkStatus === 'linked' && r.linkedSession
-            ? `${r.linkedSession.agent} — ${r.linkedSession.label || r.linkedSession.topic || r.linkedSession.shortId}`
+            ? `${r.linkedSession.agent} — ${sessionHeadline(r.linkedSession) || r.linkedSession.shortId}`
             : r.linkStatus === 'unresolved'
                 ? 'unresolved (session not indexed here)'
                 : 'unlinked';

package/dist/lib/daemon/auth-sync-service.d.ts

@@ -25,6 +25,8 @@
  */
 import { BasePeriodicService, type DaemonContext } from './service.js';
 import type { DaemonServiceId } from '../daemon-services.js';
+export declare const AUTH_SYNC_TICK_MS: number;
+export declare const AUTH_SYNC_KICKOFF_MS = 60000;
 export declare class AuthSyncService extends BasePeriodicService {
     readonly id: DaemonServiceId;
     readonly intervalMs: number;

package/dist/lib/daemon/auth-sync-service.js

@@ -25,9 +25,9 @@
  */
 import { BasePeriodicService } from './service.js';
 import { USAGE_SYNC_TICK_MS } from './usage-sync-service.js';
-const AUTH_SYNC_TICK_MS = 15 * 60_000;
+export const AUTH_SYNC_TICK_MS = 15 * 60_000;
 const AUTH_SYNC_DEADLINE_MS = 2 * 60_000;
-const AUTH_SYNC_KICKOFF_MS = 60_000;
+export const AUTH_SYNC_KICKOFF_MS = 60_000;
 export class AuthSyncService extends BasePeriodicService {
     id = 'auth-sync';
     intervalMs = AUTH_SYNC_TICK_MS;

package/dist/lib/daemon/daemon.js

@@ -32,6 +32,7 @@ import { recordSubsystemOk, recordSubsystemError, recordSubsystemErrorReason, re
 import { ServiceSupervisor } from './supervisor.js';
 import { SessionIndexService } from './session-index-service.js';
 import { SessionSummarizerService } from './session-summarizer-service.js';
+import { SessionTitleService } from './session-title-service.js';
 import { MonitorEngineService } from './monitor-engine-service.js';
 import { AccountUsageService, AccountAuthService } from './account-state-daemon-service.js';
 import { CatchupService } from './catchup-service.js';
@@ -1070,6 +1071,12 @@ export async function runDaemon() {
         supervisor.register(new AttentionNotifyService());
     else
         log('INFO', 'Attention-notify service disabled');
+    // Session titles (PHNX-3797) — generates each session row's headline once,
+    // with a cheap model, off the request path.
+    if (isEnabled('session-title'))
+        supervisor.register(new SessionTitleService());
+    else
+        log('INFO', 'Session-title service disabled');
     // Watchdog, device-probe, and self-heal are all periodic services managed
     // by the ServiceSupervisor (RUSH-3193 P3). Each is gated the same way as
     // the socket services above; state-dir-check is registered separately,

package/dist/lib/daemon/session-title-service.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Session-title service (PHNX-3797) — the ONE generator of session headlines.
+ *
+ * Every session row's headline used to be the agent's latest transcript line.
+ * This service replaces it with a user-anchored NAME: it sweeps the local
+ * session index for recent sessions whose title is still the raw first user
+ * message, asks a {@link SessionTitleProvider} (the cloud cheap-model call by
+ * default) for a short action+object headline, and persists it
+ * (`lib/session/title.ts`). Because the value lands in the index, every consumer
+ * — the CLI list, the picker, `sessions watch --json`, the fleet mirror, AGI EXT
+ * — reads one title that was generated exactly once.
+ *
+ * Cost is bounded by construction, not by hope: at most
+ * {@link SESSION_TITLE_MAX_PER_TICK} generations per tick, only for sessions
+ * inside the display window, only for rows whose stored source key no longer
+ * matches their user text (so a titled session is a pure DB read forever after),
+ * and never for the titler's own spawned sessions. When the harness is missing
+ * or signed out every attempt fails, so the service backs off exponentially
+ * instead of respawning two processes a minute forever — the rows simply keep
+ * showing the user's own words, which is the honest fallback.
+ */
+import type { DaemonServiceId } from '../daemon-services.js';
+import { type SessionTitleRunner } from '../session/title.js';
+import { BasePeriodicService, type DaemonContext } from './service.js';
+export declare class SessionTitleService extends BasePeriodicService {
+    private readonly run?;
+    readonly id: DaemonServiceId;
+    readonly intervalMs: number;
+    readonly deadlineMs = 110000;
+    /** Let the box settle (shims, PATH, index warm) before spawning a harness. */
+    readonly startupDelayMs = 60000;
+    /** Ticks still to skip before the next attempt; 0 = attempt this tick. */
+    private skipTicks;
+    /** Skip count applied after the next all-failed sweep. */
+    private backoff;
+    /** `run` is the model-call seam (defaults to the real subprocess); tests inject one. */
+    constructor(run?: SessionTitleRunner | undefined);
+    protected onStart(_ctx: DaemonContext): Promise<void>;
+    protected onStop(): Promise<void>;
+    protected onTick(ctx: DaemonContext, signal: AbortSignal): Promise<void>;
+}