@adhdev/mesh-shared 1.0.82-rc.4 → 1.0.82-rc.40

package/src/node-facts.ts

@@ -97,6 +97,20 @@ export interface MeshNodeFactsProviderQuota {
          * rather than presenting them as a freshly measured value.
          */
         lastGoodWindows?: boolean
+        /**
+         * Unix ms the reporting node's NEXT scheduled retry of this transient
+         * failure is due (HTTP Retry-After wins when later). Re-stamped to the
+         * real backoff time on every failure — see daemon-core
+         * `updateFailureRetry`. Absent on persistent failures and on daemons
+         * predating the stamp.
+         */
+        retryAtMs?: number
+        /**
+         * True once the node has spent its bounded transient-retry budget and
+         * stopped retrying; the next look is the hourly backfill. Readers must
+         * stop calling retained numbers "refreshing" (`assessQuotaFreshness`).
+         */
+        retryExhausted?: boolean
         /**
          * Unix ms when the reporting node last ATTEMPTED a refresh of this
          * provider — deliberately distinct from `updatedAt`, which dates the
@@ -112,6 +126,41 @@ export interface MeshNodeFactsProviderQuota {
          * predating the field.
          */
         fetchedAt?: number
+        /**
+         * Provenance of the RETAINED reading when `lastGoodWindows` is true —
+         * the source/plan/measurement time of the snapshot that produced the
+         * carried numbers, as opposed to the top-level `source`/`planType`,
+         * which describe the fresh failed attempt. See daemon-core
+         * `QuotaMetadata.lastGood`.
+         */
+        lastGood?: {
+            measuredAt: number
+            source?: string
+            planType?: string | null
+            collectorScope?: string
+        }
+        /**
+         * `'background-collector'` when the snapshot came from a daemon-spawned
+         * probe rather than an executing CLI session; a failure with this scope
+         * is not evidence about a running session's sign-in.
+         */
+        collectorScope?: string
+        /**
+         * DISPLAY-ONLY copy of the last numbers this node measured when it can
+         * no longer prove they belong to the CURRENT account (lineage unknown,
+         * or the failure left no confirmed match). Never read by routing, gates
+         * or ranking: those keep treating the entry as unknown. Dashboards show
+         * it marked "account unconfirmed" with its age. Never set across a
+         * CONFIRMED account switch (both accounts known and different).
+         */
+        unconfirmedReading?: {
+            /** Unix ms the numbers were measured. */
+            measuredAt: number
+            session?: MeshNodeFactsQuotaWindow | null
+            weekly?: MeshNodeFactsQuotaWindow | null
+            monthly?: MeshNodeFactsQuotaWindow | null
+            buckets?: MeshNodeFactsProviderQuota['buckets']
+        }
         [extra: string]: unknown
     }
     [extra: string]: unknown
