@adhdev/daemon-core 0.9.82-rc.44 → 0.9.82-rc.441

package/dist/mesh/mesh-routing.d.ts

@@ -0,0 +1,70 @@
+import type { DaemonComponents } from '../boot/daemon-lifecycle.js';
+export type WorkerDelegateRejectionReason = 'not_cli' | 'no_workspace' | 'no_worker_envelope' | 'coordinator_not_dispatch_target' | 'mesh_unresolved';
+export interface WorkerDelegateRouting {
+    /** True when the source session is a mesh worker whose events must route to a coordinator. */
+    isDelegate: boolean;
+    /** Resolved mesh id (runtime stamp, direct-dispatch recovery, or workspace lookup). */
+    meshId: string;
+    /** Resolved node id within the mesh, or '' when it cannot be determined. */
+    nodeId: string;
+    /** Human-readable node label for the coordinator system message. */
+    nodeLabel: string;
+    /** Coordinator daemon anchor (prefixed id) when the worker carries one; '' otherwise. */
+    coordinatorDaemonId: string;
+    /** Source session workspace (best-effort; '' when the session/workspace is missing). */
+    workspace: string;
+    /** Source session id echoed back, so diagnostics can name the dropped event's origin. */
+    sessionId: string;
+    /** Why routing was rejected (isDelegate=false), for fail-loud diagnostics (R4). */
+    rejectionReason?: WorkerDelegateRejectionReason;
+}
+interface ResolveDeps {
+    /** Resolve a mesh by id (local config + inline cache). */
+    getMeshById: (meshId: string) => any | undefined;
+    /** Resolve a mesh by workspace path (cached repo lookup). */
+    getMeshByWorkspace: (workspace: string) => any | undefined;
+}
+/**
+ * Resolve how a source CLI session's mesh events should route to a coordinator.
+ *
+ * This is the single authoritative interpretation of the worker envelope. It folds
+ * together every signal that previously lived in inline branches:
+ *  - runtime stamps (meshNodeFor / meshNodeId)
+ *  - the coordinator anchor (meshCoordinatorDaemonId) and launch marker (launchedByCoordinator,
+ *    meshCoordinatorNodeId) — any one proves delegation even if the node/mesh stamp was dropped
+ *  - direct-dispatch recovery: a coordinator session that is itself a dispatch target
+ *  - workspace→mesh fallback when no runtime mesh id survived
+ *
+ * Returns isDelegate=false (with a rejectionReason) instead of throwing, so the caller
+ * can either ignore non-delegate events or surface a diagnostic.
+ */
+export declare function resolveWorkerDelegateRouting(components: DaemonComponents, instanceId: string, deps: ResolveDeps): WorkerDelegateRouting;
+/** Ledger stream that collects delivery_unroutable diagnostics (no real mesh id exists for them). */
+export declare const UNROUTABLE_DIAGNOSTIC_STREAM = "__unroutable__";
+export declare function __resetUnroutableDiagnosticsForTests(): void;
+/** True only for rejections that represent a silently-dropped delegate event worth a diagnostic. */
+export declare function isUnroutableDelegateRejection(routing: WorkerDelegateRouting): boolean;
+/**
+ * R4: record that a worker event with a valid envelope could not be routed to a coordinator.
+ * Writes a `delivery_unroutable` ledger entry (deduped within a short window) so operators see
+ * WHY a completion never arrived instead of it vanishing. No-op for non-diagnostic rejections.
+ */
+export declare function recordUnroutableDelegateEvent(routing: WorkerDelegateRouting, eventName: string): boolean;
+export interface UnroutableDeliveryDiagnostic {
+    timestamp: string;
+    event: string;
+    sessionId?: string;
+    workspace?: string;
+    coordinatorDaemonId?: string;
+}
+/**
+ * R4 visibility: recent delivery_unroutable diagnostics, newest first. Surfaced in mesh_status
+ * so an operator/coordinator can see that completions were dropped (envelope present, mesh
+ * unresolved) rather than the drops being invisible in a ledger nobody reads. The diagnostics
+ * live in a single shared stream because an unroutable event has no resolvable mesh.
+ */
+export declare function getRecentUnroutableDeliveries(opts?: {
+    sinceMs?: number;
+    limit?: number;
+}): UnroutableDeliveryDiagnostic[];
+export {};

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

