@adhdev/daemon-core 0.9.82-rc.40 → 0.9.82-rc.401

package/dist/mesh/mesh-runtime-store.d.ts

@@ -0,0 +1,447 @@
+import type { MeshTaskStatus, MeshWorkQueueEntry } from './mesh-work-queue.js';
+export declare class MeshRuntimeStore {
+    private static instance;
+    private readonly db;
+    private readonly dbPath;
+    private readonly migratedMeshIds;
+    private fingerprintSweepCounter;
+    private walWriteCounter;
+    private toolCallLogCounter;
+    private static readonly WAL_CHECK_INTERVAL;
+    private static readonly WAL_MAX_BYTES;
+    private constructor();
+    private static loggedGetInstanceFailure;
+    static getInstance(): MeshRuntimeStore;
+    static resetForTests(): void;
+    close(): void;
+    transaction<T>(fn: () => T): T;
+    private migrate;
+    private tableColumns;
+    /**
+     * MESH-ISOLATION-LEAK migration. Two tables historically lacked a `mesh_id` column,
+     * letting one machine that belongs to multiple meshes (multiple repos) leak rows
+     * across meshes. Both migrations are idempotent and run on every boot — the column
+     * check short-circuits once the new schema is in place.
+     */
+    private migrateMeshIsolationColumns;
+    hasCompletionFingerprint(meshId: string, fingerprint: string): boolean;
+    recordCompletionFingerprint(meshId: string, fingerprint: string, ttlMs: number): void;
+    sweepExpiredFingerprints(): void;
+    private maybeCheckpointWal;
+    private ensureLegacyQueueMigrated;
+    getQueueEntries(meshId: string, statuses?: MeshTaskStatus[]): MeshWorkQueueEntry[];
+    getQueueRevision(meshId: string): string;
+    replaceQueue(meshId: string, queue: MeshWorkQueueEntry[]): void;
+    deleteQueue(meshId: string): void;
+    insertQueueEntry(entry: MeshWorkQueueEntry): void;
+    updateQueueEntry(entry: MeshWorkQueueEntry): void;
+    findQueueEntryById(meshId: string, id: string): MeshWorkQueueEntry | null;
+    hasActiveAssignment(meshId: string, sessionId: string, nodeId: string): boolean;
+    /** A session may only execute one task at a time, regardless of task mode. */
+    private hasActiveSessionAssignment;
+    /** A node may only execute one write task at a time (worktree isolation). */
+    private hasActiveNodeAssignment;
+    /**
+     * Count active (status='assigned') tasks on a node, regardless of provider or
+     * task mode. This is the load metric for least-loaded / round-robin ranking:
+     * the scheduler prefers the node with the fewest active assignments so
+     * untargeted work spreads instead of piling onto whichever node asks first.
+     */
+    nodeActiveAssignmentCount(meshId: string, nodeId: string): number;
+    /**
+     * O(1) count of queue tasks in 'pending' status for a mesh. A COUNT(*) over the
+     * indexed status column, so it avoids JSON.parse-ing every queue row — used as a
+     * cheap guard before the reconcile loop runs a full triggerMeshQueue scan.
+     */
+    pendingQueueTaskCount(meshId: string): number;
+    /**
+     * Read the current per-mesh round-robin cursor (0 when unset). Used to rotate
+     * the tie-break winner among nodes tied at the least load.
+     */
+    getSchedulerCursor(meshId: string): number;
+    /**
+     * Atomically advance the per-mesh round-robin cursor by one and return the
+     * value that was current BEFORE the bump (the value the caller should rotate
+     * by for this pass). UPSERT keeps it lock-free across concurrent passes.
+     */
+    bumpSchedulerCursor(meshId: string): number;
+    /**
+     * Count active (status='assigned') tasks on a (node, provider) combination,
+     * matched by the assignedProviderType stamped on the payload at claim time.
+     * Drives the per-(node, provider) maxParallel cap (RepoMeshNodePolicy
+     * providerRoles). The active-assignment set for a single node is tiny, so
+     * parsing payloads here is cheap and avoids a schema migration. Pre-cap legacy
+     * rows (no provider stamp) and other providers on the same node do not consume
+     * this provider's budget, so the cap is fully backward compatible.
+     */
+    private activeProviderAssignmentCount;
+    claimNextQueueTask(meshId: string, nodeId: string, sessionId: string, capabilityTags?: string[], opts?: {
+        providerType?: string;
+        providerMaxParallel?: number;
+        nodeIsWorktree?: boolean;
+    }): MeshWorkQueueEntry | null;
+    getQueueStatsByStatus(meshId: string): {
+        status: string;
+        count: number;
+    }[];
+    getActiveAssignmentDetails(meshId: string): Array<{
+        id: string;
+        nodeId?: string;
+        sessionId?: string;
+        message: string;
+    }>;
+    /**
+     * Resolve the `assigned` queue row a completion event belongs to.
+     *
+     * Clock-skew safety (C2): a completion event's `occurredAtIso` carries the
+     * REMOTE WORKER's clock, while `updated_at` carries the COORDINATOR's clock
+     * (set at assignment and re-bumped on every mutation). For a remote node,
+     * coordinator-clock > worker-clock skew used to make an `updated_at <= occurredAt`
+     * filter return nothing, stranding the finished task as `assigned` forever.
+     *
+     * We therefore NEVER filter completion-matching on the mutable `updated_at`:
+     *  1. If `taskId` is given, match the exact `assigned` row by id (no time filter).
+     *  2. Otherwise a session holds at most one `assigned` task — match it without a
+     *     time filter. If several exist (shouldn't normally), disambiguate by the
+     *     IMMUTABLE `dispatchTimestamp`: latest `dispatchTimestamp <= occurredAt`,
+     *     and if skew makes ALL of them later than `occurredAt`, fall back to the
+     *     most-recent `dispatchTimestamp` rather than returning null.
+     */
+    findAssignedBySession(meshId: string, sessionId: string, occurredAtIso?: string, taskId?: string): MeshWorkQueueEntry | null;
+    private toRow;
+    insertDirectDispatch(entry: {
+        taskId: string;
+        meshId: string;
+        nodeId?: string;
+        sessionId?: string;
+        providerType?: string;
+        message: string;
+        taskMode?: string;
+        via: string;
+        dispatchedToIdleSession?: boolean;
+        dispatchedAt: string;
+    }): void;
+    getActiveDirectDispatches(meshId: string): Array<{
+        taskId: string;
+        meshId: string;
+        nodeId: string | null;
+        sessionId: string | null;
+        providerType: string | null;
+        message: string;
+        taskMode: string | null;
+        via: string;
+        status: string;
+        dispatchedToIdleSession: boolean;
+        dispatchedAt: string;
+        updatedAt: string;
+    }>;
+    updateDirectDispatchStatus(meshId: string, sessionId: string, status: 'acked' | 'completed' | 'failed' | 'stale', taskId?: string): void;
+    /**
+     * MESH-DISPATCH-MISROUTE (fix 3, consumer residual): resolve the task_id of the SINGLE
+     * non-terminal direct dispatch a session owns. Returns the task_id only when the session
+     * holds exactly ONE active ('dispatched'/'acked') row — the case where a taskId-less
+     * lifecycle event (a legacy/relayed worker whose producer never stamped meshActiveTaskId)
+     * unambiguously belongs to that one dispatch. With zero rows there is nothing to ack; with
+     * two or more (a re-dispatch/nudge sibling) the firing event's owner is ambiguous, so we
+     * return null and the caller MUST NOT fall back to the session_id sweep that would flip a
+     * sibling row ("may flip a sibling dispatch row"). This narrows the legacy fallback to the
+     * only safe case instead of removing the producer-side TASKIDLESS stamp's safety net.
+     */
+    getSoleActiveDirectDispatchTaskId(meshId: string, sessionId: string): string | null;
+    cleanupTerminalDirectDispatches(olderThanMs: number): void;
+    deleteDirectDispatches(meshId: string): void;
+    /**
+     * Delete specific direct dispatch rows by taskId for a mesh. Used by the staleDirect prune
+     * path to remove orphaned/terminal dispatch records whose node/session is no longer in the
+     * live mesh. Returns the number of rows actually deleted. No-op for an empty taskId list.
+     */
+    deleteDirectDispatchesByTaskId(meshId: string, taskIds: string[]): number;
+    markStaleDirectDispatches(meshId: string, olderThanMs: number): void;
+    setRemoteIdleSession(meshId: string, nodeId: string, sessionId: string, providerType: string, expiresAt: number, metadata?: any): void;
+    getRemoteIdleSessions(meshId: string): Array<{
+        nodeId: string;
+        sessionId: string;
+        providerType: string;
+        expiresAt: number;
+        metadata?: any;
+    }>;
+    deleteRemoteIdleSession(meshId: string, nodeId: string, sessionId: string): void;
+    pruneExpiredRemoteIdleSessions(): void;
+    insertSessionDelivery(entry: {
+        id: string;
+        meshId: string;
+        nodeId?: string;
+        sessionId?: string;
+        providerType?: string;
+        taskId?: string;
+        kind: string;
+        priority?: number;
+        message: string;
+        status: string;
+        deliverAfter?: string;
+        expiresAt?: string;
+        sourceCoordinatorSessionId?: string;
+        sourceCoordinatorDaemonId?: string;
+        createdAt: string;
+        updatedAt: string;
+    }): void;
+    updateSessionDeliveryStatus(id: string, status: string, opts?: {
+        lastError?: string;
+        incrementAttempt?: boolean;
+    }): void;
+    getActiveSessionDeliveries(meshId: string, sessionId?: string): Array<{
+        id: string;
+        meshId: string;
+        nodeId: string | null;
+        sessionId: string | null;
+        providerType: string | null;
+        taskId: string | null;
+        kind: string;
+        priority: number;
+        message: string;
+        status: string;
+        deliverAfter: string | null;
+        expiresAt: string | null;
+        attemptCount: number;
+        sourceCoordinatorSessionId: string | null;
+        sourceCoordinatorDaemonId: string | null;
+        lastError: string | null;
+        createdAt: string;
+        updatedAt: string;
+    }>;
+    /**
+     * Bug B watchdog support: true when at least one delivery record for the task has
+     * reached a confirmed-handed-off status (delivered / acked / completed). The
+     * assigned-stranded watchdog uses this to distinguish a dispatch that was never
+     * confirmed (reclaimable) from one that WAS handed to the worker (a genuinely
+     * in-flight or completion-lost task, which is PHASE 4's responsibility, not this
+     * watchdog's). Indexed by (mesh_id, task_id).
+     */
+    taskHasConfirmedDelivery(meshId: string, taskId: string): boolean;
+    expireStaleSessionDeliveries(meshId: string): void;
+    deleteSessionDeliveries(meshId: string): void;
+    recordCompletionConflict(entry: {
+        id: string;
+        meshId: string;
+        fingerprint: string;
+        conflictingTaskId?: string;
+        conflictingSessionId?: string;
+        originalTaskId?: string;
+        originalSessionId?: string;
+        event: string;
+        createdAt: string;
+    }): void;
+    getRecentCompletionConflicts(meshId: string, limitMs?: number): Array<{
+        id: string;
+        meshId: string;
+        fingerprint: string;
+        conflictingTaskId: string | null;
+        conflictingSessionId: string | null;
+        originalTaskId: string | null;
+        originalSessionId: string | null;
+        event: string;
+        createdAt: string;
+    }>;
+    /**
+     * Record a mesh tool call and check whether this mesh+tool combination is
+     * being called too rapidly (sliding window rate guard).
+     *
+     * Returns a rate-limit advisory string when the call rate is too high, null otherwise.
+     * windowMs: sliding window size in ms (default 10s)
+     * maxCalls: max allowed calls within the window (default 5)
+     */
+    recordMeshToolCall(opts: {
+        meshId: string;
+        tool: string;
+        sessionId?: string | null;
+        windowMs?: number;
+        maxCalls?: number;
+    }): {
+        rateLimitExceeded: boolean;
+        callsInWindow: number;
+        advisory: string | null;
+    };
+    /**
+     * Prune tool call log entries older than the given age in ms.
+     * Exposed for testing.
+     */
+    pruneToolCallLog(olderThanMs: number): void;
+    appendLedgerEntry(entry: {
+        id: string;
+        meshId: string;
+        timestamp: string;
+        kind: string;
+        nodeId?: string | null;
+        sessionId?: string | null;
+        providerType?: string | null;
+        payload?: unknown;
+    }): void;
+    readLedgerEntries(meshId: string, opts?: {
+        tail?: number;
+        since?: string;
+        kind?: string;
+        limit?: number;
+    }): Array<{
+        id: string;
+        meshId: string;
+        timestamp: string;
+        kind: string;
+        nodeId: string | null;
+        sessionId: string | null;
+        providerType: string | null;
+        payload: unknown;
+    }>;
+    /**
+     * G2 read cutover: read ledger entries in append order (oldest first),
+     * matching legacy JSONL file-order semantics. Ties on the same timestamp
+     * are broken by rowid (insertion order), preserving the positional
+     * guarantee that mesh-events relies on for same-millisecond entries.
+     */
+    readLedgerEntriesOrdered(meshId: string, opts?: {
+        since?: string;
+        kinds?: string[];
+        tail?: number;
+    }): Array<{
+        id: string;
+        meshId: string;
+        timestamp: string;
+        kind: string;
+        nodeId: string | null;
+        sessionId: string | null;
+        providerType: string | null;
+        payload: unknown;
+    }>;
+    /** Remove all ledger entries for a mesh (mesh deletion / test cleanup). */
+    clearLedgerForMesh(meshId: string): number;
+    /** G2: remove entries moved to the JSONL archive so the SQLite runtime set mirrors the active ledger. */
+    deleteLedgerEntries(meshId: string, ids: string[]): number;
+    hasLedgerEntry(meshId: string, id: string): boolean;
+    ledgerEntryCount(meshId: string): number;
+    importLedgerEntries(entries: Array<{
+        id: string;
+        meshId: string;
+        timestamp: string;
+        kind: string;
+        nodeId?: string | null;
+        sessionId?: string | null;
+        providerType?: string | null;
+        payload?: unknown;
+    }>): number;
+    /**
+     * G4: Read a bounded, cursor-addressable ledger slice directly from the SQLite
+     * mesh_event_ledger table. This is the P2P reconcile read path; JSONL files are
+     * retained as export/import/debug/legacy artifacts only.
+     *
+     * The return shape is structurally compatible with MeshLedgerSlice so callers
+     * in mesh-tools.ts can pass it directly to buildMeshLedgerReplicaEvidence.
+     */
+    readLedgerSlice(meshId: string, opts?: {
+        afterId?: string;
+        since?: string;
+        kind?: string;
+        limit?: number;
+    }): {
+        protocol: 'adhdev.mesh.ledger.slice.v1';
+        meshId: string;
+        entries: Array<{
+            id: string;
+            meshId: string;
+            timestamp: string;
+            kind: string;
+            nodeId: string | null;
+            sessionId: string | null;
+            providerType: string | null;
+            payload: unknown;
+        }>;
+        cursor: {
+            afterId: string | null;
+            nextAfterId: string | null;
+            limit: number;
+            hasMore: boolean;
+        };
+        sourceOfTruth: {
+            kind: 'local_sqlite';
+            table: 'mesh_event_ledger';
+            bounded: true;
+            maxLimit: number;
+        };
+    };
+    insertPendingEvent(event: {
+        id: string;
+        meshId: string;
+        coordinatorDaemonId?: string | null;
+        event: string;
+        payload?: unknown;
+        fingerprint?: string | null;
+        queuedAt: number;
+    }): boolean;
+    /**
+     * Drain undrained pending events for a mesh, atomically marking them drained.
+     * When `opts.onlyEvents` is supplied, ONLY rows whose `event` is in that set are
+     * drained — the rest stay queued (drained=0) for a later drain. This is how the
+     * reconcile loop force-drains terminal/force-inject events into a *generating*
+     * coordinator while leaving non-force progress events for the coordinator's next
+     * idle transition. Filtering happens inside the same transaction as the
+     * drained=1 marking, so force-drain + a concurrent full drain can never both
+     * consume the same row.
+     */
+    drainPendingEvents(meshId: string, coordinatorDaemonId?: string | null | ReadonlyArray<string>, opts?: {
+        onlyEvents?: ReadonlySet<string>;
+    }): Array<{
+        id: string;
+        event: string;
+        payload: unknown;
+    }>;
+    /** Non-destructive peek — returns undrained events without marking them drained. */
+    peekPendingEvents(meshId: string, coordinatorDaemonId?: string | null | ReadonlyArray<string>): Array<{
+        id: string;
+        event: string;
+        payload: unknown;
+    }>;
+    hasPendingEventFingerprint(meshId: string, fingerprint: string): boolean;
+    upsertMission(mission: {
+        id: string;
+        meshId: string;
+        title: string;
+        goal?: string;
+        status?: string;
+    }): void;
+    getMission(meshId: string, missionId: string): {
+        id: string;
+        meshId: string;
+        title: string;
+        goal: string;
+        status: string;
+        createdAt: string;
+        updatedAt: string;
+    } | null;
+    getMissions(meshId: string, statuses?: string[]): Array<{
+        id: string;
+        meshId: string;
+        title: string;
+        goal: string;
+        status: string;
+        createdAt: string;
+        updatedAt: string;
+    }>;
+    /** Remove all missions for a mesh — mesh deletion / test cleanup. */
+    clearMissionsForMesh(meshId: string): number;
+    /** Remove all pending-event rows (drained included) for a mesh — mesh deletion / test cleanup. */
+    clearPendingEventsForMesh(meshId: string): number;
+    pendingEventCount(meshId: string): number;
+    /**
+     * Mark specific pending-event rows drained by id (ack). Used by the
+     * unresolved-delegate durable-forward outbox: an event is peeked (not drained)
+     * while its push to the coordinator is unconfirmed, then marked drained ONLY
+     * after the push is acked. A failed push leaves the row undrained so the next
+     * reconcile tick retries it. Returns the number of rows newly marked drained.
+     */
+    markPendingEventsDrainedById(ids: ReadonlyArray<string>): number;
+    /**
+     * Hard-delete pending-event rows by id (including the dedup fingerprint history).
+     * Used to expire an unresolved-delegate outbox entry that has exhausted its retry
+     * budget — fully removing it frees the fingerprint so a genuinely new completion
+     * for the same task could be re-queued later. Returns the number of rows deleted.
+     */
+    deletePendingEventsById(ids: ReadonlyArray<string>): number;
+}