@@ -137,6 +186,8 @@ export interface MeshNodeFactsProviderEnablement {
 
 export interface MeshNodeFacts {
     schemaVersion: number
+    /** Cached CLI detection only; no paths or account data. */
+    providerInventory?: { observedAt: number; providers: Record<string, { installed: boolean }> }
     reportedAt: number
     daemonBuild?: MeshNodeFactsDaemonBuild
     providerVersions?: Record<string, string>
@@ -199,6 +250,24 @@ export interface MeshNodeFacts {
      * Booleans keyed by provider type only — no free text, no credentials.
      */
     providerEnablement?: Record<string, MeshNodeFactsProviderEnablement>
+    /**
+     * The reporting machine's stored quota RESERVE (daemon-core
+     * `ADHDevConfig.quotaReserve`, sparse, ≤ 2 KB, migration audit trail
+     * stripped): the "how much quota to leave for the person" bar that the
+     * coordinator's launch gate applies to THIS machine's snapshots.
+     * ★ABSENT means "this node did not tell us" (older daemon) and resolves to
+     * the code defaults — the same fail-open direction as before the field
+     * existed. Percentages, durations and hashed account keys only; no free
+     * text, no emails. Resolve with daemon-core `resolveQuotaReserve`; never
+     * read its fields directly.
+     */
+    quotaReserve?: {
+        version: 1
+        defaults?: Record<string, number>
+        pools?: Record<string, Record<string, number>>
+        accounts?: Record<string, Record<string, Record<string, number>>>
+        updatedAt?: string
+    }
     /** Future fields ride through opaquely — do not enumerate them in relays. */
     [extra: string]: unknown
 }
@@ -253,7 +322,7 @@ export function normalizeMeshNodeFacts(raw: unknown): MeshNodeFacts | undefined
  * the host `agy` itself uses; the unprefixed `cloudcode-pa` host 429s Google
  * AI Pro Antigravity accounts), and its credential lives in the OS keyring,
  * not the stale on-disk token file — see the provenance note in daemon-core
- * `quota/fetchers/antigravity.ts`. Supported on macOS and Windows; other
+ * `quota/fetchers/antigravity.ts`. Supported on macOS, Windows, and Linux; other
  * platforms report `unsupported` rather than guess at a keyring backend
  * nobody has verified.
  *

package/src/outbound-message.ts

@@ -160,6 +160,7 @@ export type SendRefusal =
     | 'no_target'
     | 'bootstrap_pending'
     | 'duplicate_dispatch'
+    | 'new_work_held'
     | 'internal_error'
 
 /**
@@ -278,6 +279,7 @@ export const SEND_REFUSAL_REASONS = [
     'no_target',
     'bootstrap_pending',
     'duplicate_dispatch',
+    'new_work_held',
     'internal_error',
 ] as const satisfies readonly SendRefusal[]
 
@@ -321,3 +323,20 @@ export function isOutboundMessage(value: unknown): value is OutboundMessage {
         && isSendPolicy(candidate.policy)
         && typeof candidate.createdAt === 'number'
 }
+
+const PASTED_OPEN_RE = /^\s*<pasted_content(?:\s+id="[^"]*")?\s*>\s*$/
+const PASTED_CLOSE_RE = /^\s*<\/pasted_content(?:\s+id="[^"]*")?\s*>\s*$/
+
+/**
+ * Drop the `<pasted_content>` envelope lines Claude Code wraps around a pasted
+ * input. Only a text that OPENS with the envelope is touched; anything else is
+ * returned unchanged. Shared across daemon transcript merge and web echo/display
+ * normalization so wrapped turns correlate identically.
+ */
+export function unwrapPastedContent(text: string): string {
+    const lines = text.replace(/\r\n?/g, '\n').split('\n')
+    const first = lines.findIndex((line) => line.trim())
+    if (first < 0 || !PASTED_OPEN_RE.test(lines[first])) return text
+    return lines.filter((line) => !PASTED_OPEN_RE.test(line) && !PASTED_CLOSE_RE.test(line)).join('\n')
+}
+

package/src/path-ownership.ts

@@ -34,7 +34,7 @@
 
 /** One normalized ownership entry: a repo-relative path, optionally a `**` subtree prefix. */
 export interface OwnedPathEntry {
-    /** Repo-relative path with forward slashes, no leading `./`, no trailing slash. */
+    /** Repo-relative path with forward slashes, no leading `./`, no trailing slash; empty for the whole-repo subtree. */
     readonly path: string
     /** True when this entry was declared as `<path>/**` (owns the whole subtree). */
     readonly subtree: boolean
@@ -159,16 +159,14 @@ export function normalizeOwnedPaths(input: unknown): NormalizeOwnedPathsResult {
 /** True when `path` is exactly `base`, or (when `base` is a subtree entry) nested under it. */
 function entryContains(base: OwnedPathEntry, path: string): boolean {
     if (path === base.path) return true
-    if (base.subtree && (path === base.path || path.startsWith(`${base.path}/`))) return true
+    // An empty subtree prefix is the repo root, so it contains every normalized path.
+    if (base.subtree && (base.path === '' || path.startsWith(`${base.path}/`))) return true
     return false
 }
 
 /** True when two normalized entries' claimed sets intersect (exact match, or one contains the other's directory). */
 function entriesOverlap(a: OwnedPathEntry, b: OwnedPathEntry): boolean {
-    if (a.path === b.path) return true
-    if (a.subtree && (b.path === a.path || b.path.startsWith(`${a.path}/`))) return true
-    if (b.subtree && (a.path === b.path || a.path.startsWith(`${b.path}/`))) return true
-    return false
+    return entryContains(a, b.path) || entryContains(b, a.path)
 }
 
 /** True when two declarations claim any overlapping path. Pure set comparison — no policy (refuse vs warn) here. */

package/src/protocol/daemon-server.ts

@@ -52,6 +52,9 @@ export const DAEMON_STATUS_EVENT_NAMES = [
     'agent:generating_completed',
     'agent:stopped',
     'monitor:no_progress',
+    // An owner decision (structured missions) needs the owner. Server-bound for the push only;
+    // the dashboard learns about decisions over P2P (`mission_decisions_list`).
+    'agent:decision_needed',
 ] as const
 export type DaemonStatusEventName = typeof DAEMON_STATUS_EVENT_NAMES[number]
 export const isDaemonStatusEventName = makeTypeGuard(DAEMON_STATUS_EVENT_NAMES)
@@ -62,6 +65,27 @@ export const isDaemonStatusEventName = makeTypeGuard(DAEMON_STATUS_EVENT_NAMES)
  * (`modalMessage`/`modalButtons`, CLAUDE.md "Push notification exception").
  * Mirror of daemon-core `DaemonStatusEventPayload`.
  */
+/**
+ * Owner-decision push payload (design §9, owner decision D1 2026-10-28). The ONLY mission text that
+ * reaches the server: the question (<=80 chars) and up to 3 option labels (<=24 chars). Never
+ * `context`, free-text answers, mission goal/summary or chat content.
+ */
+export type DecisionPushWire = {
+    meshId: string
+    missionId: string
+    itemId: string
+    question: string
+    options: Array<{ id: string; label: string }>
+    recommended?: string
+    urgency: 'normal' | 'blocking'
+    dueAt?: string
+    /** `new` = freshly asked; `remind` = a blocking decision crossed its due time. */
+    reason: 'new' | 'remind'
+}
+export const DECISION_PUSH_QUESTION_MAX = 80
+export const DECISION_PUSH_OPTION_LABEL_MAX = 24
+export const DECISION_PUSH_OPTIONS_MAX = 3
+
 export type DaemonStatusEventWirePayload = {
     event: DaemonStatusEventName
     timestamp: number
@@ -73,8 +97,13 @@ export type DaemonStatusEventWirePayload = {
     elapsedSec?: number
     modalMessage?: string
     modalButtons?: string[]
+    modalKey?: string
+    approvalEvidence?: 'live' | 'cached' | 'unavailable'
+    waitKind?: 'external'
     surfaceHidden?: boolean
     muted?: boolean
+    /** Present only on `agent:decision_needed`. */
+    decision?: DecisionPushWire
 }
 
 // ─── Status report (mirror of daemon-core `CloudStatusReportPayload`) ──────
@@ -260,8 +289,8 @@ export const DAEMON_P2P_SIGNAL_TYPES = ['p2p_offer', 'p2p_ice'] as const
 export type DaemonP2PSignalType = typeof DAEMON_P2P_SIGNAL_TYPES[number]
 export const isDaemonP2PSignalType = makeTypeGuard(DAEMON_P2P_SIGNAL_TYPES)
 
-export type P2POfferWirePayload = { sdp: string; type: string; peerId: string }
-export type P2PIceWirePayload = { candidate: string; mid: string; peerId: string }
+export type P2POfferWirePayload = { sdp: string; type: string; peerId: string; attemptId?: number; attemptEpoch?: string; probe?: boolean }
+export type P2PIceWirePayload = { candidate: string; mid: string; peerId: string; attemptId?: number; attemptEpoch?: string; probe?: boolean }
 
 /**
  * A dashboard-originated signal as relayed to the daemon. `peerId` is stamped
@@ -273,6 +302,12 @@ export type P2PIceWirePayload = { candidate: string; mid: string; peerId: string
 export type RelayedP2PSignalWirePayload = {
     peerId?: string
     daemonId?: string
+    attemptId?: number
+    attemptEpoch?: string
+    /** p2p_ready only: the dashboard's stale-connect backoff index (see DashboardP2PReadyWirePayload). */
+    backoffStep?: number
+    /** Make-before-break relay->direct re-probe of an existing peer (see DashboardP2PReadyWirePayload). */
+    probe?: boolean
     sharePermission?: string
     shareTargetSessionId?: string
     sdp?: string

package/src/protocol/dashboard-server.ts

@@ -152,6 +152,9 @@ export type SystemAnnouncementWirePayload = {
 export type DashboardP2POfferWirePayload = {
     daemonId: string
     peerId?: string
+    attemptId?: number
+    attemptEpoch?: string
+    probe?: boolean
     sdp: string
     type: string
 }
@@ -159,6 +162,9 @@ export type DashboardP2POfferWirePayload = {
 export type DashboardP2PIceWirePayload = {
     daemonId: string
     peerId?: string
+    attemptId?: number
+    attemptEpoch?: string
+    probe?: boolean
     candidate: string
     mid?: string
     sdpMid?: string | null
@@ -234,11 +240,16 @@ export const DASHBOARD_P2P_SIGNAL_TYPES = ['p2p_ready', 'p2p_answer', 'p2p_ice']
 export type DashboardP2PSignalType = typeof DASHBOARD_P2P_SIGNAL_TYPES[number]
 export const isDashboardP2PSignalType = makeTypeGuard(DASHBOARD_P2P_SIGNAL_TYPES)
 
-export type DashboardP2PReadyWirePayload = { daemonId: string; peerId: string }
-export type DashboardP2PAnswerWirePayload = { daemonId: string; peerId: string; sdp: string; type: string }
+/** `backoffStep`: the dashboard's stale-connect backoff index (0 = 15s, 1 = 30s, 2 = 60s), so the daemon holds the connecting slot for the same window. */
+/** `probe`: identifier-only flag — this signal belongs to a make-before-break relay->direct re-probe of the SAME logical peer (never a new peer for the connection cap). */
+export type DashboardP2PReadyWirePayload = { daemonId: string; peerId: string; attemptId?: number; attemptEpoch?: string; backoffStep?: number; probe?: boolean }
+export type DashboardP2PAnswerWirePayload = { daemonId: string; peerId: string; sdp: string; type: string; attemptId?: number; attemptEpoch?: string; probe?: boolean }
 export type DashboardP2PLocalIceWirePayload = {
     daemonId: string
     peerId: string
+    attemptId?: number
+    attemptEpoch?: string
+    probe?: boolean
     candidate: string
     sdpMid: string | null
     sdpMLineIndex: number | null

package/src/provider-approval.ts

@@ -0,0 +1,59 @@
+/** Provider permissions are runtime decisions, never owner write ratification. */
+export interface ProviderApproval {
+    source: 'provider_modal' | 'legacy_provider' | 'status_only' | 'ledger_approval';
+    /** Exact Inbox actions or the existing session handler; never inferred consent. */
+    compatibility?: 'exact' | 'session_only' | 'unknown';
+    type: 'tool_permission' | 'provider_setup' | 'unknown';
+    evidence: 'live' | 'cached' | 'unavailable';
+    lifecycle: 'pending' | 'resolved';
+    modalKey: string | null;
+    createdAt: number | null;
+    resolvedAt: number | null;
+    description: string;
+    runtimeDirectory?: string;
+    displayedDirectory?: string | null;
+    buttons: string[];
+    actionable: boolean;
+    providerType?: string;
+    sessionId?: string;
+    nodeId?: string | null;
+    meshId?: string | null;
+    taskId?: string | null;
+    attemptId?: string | null;
+    generation?: number | null;
+}
+
+/** Exact resource identity required by the approvals-only action path. */
+export interface ProviderApprovalTarget {
+    modalKey: string;
+    attemptId: string | null;
+    generation: number | null;
+}
+
+/** Confirmed authority for the new Inbox path. Legacy handlers retain their own checks. */
+export function isActionableProviderApproval(approval: ProviderApproval | null | undefined): boolean {
+    return !!approval && approval.source === 'provider_modal' && approval.type === 'tool_permission'
+        && approval.lifecycle === 'pending' && approval.evidence === 'live' && approval.actionable
+        && !!approval.modalKey && Array.isArray(approval.buttons)
+        && approval.buttons.some(button => typeof button === 'string' && !!button.trim());
+}
+
+/** An explicit null suppresses the resource; only missing metadata uses compatibility. */
+export function readProviderDecision(approval: ProviderApproval | null | undefined, waiting: boolean, hasModal = false): ProviderApproval | null {
+    if (approval !== undefined) return approval && ['provider_modal', 'legacy_provider', 'status_only', 'ledger_approval'].includes(approval.source) ? approval : null;
+    if (!waiting) return null;
+    return { source: hasModal ? 'legacy_provider' : 'status_only', type: 'unknown',
+        compatibility: hasModal ? 'session_only' : 'unknown', evidence: 'unavailable',
+        lifecycle: 'pending', modalKey: null, createdAt: null, resolvedAt: null,
+        description: '', buttons: [], actionable: false };
+}
+
+/** Host metadata is durable: identity and clocks only, never modal text or directories. */
+export function providerApprovalSnapshot(approval: ProviderApproval | null | undefined): ProviderApproval | null {
+    if (!approval) return null;
+    const { source, type, lifecycle, modalKey, createdAt, resolvedAt, providerType, sessionId,
+        nodeId, meshId, taskId, attemptId, generation } = approval;
+    return { source, type, lifecycle, modalKey, createdAt, resolvedAt, providerType, sessionId,
+        nodeId, meshId, taskId, attemptId, generation, evidence: 'cached', actionable: false,
+        description: '', buttons: [] };
+}

package/src/provider-question.ts

@@ -0,0 +1,31 @@
+/** Ephemeral provenance supplied by the owning daemon, never inferred from prompt text. */
+export interface ProviderQuestionBinding {
+    transport: 'codex_rpc' | 'codex_async';
+    sessionId: string;
+    generation: string;
+    threadId: string;
+    turnId: string;
+    itemId: string;
+    requestId?: string | number;
+}
+
+export type ProviderQuestionLifecycle = 'pending' | 'submitted' | 'resolved' | 'completed' | 'cancelled' | 'expired' | 'unknown';
+
+export interface ProviderQuestionEpisode {
+    blocking?: boolean;
+    binding?: ProviderQuestionBinding;
+    lifecycle?: ProviderQuestionLifecycle;
+    /** Async dismiss is product-local; it is not a native tool cancellation. */
+    support?: 'request_bound' | 'product_local' | 'uncertain';
+}
+
+export function isProviderQuestionBinding(value: unknown): value is ProviderQuestionBinding {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+    const b = value as Record<string, unknown>;
+    if (b.transport !== 'codex_rpc' && b.transport !== 'codex_async') return false;
+    const keys = ['transport', 'sessionId', 'generation', 'threadId', 'turnId', 'itemId', ...(b.transport === 'codex_rpc' ? ['requestId'] : [])];
+    if (Reflect.ownKeys(b).some(key => typeof key !== 'string' || !keys.includes(key))) return false;
+    if (['sessionId', 'generation', 'threadId', 'turnId', 'itemId'].some(key => typeof b[key] !== 'string' || !(b[key] as string).trim())) return false;
+    return b.transport === 'codex_async' ? b.requestId === undefined
+        : (typeof b.requestId === 'string' && !!b.requestId.trim()) || (typeof b.requestId === 'number' && Number.isFinite(b.requestId));
+}

package/src/quota-freshness.ts

@@ -0,0 +1,139 @@
+/**
+ * Quota snapshot freshness — the ONE decision every display surface shares.
+ *
+ * Why this lives in the leaf package: the dashboard chips (web-core
+ * `quotaWindowCue`), the `adhdev quota` CLI (daemon-core `quota/cli.ts`) and the
+ * coordinator-facing `mesh_status` fold (mcp-server `summarizeNodeQuota`) each
+ * carried a hand-copied version of this rule, and a fix to one left the other
+ * two telling a different story about the same snapshot. They all call
+ * `assessQuotaFreshness` now; only the WORDING stays per-surface.
+ *
+ * Pure: plain objects in, plain object out, no clock except the `now` argument.
+ */
+import type { MeshNodeFactsProviderQuota } from './node-facts'
+
+export type QuotaFreshnessCue = 'refreshing' | 'stale'
+
+export interface QuotaFreshness {
+    /** Undefined = nothing to say (a fresh reading, or no retained numbers). */
+    cue?: QuotaFreshnessCue
+    /**
+     * Only the USER can produce a new reading (aged-out Claude statusline;
+     * expired CLI access token — the daemon never redeems it). The surface
+     * should say what to run, not promise a self-heal.
+     */
+    userMustAct: boolean
+    /**
+     * Unix ms by which the daemon will have looked again, for a `stale` reading
+     * the daemon re-checks on its own. Absent when the user must act, when the
+     * reading is `refreshing` (a retry is already scheduled), or when the check
+     * is already due.
+     */
+    nextCheckAt?: number
+}
+
+/**
+ * How long past `metadata.retryAtMs` a retry still reads as "in flight". The
+ * retry timer fires at retryAtMs and the probe itself takes a few seconds; a
+ * retryAtMs well in the past with no newer attempt means no retry is coming.
+ */
+export const QUOTA_RETRY_INFLIGHT_GRACE_MS = 60_000
+
+/**
+ * The daemon's backfill horizon: a snapshot is re-probed once it is this old
+ * even on an idle machine. Mirrors daemon-core `QUOTA_ROUTABLE_MAX_AGE_MS`
+ * (quota/refresh.ts); daemon-core's quota-freshness test pins the two equal.
+ */
+export const QUOTA_BACKFILL_HORIZON_MS = 60 * 60 * 1000
+
+function hasUsableWindow(window: { usedPercent?: unknown } | null | undefined): boolean {
+    return !!window && typeof window.usedPercent === 'number' && Number.isFinite(window.usedPercent)
+}
+
+/**
+ * Does the snapshot carry any renderable number — session/weekly/monthly
+ * windows OR per-pool buckets? `monthly` counts on its own: cursor-cli reports
+ * ONLY that axis, and leaving it out made a retained cursor reading look
+ * numberless. A window without a finite `usedPercent` is unknown, not 0%.
+ */
+function hasReading(quota: MeshNodeFactsProviderQuota): boolean {
+    if (hasUsableWindow(quota.session) || hasUsableWindow(quota.weekly) || hasUsableWindow(quota.monthly)) return true
+    return Array.isArray(quota.buckets) && quota.buckets.some((b) => !!b && typeof b.usedPercent === 'number' && Number.isFinite(b.usedPercent))
+}
+
+function finiteMs(value: unknown): number | undefined {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : undefined
+}
+
+/**
+ * When the daemon will next look, from the snapshot alone — the same
+ * "both clocks" rule the refresh loop's backfill uses (data age AND attempt
+ * age must both pass the horizon). Undefined when that moment has passed.
+ */
+function backfillCheckAt(quota: MeshNodeFactsProviderQuota, now: number): number | undefined {
+    const dataDue = finiteMs(quota.updatedAt)
+    const attempted = finiteMs(quota.metadata?.fetchedAt)
+    const dueAt = Math.max(
+        dataDue === undefined ? Number.NEGATIVE_INFINITY : dataDue + QUOTA_BACKFILL_HORIZON_MS,
+        attempted === undefined ? Number.NEGATIVE_INFINITY : attempted + QUOTA_BACKFILL_HORIZON_MS,
+    )
+    return Number.isFinite(dueAt) && dueAt > now ? dueAt : undefined
+}
+
+/**
+ * Which freshness cue a snapshot's retained numbers should carry.
+ *
+ *  - `stale` + `userMustAct` — nothing will refresh it without the user:
+ *      · `no-data` on any provider EXCEPT codex (Claude's statusline aged out —
+ *        a session must run). Codex's `no-data` is the daemon re-reading the
+ *        rollout files itself (≈60s while a CLI is active, ≤60 min idle), so it
+ *        is `stale` WITHOUT userMustAct;
+ *      · `expired-token` on Grok/Kimi/antigravity — only the owning CLI
+ *        renews it on use. An idle CLI has no background renewal cadence.
+ *        A scheduled quota retry does not itself renew credentials.
+ *  - `refreshing` — retained numbers after a transient failure with a retry
+ *    actually pending. ★Honest about the end of the retry budget: once the
+ *    daemon has stopped retrying (`metadata.retryExhausted`, or `retryAtMs`
+ *    long past with no newer attempt) the numbers are `stale` with the next
+ *    scheduled check, not "refreshing" for the up-to-60 minutes until the
+ *    hourly backfill. A snapshot with NO retry bookkeeping at all (a daemon
+ *    predating the stamp) keeps the old `refreshing` reading.
+ */
+export function assessQuotaFreshness(quota: MeshNodeFactsProviderQuota, now: number = Date.now()): QuotaFreshness {
+    const meta = quota.metadata
+    const kind = meta?.failureKind
+    const userMustAct = kind === 'no-data' && quota.provider !== 'codex-cli'
+    const awaitsCliUse = kind === 'expired-token' && ['grok-cli', 'kimi', 'antigravity-cli'].includes(quota.provider)
+    // Order matters: the aged-out Claude shape and the retained expired-token
+    // shape both ALSO mark lastGoodWindows, so they must be classified before
+    // the generic branch. An expired short-lived access token that the CLI
+    // renews itself is NOT an auth failure requiring user action (userMustAct:
+    // false), while any retained lastGood numbers are marked stale.
+    if (userMustAct) return hasReading(quota) ? { cue: 'stale', userMustAct: true } : { userMustAct: true }
+    if (awaitsCliUse) return hasReading(quota) ? { cue: 'stale', userMustAct: false } : { userMustAct: false }
+    if (meta?.lastGoodWindows !== true) {
+        // A successful fetch is not a perpetual live reading. Use the DATA
+        // clock; a recent failed attempt must never rejuvenate old numbers.
+        const measuredAt = finiteMs(quota.updatedAt)
+        if (hasReading(quota) && (measuredAt === undefined || now - measuredAt >= QUOTA_BACKFILL_HORIZON_MS)) {
+            return { cue: 'stale', userMustAct }
+        }
+        return { userMustAct }
+    }
+
+    const retryAtMs = finiteMs(meta?.retryAtMs)
+    const retryStopped = meta?.retryExhausted === true
+        || (retryAtMs !== undefined && retryAtMs + QUOTA_RETRY_INFLIGHT_GRACE_MS < now)
+    // A `no-data` retained reading (codex) has no retry at all — it is a
+    // snapshot the daemon will simply look at again, never an in-flight refresh.
+    if (kind !== 'no-data' && !retryStopped) return { cue: 'refreshing', userMustAct: false }
+    const nextCheckAt = backfillCheckAt(quota, now)
+    return nextCheckAt === undefined
+        ? { cue: 'stale', userMustAct: false }
+        : { cue: 'stale', userMustAct: false, nextCheckAt }
+}
+
+/** Whole minutes (min 1) until `nextCheckAt`, for the "next check ~Nm" wording. */
+export function minutesUntilQuotaCheck(nextCheckAt: number, now: number = Date.now()): number {
+    return Math.max(1, Math.round((nextCheckAt - now) / 60_000))
+}

package/src/relay-reprobe.ts

@@ -0,0 +1,117 @@
+/**
+ * Relay -> direct re-probe scheduler (pure, dependency-free).
+ *
+ * A P2P connection that settled on a TURN relay never looks for a direct path
+ * again. The owning transport (dashboard `P2PConnection`, daemon peer manager)
+ * uses this scheduler to periodically attempt a make-before-break probe: a
+ * SECOND peer connection (STUN-only) is built next to the working relay one and
+ * only swapped in once it is verified direct. The scheduler owns nothing but
+ * timing: backoff 60s -> 5min (doubling), jitter, and the stop conditions. The
+ * transport supplies `shouldProbe` (open + idle + visible) and `probe`.
+ */
+
+export type RelayReprobeOutcome = 'direct' | 'relay' | 'failed' | 'skipped'
+
+export interface RelayReprobeTiming {
+    /** First delay and the unit of growth (default 60s). */
+    baseDelayMs?: number
+    /** Backoff ceiling before jitter (default 5min). */
+    maxDelayMs?: number
+    /** +/- fraction applied to every delay (default 0.2). */
+    jitterRatio?: number
+}
+
+export const RELAY_REPROBE_BASE_DELAY_MS = 60_000
+export const RELAY_REPROBE_MAX_DELAY_MS = 5 * 60_000
+export const RELAY_REPROBE_JITTER_RATIO = 0.2
+
+/** Delay before the next attempt after `failures` consecutive non-direct outcomes. */
+export function computeRelayReprobeDelay(
+    failures: number,
+    random: () => number,
+    timing: RelayReprobeTiming = {},
+): number {
+    const base = timing.baseDelayMs ?? RELAY_REPROBE_BASE_DELAY_MS
+    const max = timing.maxDelayMs ?? RELAY_REPROBE_MAX_DELAY_MS
+    const jitter = timing.jitterRatio ?? RELAY_REPROBE_JITTER_RATIO
+    const grown = Math.min(max, base * 2 ** Math.max(0, failures))
+    const factor = 1 + jitter * (Math.min(1, Math.max(0, random())) * 2 - 1)
+    return Math.round(grown * factor)
+}
+
+export interface RelayReprobeSchedulerOptions extends RelayReprobeTiming {
+    random: () => number
+    setTimer: (callback: () => void, ms: number) => unknown
+    clearTimer: (handle: unknown) => void
+    /** Connected over relay, idle, tab visible, auth epoch unchanged... Re-checked on every tick. */
+    shouldProbe: () => boolean
+    /** One make-before-break attempt. Must never throw into the scheduler; a rejection counts as 'failed'. */
+    probe: () => Promise<RelayReprobeOutcome>
+}
+
+export class RelayReprobeScheduler {
+    private handle: unknown = null
+    private running = false
+    private inFlight = false
+    private failureCount = 0
+    private generation = 0
+
+    constructor(private readonly options: RelayReprobeSchedulerOptions) {}
+
+    get isRunning(): boolean { return this.running }
+    get failures(): number { return this.failureCount }
+    get probing(): boolean { return this.inFlight }
+
+    /** Begin probing (idempotent). Call when a connection is selected as relay. */
+    start(): void {
+        if (this.running) return
+        this.running = true
+        this.failureCount = 0
+        this.generation++
+        this.schedule()
+    }
+
+    /** Stop for good (direct path found, connection closed, auth epoch changed). */
+    stop(): void {
+        this.running = false
+        this.generation++
+        if (this.handle !== null) {
+            this.options.clearTimer(this.handle)
+            this.handle = null
+        }
+    }
+
+    private schedule(): void {
+        if (!this.running) return
+        const generation = this.generation
+        const delay = computeRelayReprobeDelay(this.failureCount, this.options.random, this.options)
+        this.handle = this.options.setTimer(() => {
+            this.handle = null
+            void this.tick(generation)
+        }, delay)
+    }
+
+    private async tick(generation: number): Promise<void> {
+        if (!this.running || generation !== this.generation) return
+        if (this.inFlight || !this.options.shouldProbe()) {
+            this.schedule()
+            return
+        }
+        this.inFlight = true
+        let outcome: RelayReprobeOutcome
+        try {
+            outcome = await this.options.probe()
+        } catch {
+            outcome = 'failed'
+        }
+        this.inFlight = false
+        // stop()/restart while the probe was in flight: the verdict is stale.
+        if (!this.running || generation !== this.generation) return
+        if (outcome === 'direct') {
+            this.stop()
+            return
+        }
+        if (outcome !== 'skipped') this.failureCount++
+        this.schedule()
+    }
+}