@@ -0,0 +1,450 @@
+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;
+        source?: string;
+    }): void;
+    getMission(meshId: string, missionId: string): {
+        id: string;
+        meshId: string;
+        title: string;
+        goal: string;
+        status: string;
+        source?: string;
+        createdAt: string;
+        updatedAt: string;
+    } | null;
+    getMissions(meshId: string, statuses?: string[]): Array<{
+        id: string;
+        meshId: string;
+        title: string;
+        goal: string;
+        status: string;
+        source?: 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-inflight.d.ts

@@ -0,0 +1,46 @@
+/**
+ * CANON-IDENTITY single-flight dispatch guard.
+ *
+ * A queue task is double-dispatched into two worker sessions when a SECOND dispatch
+ * path opens after the first has already claimed + dispatched the task. The two
+ * observed paths:
+ *   - the idle-claim drain / auto-launch both funnel through tryAssignQueueTask,
+ *     which is serialized by the atomic claim transaction (claimNextQueueTask) — so
+ *     two concurrent claims can never both win; and
+ *   - the operator requeue tool (mesh_queue_requeue → requeueTask), which flips an
+ *     already-`assigned` row back to `pending` REGARDLESS of whether the worker
+ *     holding it is still generating. A requeue issued while the worker is mid-turn
+ *     re-opens the task for a SECOND session to claim — the live `ade8586d` race.
+ *
+ * The atomic claim already discriminates pending-vs-assigned, but it cannot tell a
+ * GENUINELY-in-flight assigned row (dispatched, worker generating) from a STALE
+ * assigned row (dead session, dispatch never confirmed) — and the requeue contract
+ * must still reopen the stale case. This module is that discriminator: a task id is
+ * registered here ONLY by the dispatch path at the moment it hands the claimed task
+ * to a transport, and cleared the moment the task leaves the `assigned` state
+ * (terminal completion/failure, dispatch-failure requeue, cancel, reclaim, or a
+ * forced requeue). requeueTask consults it and refuses (no-op) to reopen a task that
+ * is still in-flight unless the caller passes `force`.
+ *
+ * Dependency-free leaf (no imports) so both mesh-queue-assignment (begin) and
+ * mesh-work-queue (clear + the requeue guard) can import it without a cycle. The key
+ * is `${meshId}::${taskId}`; a task id is a single-form UUID, so no daemon-id
+ * normalization is needed on the key itself.
+ */
+/**
+ * Mark a task as actively dispatched/generating (in-flight). Called by the dispatch
+ * path right after a successful claim, before/as the task is handed to a transport.
+ * Returns true when this call transitioned the task into the in-flight set, false
+ * when it was already in-flight (a redundant begin — the caller may treat that as a
+ * signal that a dispatch is already live for this task).
+ */
+export declare function beginTaskDispatchInFlight(meshId: string, taskId: string): boolean;
+/** True while a task is actively dispatched/generating (registered by the dispatch
+ *  path and not yet cleared by a terminal/requeue/cancel transition). */
+export declare function isTaskDispatchInFlight(meshId: string, taskId: string): boolean;
+/** Clear a task's in-flight mark. Called whenever the task leaves the `assigned`
+ *  state (terminal completion/failure, dispatch-failure requeue, cancel, reclaim, or
+ *  a forced requeue). Idempotent / safe to call when the task was never in-flight. */
+export declare function endTaskDispatchInFlight(meshId: string, taskId: string): void;
+/** Test-only: drop all in-flight marks so a fresh test starts from a clean guard. */
+export declare function __resetTaskDispatchInFlightForTests(): void;