package/dist/mesh/mesh-scheduling-runtime.d.ts

@@ -0,0 +1,78 @@
+import type { RepoMeshNodePolicy, RepoMeshSchedulingStrategy } from '../repo-mesh-types.js';
+import type { MeshWorkQueueEntry } from './mesh-work-queue.js';
+/** Per-(node, provider) cap and its current consumption. */
+export interface MeshNodeProviderSchedulingRuntime {
+    providerType: string;
+    /** Declared maxParallel cap for this (node, provider). Omitted when uncapped. */
+    maxParallel?: number;
+    /** Active (status='assigned') tasks on this node claimed by this provider. */
+    activeAssigned: number;
+    /** True when activeAssigned has reached maxParallel (a further claim is refused). */
+    capReached: boolean;
+}
+/** Per-node scheduling-runtime projection. */
+export interface MeshNodeSchedulingRuntime {
+    nodeId: string;
+    /** Active (status='assigned') task count on this node — the least-loaded rank key. */
+    load: number;
+    /** Soft scheduling priority (PRIORITY rank key; higher = preferred). */
+    schedulingPriority: number;
+    /** Per-node concurrent-session cap, when configured. */
+    maxConcurrentSessions?: number;
+    /** Per-(node, provider) caps + consumption, when providerRoles declares any. */
+    providerRoles?: MeshNodeProviderSchedulingRuntime[];
+    /**
+     * True when the node currently cannot claim a NEW write (non-readonly) task —
+     * either the global write cap is exhausted or a node-local gate (active write
+     * assignment / a fully-consumed provider cap / session cap) blocks it.
+     */
+    capReached: boolean;
+    /** Structured reasons backing capReached (empty when the node can take work). */
+    capReasons: string[];
+}
+/** Mesh-level scheduling-runtime projection. */
+export interface MeshSchedulingRuntime {
+    /** Resolved tie-break strategy (defaults to 'first_eligible'). */
+    strategy: RepoMeshSchedulingStrategy;
+    /** Effective global write-task parallel cap (clamped). */
+    maxParallelTasks: number;
+    /** Derived read-only diagnosis cap (max(2, 2× write cap)) — mirrors the claim path. */
+    maxReadonlyParallelTasks: number;
+    /** Current global write (non-readonly) assigned-task load. */
+    activeWriteAssigned: number;
+    /** Current global read-only assigned-task load. */
+    activeReadonlyAssigned: number;
+    /** True when the global write cap is exhausted (no new write task can launch). */
+    globalWriteCapReached: boolean;
+    /** True when the read-only diagnosis cap is exhausted. */
+    globalReadonlyCapReached: boolean;
+    /** Per-node projections, in mesh config order. */
+    nodes: MeshNodeSchedulingRuntime[];
+}
+interface MeshLike {
+    policy?: {
+        schedulingStrategy?: unknown;
+        maxParallelTasks?: unknown;
+    } | null;
+    nodes?: Array<{
+        id?: string;
+        nodeId?: string;
+        node_id?: string;
+        policy?: RepoMeshNodePolicy | null;
+        isLocalWorktree?: boolean;
+    }> | null;
+}
+/**
+ * Build the scheduling-runtime projection for a mesh from its config + a snapshot of
+ * its work queue. Pure and side-effect free — safe to call on any read path.
+ *
+ * The derivation deliberately mirrors maybeAutoLaunchOneQueueSession's gates so the
+ * exposed "capReached/capReasons" match why a real claim would be refused:
+ *   • global write cap   → activeWriteAssigned >= maxParallelTasks
+ *   • node write conflict→ a node already holding an assigned write task (worktree isolation)
+ *   • provider cap       → a (node, provider) at its declared maxParallel
+ * It does NOT re-evaluate eligibility/required-tags (those are task-specific); it only
+ * reports the capacity picture, which is what an operator needs to read load balance.
+ */
+export declare function buildMeshSchedulingRuntime(mesh: MeshLike | null | undefined, queue: MeshWorkQueueEntry[]): MeshSchedulingRuntime;
+export {};

