@adhdev/mesh-shared 1.0.82-rc.3 → 1.0.82-rc.31

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,9 @@ 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'
+
+export * from './role-launch';
+export * from './task-source-phase';

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' | 'provider_quota_gated' | '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

@@ -28,6 +28,7 @@ export const CANONICAL_MESH_TOOL_NAMES = [
     'mesh_view_queue',
     'mesh_queue_cancel',
     'mesh_queue_requeue',
+    'mesh_queue_revise',
     'mesh_send_task',
     'mesh_read_chat',
     'mesh_read_debug',
@@ -44,6 +45,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',
@@ -64,6 +66,9 @@ export const CANONICAL_MESH_TOOL_NAMES = [
     'mesh_mission_list',
     'mesh_review_inbox',
     'mesh_node_slots',
+    'driver_list',
+    'driver_describe',
+    'artifact_list',
 ] as const;
 
 export type CanonicalMeshToolName = typeof CANONICAL_MESH_TOOL_NAMES[number];

package/src/mesh-vocabulary.ts

@@ -17,10 +17,12 @@
 
 export { MESH_TASK_DIFFICULTIES, type MeshTaskDifficulty } from './brain-routing'
 
-export const MESH_TASK_STATUSES = ['pending', 'assigned', 'completed', 'failed', 'cancelled'] as const
+/** `blocked` ends a worker attempt pending external follow-up; only completed satisfies dependencies.
+ * Branch convergence (including blocked_review) remains an independent axis. */
+export const MESH_TASK_STATUSES = ['pending', 'assigned', 'completed', 'blocked', 'failed', 'cancelled'] as const
 export type MeshTaskStatus = typeof MESH_TASK_STATUSES[number]
 
-export const MESH_TERMINAL_TASK_STATUSES = ['completed', 'failed', 'cancelled'] as const
+export const MESH_TERMINAL_TASK_STATUSES = ['completed', 'blocked', 'failed', 'cancelled'] as const
 export type MeshTerminalTaskStatus = typeof MESH_TERMINAL_TASK_STATUSES[number]
 
 export const MESH_TASK_MODES = ['code_change', 'validation', 'live_debug_readonly', 'launch_app', 'convergence'] as const
@@ -56,6 +58,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>
@@ -253,7 +288,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

@@ -321,3 +321,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

@@ -73,6 +73,9 @@ export type DaemonStatusEventWirePayload = {
     elapsedSec?: number
     modalMessage?: string
     modalButtons?: string[]
+    modalKey?: string
+    approvalEvidence?: 'live' | 'cached' | 'unavailable'
+    waitKind?: 'external'
     surfaceHidden?: boolean
     muted?: boolean
 }
@@ -260,8 +263,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 }
+export type P2PIceWirePayload = { candidate: string; mid: string; peerId: string; attemptId?: number; attemptEpoch?: string }
 
 /**
  * A dashboard-originated signal as relayed to the daemon. `peerId` is stamped
@@ -273,6 +276,8 @@ export type P2PIceWirePayload = { candidate: string; mid: string; peerId: string
 export type RelayedP2PSignalWirePayload = {
     peerId?: string
     daemonId?: string
+    attemptId?: number
+    attemptEpoch?: string
     sharePermission?: string
     shareTargetSessionId?: string
     sdp?: string

package/src/protocol/dashboard-server.ts

@@ -152,6 +152,8 @@ export type SystemAnnouncementWirePayload = {
 export type DashboardP2POfferWirePayload = {
     daemonId: string
     peerId?: string
+    attemptId?: number
+    attemptEpoch?: string
     sdp: string
     type: string
 }
@@ -159,6 +161,8 @@ export type DashboardP2POfferWirePayload = {
 export type DashboardP2PIceWirePayload = {
     daemonId: string
     peerId?: string
+    attemptId?: number
+    attemptEpoch?: string
     candidate: string
     mid?: string
     sdpMid?: string | null
@@ -234,11 +238,13 @@ 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 }
+export type DashboardP2PReadyWirePayload = { daemonId: string; peerId: string; attemptId?: number; attemptEpoch?: string }
+export type DashboardP2PAnswerWirePayload = { daemonId: string; peerId: string; sdp: string; type: string; attemptId?: number; attemptEpoch?: string }
 export type DashboardP2PLocalIceWirePayload = {
     daemonId: string
     peerId: string
+    attemptId?: number
+    attemptEpoch?: string
     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));
+}