@adhdev/mesh-shared 1.0.82-rc.2 → 1.0.82-rc.21

package/src/assistant-protocol.ts

@@ -18,15 +18,21 @@
 
 export const ASSISTANT_TOOLS = [
     'projects',
+    'environment',
+    'assistant_action',
+    'project_watch',
     'project_status',
     'project_send',
     'project_read',
     'project_add',
+    'project_attach_remote',
     'discover_repos',
     'memory',
     'skill_view',
     'skill_manage',
     'project_note',
+    'launch_defaults',
+    'launch_defaults_set',
 ] as const
 
 export type AssistantTool = typeof ASSISTANT_TOOLS[number]
@@ -41,15 +47,23 @@ export function isAssistantTool(value: unknown): value is AssistantTool {
 export const ASSISTANT_VERB = {
     // tool verbs
     projects: 'assistant_projects',
+    environment: 'assistant_environment',
+    action: 'assistant_action',
+    watch: 'assistant_project_watch',
+    executionState: 'assistant_execution_state',
+    executionSettings: 'assistant_execution_settings',
     projectStatus: 'assistant_project_status',
     projectSend: 'assistant_project_send',
     projectRead: 'assistant_project_read',
     projectAdd: 'assistant_project_add',
+    projectAttachRemote: 'assistant_project_attach_remote',
     discoverRepos: 'assistant_discover_repos',
     memory: 'assistant_memory',
     skillView: 'assistant_skill_view',
     skillManage: 'assistant_skill_manage',
     projectNote: 'assistant_project_note',
+    launchDefaults: 'assistant_launch_defaults',
+    launchDefaultsSet: 'assistant_launch_defaults_set',
     // assistant-side daemon verbs without a tool of the same name
     launch: 'launch_assistant',
     pendingRelays: 'assistant_pending_relays',
@@ -57,6 +71,9 @@ export const ASSISTANT_VERB = {
     stagedResolve: 'assistant_staged_resolve',
     storeAdmin: 'assistant_store_admin',
     importSkills: 'assistant_import_skills',
+    /** Projects the assistant is following (open relay threads) — list / stop following. */
+    threads: 'assistant_threads',
+    threadClose: 'assistant_thread_close',
 } as const
 
 export type AssistantVerb = typeof ASSISTANT_VERB[keyof typeof ASSISTANT_VERB]
@@ -64,15 +81,21 @@ export type AssistantVerb = typeof ASSISTANT_VERB[keyof typeof ASSISTANT_VERB]
 /** The daemon verb each assistant tool calls. */
 export const ASSISTANT_TOOL_VERBS: Readonly<Record<AssistantTool, AssistantVerb>> = {
     projects: ASSISTANT_VERB.projects,
+    environment: ASSISTANT_VERB.environment,
+    assistant_action: ASSISTANT_VERB.action,
+    project_watch: ASSISTANT_VERB.watch,
     project_status: ASSISTANT_VERB.projectStatus,
     project_send: ASSISTANT_VERB.projectSend,
     project_read: ASSISTANT_VERB.projectRead,
     project_add: ASSISTANT_VERB.projectAdd,
+    project_attach_remote: ASSISTANT_VERB.projectAttachRemote,
     discover_repos: ASSISTANT_VERB.discoverRepos,
     memory: ASSISTANT_VERB.memory,
     skill_view: ASSISTANT_VERB.skillView,
     skill_manage: ASSISTANT_VERB.skillManage,
     project_note: ASSISTANT_VERB.projectNote,
+    launch_defaults: ASSISTANT_VERB.launchDefaults,
+    launch_defaults_set: ASSISTANT_VERB.launchDefaultsSet,
 }
 
 /**
@@ -81,13 +104,15 @@ export const ASSISTANT_TOOL_VERBS: Readonly<Record<AssistantTool, AssistantVerb>
  * because they cause effects (a coordinator message or launch, a new
  * project), and MCP clients use readOnlyHint to skip confirmation.
  */
-export const ASSISTANT_WRITE_TOOLS: readonly AssistantTool[] = ['memory', 'skill_manage', 'project_note', 'project_send', 'project_add']
+export const ASSISTANT_WRITE_TOOLS: readonly AssistantTool[] = ['project_watch', 'assistant_action', 'memory', 'skill_manage', 'project_note', 'project_send', 'project_add', 'project_attach_remote', 'launch_defaults_set']
 
 /** Owner-only verbs: never reachable from the assistant's MCP server (no `ipc`). */
 export const ASSISTANT_OWNER_VERBS: readonly AssistantVerb[] = [
+    ASSISTANT_VERB.executionSettings,
     ASSISTANT_VERB.stagedResolve,
     ASSISTANT_VERB.storeAdmin,
     ASSISTANT_VERB.importSkills,
+    ASSISTANT_VERB.threadClose,
 ]
 
 /** The only assistant verbs accepted while an idle review turn is open (§4.10.7). */

package/src/index.ts

@@ -16,6 +16,7 @@ export * from './git-normalize'
 export * from './session-normalize'
 export * from './node-normalize'
 export * from './node-facts'
+export * from './quota-freshness'
 export * from './workspace-normalize'
 export * from './daemon-normalize'
 export * from './git-summarize'
@@ -41,3 +42,6 @@ export * from './turn-ipc'
 export * from './path-ownership'
 export * from './mission-brief'
 export * from './keyed-doc-delta'
+export * from './provider-approval'
+export * from './provider-question'
+export * from './launch-defaults'

package/src/keyed-doc-delta.ts

@@ -326,7 +326,15 @@ export function foldKeyedDoc<T extends Record<string, unknown>>(held: T, delta:
         const heldList = heldCollections.get(path)
         if (change?.absent) {
             const [head, tail] = splitPath(path)
-            if (!tail) delete next[head]
+            if (!tail) {
+                delete next[head]
+                continue
+            }
+            const parent = next[head]
+            if (!isRecord(parent) || !(tail in parent)) continue
+            const copy = { ...parent }
+            delete copy[tail]
+            next[head] = copy
             continue
         }
         if (!change && heldList === undefined) continue

package/src/launch-defaults.ts

@@ -0,0 +1,168 @@
+/** Daemon-local launch intent and command wire contract. P2P/local only;
+ * never include this document or its history in cloud status_report.
+ * Publication through mesh-shared's barrel is a later integration step. */
+export const LAUNCH_DEFAULT_ROLES = ['assistant', 'coordinator'] as const;
+export type LaunchDefaultRole = typeof LAUNCH_DEFAULT_ROLES[number];
+export const LAUNCH_DEFAULT_SOURCES = ['user', 'stored_default', 'project_default', 'provider_default'] as const;
+export type LaunchDefaultSource = typeof LAUNCH_DEFAULT_SOURCES[number];
+export const LAUNCH_DEFAULTS_NEXT_LAUNCH_NOTE = 'Applies to the next launch; running sessions are unchanged.';
+export function isLaunchDefaultRole(value: unknown): value is LaunchDefaultRole {
+    return typeof value === 'string' && (LAUNCH_DEFAULT_ROLES as readonly string[]).includes(value);
+}
+export function isLaunchDefaultSource(value: unknown): value is LaunchDefaultSource {
+    return typeof value === 'string' && (LAUNCH_DEFAULT_SOURCES as readonly string[]).includes(value);
+}
+export interface LaunchDefaultSelection {
+    provider: string;
+    /** Omission means pass no model/thinking argument, not inherit another provider. */
+    model?: string;
+    thinkingLevel?: string;
+}
+export type LaunchDefaultToolRestriction = 'enforced' | 'prompt_only';
+export type LaunchDefaultOrigin = 'owner' | 'human' | 'relay' | 'review' | 'review_tainted';
+export interface LaunchDefaultEntry extends LaunchDefaultSelection {
+    revision: number;
+    setBy: 'owner' | 'assistant';
+    setAt: number;
+}
+export interface LaunchDefaultChange {
+    at: number;
+    role: LaunchDefaultRole;
+    by: 'owner' | 'assistant';
+    origin: LaunchDefaultOrigin;
+    from: LaunchDefaultEntry | null;
+    to: LaunchDefaultEntry | null;
+}
+export interface LaunchDefaultsDocument {
+    version: 1;
+    /** Global document token, including clears; distinct from entry revisions. */
+    revision: number;
+    assistant?: LaunchDefaultEntry;
+    coordinator?: LaunchDefaultEntry;
+    history: LaunchDefaultChange[];
+}
+export interface LaunchDefaultRef {
+    role: LaunchDefaultRole;
+    scope: 'global' | 'project';
+    /** Entry revision for global defaults; host project token for project defaults. */
+    revision: number;
+    projectId?: string;
+}
+export type LaunchDefaultField = keyof LaunchDefaultSelection;
+export interface LaunchDefaultAxis {
+    value: string | null;
+    source: LaunchDefaultSource;
+    defaultRef?: LaunchDefaultRef;
+}
+export type LaunchDefaultWarning = 'catalog_unverified' | 'manual_mcp_setup_required';
+export type LaunchDefaultValidationReason =
+    | 'invalid_schema' | 'provider_unknown' | 'provider_not_cli' | 'provider_disabled'
+    | 'provider_not_detected' | 'provider_not_eligible' | 'model_unsupported'
+    | 'model_provider_mismatch' | 'model_not_offered' | 'thinking_unsupported'
+    | 'thinking_not_offered' | 'catalog_unavailable';
+export type LaunchDefaultResolution =
+    | { ok: true; selection: LaunchDefaultSelection; applied: Record<LaunchDefaultField, LaunchDefaultAxis>;
+        defaultRef?: LaunchDefaultRef; documentRevision: number; warnings: LaunchDefaultWarning[];
+        toolRestriction: LaunchDefaultToolRestriction }
+    | { ok: false; code: 'launch_default_required' | 'launch_default_unavailable' | 'launch_selection_invalid';
+        role: LaunchDefaultRole; field: LaunchDefaultField; reason: string; source?: LaunchDefaultSource;
+        value?: string | null; defaultRef?: LaunchDefaultRef; candidates?: readonly string[]; hint: string };
+export interface LaunchDefaultsRoleView {
+    stored: LaunchDefaultEntry | null;
+    /** The existing daemon resolver's result, including loud failures. */
+    effective: LaunchDefaultResolution;
+}
+type Target = { role: 'assistant'; project?: never } | { role: 'coordinator'; project?: string };
+export type LaunchDefaultsReadRequest =
+    | ({ action?: 'get' } & (Target | { role?: never; project?: never }))
+    | ({ action: 'check' } & Target & LaunchDefaultSelection);
+/** Mandatory CAS: global document token, or host project token for project writes.
+ * 0 is explicit first setup; clears advance the token and never restore fallback. */
+export type LaunchDefaultsSetRequest = Target & { expectedRevision: number } & (
+    | ({ action: 'set' } & LaunchDefaultSelection)
+    | { action: 'clear'; provider?: never; model?: never; thinkingLevel?: never }
+);
+/** Existing assistant routing envelope; session identity never supplies origin. */
+export type AssistantLaunchDefaultsReadRequest = LaunchDefaultsReadRequest & { assistantSessionId?: string };
+export type AssistantLaunchDefaultsSetRequest = LaunchDefaultsSetRequest & { assistantSessionId?: string };
+export const LAUNCH_DEFAULT_ERROR_CODES = [
+    'invalid_args', 'launch_default_required', 'launch_default_unavailable', 'launch_selection_invalid',
+    'launch_default_invalid', 'revision_conflict', 'store_unavailable', 'store_busy', 'persistence_failed',
+    'project_not_found', 'project_ambiguous', 'project_not_hosted', 'project_storage_unavailable',
+    'staging_unavailable', 'staging_failed', 'review_turn_tool_denied',
+] as const;
+export type LaunchDefaultsErrorCode = typeof LAUNCH_DEFAULT_ERROR_CODES[number];
+export interface LaunchDefaultsError {
+    success: false;
+    code: LaunchDefaultsErrorCode;
+    error: string;
+    reason?: string;
+    role?: LaunchDefaultRole;
+    field?: LaunchDefaultField;
+    source?: LaunchDefaultSource;
+    value?: string | null;
+    defaultRef?: LaunchDefaultRef;
+    candidates?: readonly string[];
+    actualRevision?: number;
+    /** 0 for an absent global document; absent when it cannot be read. */
+    documentRevision?: number;
+    /** A persistence failure can replace intent without confirming durability.
+     * Re-read before retrying; never report applied on committed:true alone. */
+    committed?: boolean;
+}
+export interface LaunchDefaultsReadSuccess {
+    success: true;
+    result: 'get';
+    documentRevision: number;
+    roles: Partial<Record<LaunchDefaultRole, LaunchDefaultsRoleView>>;
+    project?: { projectId: string; revision: number; entry: LaunchDefaultEntry | null };
+}
+export interface LaunchDefaultsCheckSuccess {
+    success: true;
+    result: 'check';
+    role: LaunchDefaultRole;
+    selection: LaunchDefaultSelection;
+    warnings: LaunchDefaultWarning[];
+    toolRestriction: LaunchDefaultToolRestriction;
+    lowersToolLock: boolean;
+}
+export interface LaunchDefaultsApplied {
+    success: true;
+    result: 'applied';
+    role: LaunchDefaultRole;
+    scope: 'global' | 'project';
+    projectId?: string;
+    entry: LaunchDefaultEntry | null;
+    previous: LaunchDefaultEntry | null;
+    /** CAS token returned by the authority that performed the write. */
+    revision: number;
+    warnings: LaunchDefaultWarning[];
+    durable: true;
+    note: string;
+}
+export interface LaunchDefaultsStaged {
+    success: true;
+    result: 'staged';
+    role: LaunchDefaultRole;
+    stagedId: string;
+    previous: LaunchDefaultEntry | null;
+    selection: LaunchDefaultSelection | null;
+    expectedRevision: number;
+    warnings: LaunchDefaultWarning[];
+    note: string;
+}
+/** Existing owner Inbox adapter stores this proposal; it is not another default.
+ * Applying it must revalidate on the host and CAS via the same set handler. */
+export interface LaunchDefaultsProposal {
+    kind: 'launch_defaults';
+    role: LaunchDefaultRole;
+    project?: string;
+    selection: LaunchDefaultSelection | null;
+    previous: LaunchDefaultEntry | null;
+    expectedRevision: number;
+    origin: LaunchDefaultOrigin;
+    callerSessionId?: string;
+}
+export type LaunchDefaultsReadResponse = LaunchDefaultsReadSuccess | LaunchDefaultsCheckSuccess | LaunchDefaultsError;
+export type LaunchDefaultsSetResponse = LaunchDefaultsApplied | LaunchDefaultsStaged | LaunchDefaultsError;
+export type LaunchDefaultsResponse = LaunchDefaultsReadResponse | LaunchDefaultsSetResponse;

package/src/mesh-tool-names.ts

@@ -44,6 +44,7 @@ export const CANONICAL_MESH_TOOL_NAMES = [
     'mesh_list_pending_approvals',
     'mesh_create',
     'mesh_add_node',
+    'mesh_attach_remote',
     'mesh_clone_node',
     'mesh_remove_node',
     'mesh_cleanup_worktree_nodes',

package/src/mesh-vocabulary.ts

@@ -56,6 +56,14 @@ export type MeshSessionCleanupMode = typeof MESH_SESSION_CLEANUP_MODES[number]
 export const WORKER_REPORT_OUTCOMES = ['completed', 'blocked', 'failed'] as const
 export type WorkerReportOutcome = typeof WORKER_REPORT_OUTCOMES[number]
 
+/**
+ * Hard cap on a `report_completion` summary (characters, after trim). Over-limit
+ * summaries are REJECTED, never truncated. Declared once so the daemon validator
+ * and the mcp-server's pre-send check (which keeps an over-limit report out of the
+ * durable outbox) cannot drift apart.
+ */
+export const WORKER_REPORT_SUMMARY_MAX_CHARS = 8_000
+
 /** Final branch state a worker reports (see coordinator convergence rules). */
 export const WORKER_BRANCH_STATES = [
     'merged_to_main',

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,25 @@ 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
         [extra: string]: unknown
     }
     [extra: string]: unknown
@@ -137,6 +170,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>

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/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,136 @@
+/**
+ * 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')
+        || (kind === 'expired-token' && ['grok-cli', 'kimi', 'antigravity-cli'].includes(quota.provider))
+    // Order matters: the aged-out Claude shape and the retained antigravity
+    // shape both ALSO mark lastGoodWindows (mesh routing trusts retained numbers
+    // until their reset), so they must be classified before the generic branch.
+    if (userMustAct) return hasReading(quota) ? { cue: 'stale', userMustAct: true } : { userMustAct: true }
+    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))
+}