package/dist/mesh/mesh-task-stats.d.ts

@@ -0,0 +1,49 @@
+/**
+ * M7: Operational stats (time/attempts) derived from existing truth.
+ *
+ * No cost/token accounting — ADHDev observes PTY/CDP and cannot see API
+ * tokens (explicit non-goal). Everything here is derived at query time from
+ * the SQLite ledger and queue rows; there is no separate aggregate table.
+ * Tasks with missing ledger evidence report incompleteEvidence instead of
+ * estimated numbers.
+ */
+export interface MeshTaskStats {
+    taskId: string;
+    status: string;
+    dispatchedAt: string | null;
+    terminalAt: string | null;
+    terminalKind: 'task_completed' | 'task_failed' | null;
+    /** dispatched → terminal wall clock; null when evidence is incomplete. */
+    durationMs: number | null;
+    /** Number of task_dispatched ledger entries observed for this task. */
+    dispatchCount: number;
+    /** Queue requeueCount (0 when the row is gone or never requeued). */
+    requeueCount: number;
+    /** True when dispatch or terminal ledger evidence is missing — numbers are withheld, never estimated. */
+    incompleteEvidence?: true;
+}
+export interface MeshMissionStats {
+    missionId: string;
+    taskCount: number;
+    completed: number;
+    failed: number;
+    /** Sum of per-task durations with complete evidence. */
+    totalDurationMs: number;
+    /** First dispatch → last terminal across the mission's tasks; null without complete endpoints. */
+    wallClockMs: number | null;
+    /** Total requeue attempts across the mission's tasks. */
+    retries: number;
+    /** Task ids whose ledger evidence was incomplete (excluded from sums). */
+    incompleteTaskIds: string[];
+}
+/**
+ * Compute per-task stats from ledger entries. Scans a bounded tail window —
+ * stats are an operational view of recent work, not a full historical report.
+ */
+export declare function computeMeshTaskStats(meshId: string, opts?: {
+    taskIds?: string[];
+    missionId?: string;
+    tail?: number;
+}): MeshTaskStats[];
+/** Mission rollup — derived from per-task stats, no stored aggregates. */
+export declare function computeMeshMissionStats(meshId: string, missionId: string): MeshMissionStats;

