@adhdev/daemon-core 0.9.82-rc.49 → 0.9.82-rc.490

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;

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,34 @@
+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;
+}
+/** Register (or clear, with undefined) the PHASE 0 retry nudge handler. */
+export declare function registerUnresolvedForwardRetryNudge(handler?: () => void): void;
+/** Fire-and-forget nudge: ask the reconcile loop to run the outbox retry soon. */
+export declare function nudgeUnresolvedForwardRetry(): void;
+/**
+ * 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;