package/dist/mesh/mesh-unresolved-forward-outbox.d.ts

@@ -0,0 +1,30 @@
+export declare const UNRESOLVED_FORWARD_OUTBOX_MESH_ID = "__unresolved_forward_outbox__";
+export interface UnresolvedForwardEntry {
+    /** Row id in mesh_pending_events; pass back to ack/expire after a push attempt. */
+    id: string;
+    /** The coordinator daemon to push this event to (mesh_forward_event target). */
+    coordinatorDaemonId: string;
+    /** The flat payload to forward (already shaped for handleMeshForwardEvent). */
+    payload: Record<string, unknown>;
+    /** When the entry was first enqueued (epoch ms) — used for age-based expiry. */
+    queuedAt: number;
+}
+/**
+ * Durably enqueue an unresolved-delegate forward for a coordinator daemon. The
+ * `forwardPayload` is the flat shape handleMeshForwardEvent reads on the coordinator.
+ * Idempotent on the event fingerprint. Returns true when a new row was written (or a
+ * duplicate was harmlessly ignored), false on a hard persistence failure.
+ */
+export declare function enqueueUnresolvedDelegateForward(coordinatorDaemonId: string, eventName: string, forwardPayload: Record<string, unknown>): boolean;
+/** Peek (non-destructive) every undrained outbox entry across all coordinators. */
+export declare function peekUnresolvedDelegateForwards(): UnresolvedForwardEntry[];
+/** Mark an outbox entry delivered (acked) after a successful push. */
+export declare function ackUnresolvedDelegateForward(id: string): void;
+/**
+ * Drop outbox entries that have exceeded the max retry age. Returns the count
+ * expired so the caller can log a fail-loud trace (a dropped completion is a real
+ * loss; it must be visible, not silent).
+ */
+export declare function expireStaleUnresolvedDelegateForwards(nowMs?: number): number;
+/** Test helper: purge the entire outbox. */
+export declare function __clearUnresolvedDelegateForwardOutboxForTests(): void;

package/dist/mesh/mesh-warmup-deadline.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Await `work` under a warmup-aware deadline so a cold-open DataChannel handshake
+ * is NOT charged against the command response budget — the root cause of the
+ * "first mesh dispatch to a cold peer false-times-out, the warm retry succeeds"
+ * signature. Two budgets, switched by the live peer connection state:
+ *
+ *  - While `isConnected()` returns false the peer's channel is still opening; the
+ *    cold-open `connectTimeoutMs` budget applies. This phase is deliberately
+ *    generous because a TURN-relayed cross-machine handshake legitimately needs
+ *    many seconds — but a genuine connect *failure* is surfaced by `work`
+ *    rejecting on its own (the mesh manager fails the peer the instant its
+ *    PeerConnection state goes terminal), so a real failure is never masked for
+ *    the whole window.
+ *  - The first time `isConnected()` returns true the channel is warm; from that
+ *    instant the tight `responseTimeoutMs` governs how long the handler may take.
+ *    Warm-channel callers therefore see behavior identical to the old single
+ *    `Promise.race(work, responseTimeoutMs)`.
+ *
+ * Rejects with `Error('timeout')` when either budget is exhausted, mirroring the
+ * previous single-race contract. When no connection getter is wired callers must
+ * NOT pass `() => true` ("always warm") — that re-introduces the cold-open
+ * false-timeout. Use {@link resolveWarmupDeadlineOpts} which degrades conservatively.
+ */
+export declare function awaitWithWarmupDeadline<T>(work: Promise<T>, opts: {
+    isConnected: () => boolean;
+    connectTimeoutMs: number;
+    responseTimeoutMs: number;
+    pollIntervalMs?: number;
+}): Promise<T>;
+/** Minimal connection-state reader: a mesh peer snapshot stamps its live state on `.state`. */
+export declare function readWarmupConnectionState(connection: Record<string, unknown> | null | undefined): string | undefined;
+export interface ResolvedWarmupDeadlineOpts {
+    isConnected: () => boolean;
+    connectTimeoutMs: number;
+    responseTimeoutMs: number;
+}
+/**
+ * Build {@link awaitWithWarmupDeadline} opts from an OPTIONAL live peer-connection
+ * probe, handling the missing-getter case fail-loud instead of silently degrading.
+ *
+ * When `getConnection` is wired the normal cold-open/warm split applies: the probe
+ * is consulted live and the channel is "warm" only once it reports `connected`.
+ *
+ * When `getConnection` is ABSENT the old call sites fell back to `() => true`
+ * ("always warm"), which charges a still-opening cold channel against the response
+ * budget and silently re-introduces the exact cold-open false-timeout the warmup
+ * deadline exists to prevent. Instead we degrade CONSERVATIVELY and FAIL LOUD:
+ *   - `onMissingGetter` is invoked so the caller can warn (the degrade is visible,
+ *     never silent) — keyed/throttled by the caller as it sees fit.
+ *   - the channel is treated as NOT observably warm (`isConnected: () => false`),
+ *     so the response deadline never arms early on an unobservable channel.
+ *   - the cold peer is granted the COMBINED connect+response window as one deadline,
+ *     so a slow-but-live cold open is never false-timed at the shorter response
+ *     budget. A genuinely hung dispatch still rejects when the combined window
+ *     lapses, and `work` rejecting on its own (a real transport failure) still
+ *     settles immediately.
+ *
+ * Note: a present getter that returns a non-`connected` snapshot (or `null` for an
+ * unknown peer) correctly yields `isConnected() === false` — i.e. the generous
+ * connect budget, never "always warm". Only a wholly absent getter degrades.
+ */
+export declare function resolveWarmupDeadlineOpts(opts: {
+    getConnection?: ((daemonId: string) => Record<string, unknown> | null) | undefined;
+    daemonId: string;
+    connectTimeoutMs: number;
+    responseTimeoutMs: number;
+    onMissingGetter?: (daemonId: string) => void;
+}): ResolvedWarmupDeadlineOpts;