@adhdev/daemon-core 0.9.82-rc.380 → 0.9.82-rc.381

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

@@ -128,6 +128,18 @@ export declare class MeshRuntimeStore {
         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;
     /**

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/repo-mesh-types.d.ts

@@ -279,6 +279,34 @@ export interface RepoMeshNodePolicy {
     initSubmodulesOnClone?: boolean;
 }
 export declare const DEFAULT_MESH_POLICY: RepoMeshPolicy;
+/** Min/max bounds for the global write-task parallel cap. */
+export declare const MESH_MAX_PARALLEL_TASKS_MIN = 1;
+export declare const MESH_MAX_PARALLEL_TASKS_MAX = 8;
+/**
+ * Resolve the effective global write-task parallel cap from a raw policy value,
+ * clamped to [MESH_MAX_PARALLEL_TASKS_MIN, MESH_MAX_PARALLEL_TASKS_MAX] and
+ * defaulting to DEFAULT_MESH_POLICY.maxParallelTasks for a missing/NaN value.
+ * Both the config write path and the runtime scheduler read the cap through this
+ * helper so they can never disagree on what "max parallel" means.
+ */
+export declare function resolveMaxParallelTasks(value: unknown): number;
+/**
+ * Normalize an autoFastForward sub-policy, filling defaults and dropping an
+ * invalid maxBehind. Mirrors the (previously mesh-config-local) shape so the merge
+ * always emits a fully-populated, valid autoFastForward object.
+ */
+export declare function normalizeAutoFastForwardPolicy(value: unknown): NonNullable<RepoMeshPolicy['autoFastForward']>;
+/**
+ * Canonical merge+normalize for a RepoMeshPolicy. Layers (lowest→highest):
+ * DEFAULT_MESH_POLICY → base (existing persisted policy) → patch (incoming change),
+ * then applies every per-field normalizer so the result is always valid regardless
+ * of what a hand-edited meshes.json or a partial patch contained.
+ *
+ * Persistence economy is preserved: schedulingStrategy is dropped when it
+ * normalizes to the 'first_eligible' default, and autoConvergeCodeChange is dropped
+ * unless explicitly true — so an untouched meshes.json stays byte-for-byte the same.
+ */
+export declare function mergeAndNormalizePolicy(base: RepoMeshPolicy | undefined, patch: Partial<RepoMeshPolicy> | undefined): RepoMeshPolicy;
 /**
  * Resolve whether a delegated worker session launched onto `nodePolicy` (within a mesh
  * governed by `meshPolicy`) should auto-approve. Precedence: node override → mesh policy
@@ -464,6 +492,41 @@ export interface LocalMeshNodeEntry {
     relatedRepos?: RepoMeshRelatedRepo[];
     role?: RepoMeshDaemonRole;
 }
+/**
+ * Per-(node, provider) cap + consumption, as surfaced on a node's scheduling
+ * status. Wire-shape mirror of MeshNodeProviderSchedulingRuntime.
+ */
+export interface RepoMeshNodeProviderSchedulingStatus {
+    providerType: string;
+    maxParallel?: number;
+    activeAssigned: number;
+    capReached: boolean;
+}
+/**
+ * Per-node scheduling runtime exposed on RepoMeshNodeStatus.scheduling. Carried in
+ * full by verbose mesh_status; compact mesh_status sends only {load, capReached}.
+ */
+export interface RepoMeshNodeSchedulingStatus {
+    load: number;
+    schedulingPriority?: number;
+    maxConcurrentSessions?: number;
+    providerRoles?: RepoMeshNodeProviderSchedulingStatus[];
+    capReached: boolean;
+    capReasons?: string[];
+}
+/**
+ * Mesh-level scheduling rollup exposed on RepoMeshStatus.scheduling: which tie-break
+ * strategy is live and how much of the global parallel caps is consumed.
+ */
+export interface RepoMeshSchedulingStatus {
+    strategy: RepoMeshSchedulingStrategy;
+    maxParallelTasks: number;
+    maxReadonlyParallelTasks: number;
+    activeWriteAssigned: number;
+    activeReadonlyAssigned: number;
+    globalWriteCapReached: boolean;
+    globalReadonlyCapReached: boolean;
+}
 export interface RepoMeshStatus {
     meshId: string;
     meshName: string;
@@ -474,6 +537,11 @@ export interface RepoMeshStatus {
     nodes: RepoMeshNodeStatus[];
     queue?: RepoMeshQueueStatus;
     ledger?: RepoMeshLedgerStatus;
+    /**
+     * Mesh-level scheduling rollup (strategy + global cap consumption). Omitted by
+     * daemons predating the scheduling-runtime exposure — treat as optional.
+     */
+    scheduling?: RepoMeshSchedulingStatus;
     /**
      * Mission summaries for the dashboard overview. Active/paused missions plus a
      * capped, newest-first slice of completed/abandoned history. Omitted by older
@@ -545,6 +613,19 @@ export interface RepoMeshNodeStatus {
     lastSeenAt?: string;
     updatedAt?: string;
     connection?: RepoMeshPeerConnectionStatus;
+    /**
+     * Per-node scheduling runtime (load / priority / provider caps / claim-block
+     * reasons). Verbose mesh_status carries the full shape; compact carries only
+     * {load, capReached}. Omitted by daemons predating the exposure.
+     */
+    scheduling?: RepoMeshNodeSchedulingStatus;
+    /**
+     * Stale-daemon-build marker: the live daemon's build commit is a strict ancestor
+     * of this node's workspace HEAD (merged code not yet live). Best-effort, set by
+     * mesh_status when the git probe reports daemonBuildBehind; shape is daemon-defined
+     * (scope/isDaemonAffecting flags). Omitted when the build is current.
+     */
+    staleDaemonBuild?: Record<string, unknown>;
     error?: string;
 }
 export type RepoMeshQueueTaskStatus = 'pending' | 'assigned' | 'completed' | 'failed' | 'cancelled';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/daemon-core",
-  "version": "0.9.82-rc.380",
+  "version": "0.9.82-rc.381",
   "description": "ADHDev daemon core — CDP, IDE detection, providers, command execution",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -46,7 +46,7 @@
   "author": "vilmire",
   "license": "AGPL-3.0-or-later",
   "dependencies": {
-    "@adhdev/mesh-shared": "0.9.82-rc.380",
+    "@adhdev/mesh-shared": "0.9.82-rc.381",
     "@adhdev/session-host-core": "*",
     "@agentclientprotocol/sdk": "^0.16.1",
     "ajv": "^8.20.0",

package/src/config/mesh-config.ts

@@ -22,7 +22,7 @@ import type {
     RepoMeshHostMetadata,
     RepoMeshDaemonRole,
 } from '../repo-mesh-types.js';
-import { DEFAULT_MESH_POLICY, normalizeMeshSchedulingStrategy } from '../repo-mesh-types.js';
+import { mergeAndNormalizePolicy } from '../repo-mesh-types.js';
 import { createDefaultMeshHostMetadata } from '../mesh/mesh-host-ownership.js';
 
 // ─── Persistence ────────────────────────────────
@@ -151,63 +151,11 @@ export function normalizeRepoIdentity(remoteUrl: string): string {
 
 // ─── CRUD Operations ────────────────────────────
 
-const SESSION_CLEANUP_MODES = new Set(['preserve', 'stop', 'delete_stopped', 'stop_and_delete']);
-const SPAWNED_SESSION_VISIBILITY_MODES = new Set(['visible', 'hidden']);
-
-function mergeMeshPolicy(base: RepoMeshPolicy | undefined, patch: Partial<RepoMeshPolicy> | undefined): RepoMeshPolicy {
-    const autoFastForward = normalizeAutoFastForwardPolicy({
-        ...DEFAULT_MESH_POLICY.autoFastForward,
-        ...((base?.autoFastForward && typeof base.autoFastForward === 'object') ? base.autoFastForward : {}),
-        ...((patch?.autoFastForward && typeof patch.autoFastForward === 'object') ? patch.autoFastForward : {}),
-    });
-    const policy: RepoMeshPolicy = {
-        ...DEFAULT_MESH_POLICY,
-        ...(base || {}),
-        ...(patch || {}),
-        autoFastForward,
-    };
-    if (!['block', 'warn', 'checkpoint_then_continue'].includes(policy.dirtyWorkspaceBehavior)) {
-        policy.dirtyWorkspaceBehavior = 'warn';
-    }
-    const maxParallelTasks = Number(policy.maxParallelTasks);
-    policy.maxParallelTasks = Number.isFinite(maxParallelTasks) ? Math.max(1, Math.min(8, Math.floor(maxParallelTasks))) : 2;
-    policy.allowAutoPublishSubmoduleMainCommits = policy.allowAutoPublishSubmoduleMainCommits === true;
-    if (!SESSION_CLEANUP_MODES.has(String(policy.sessionCleanupOnNodeRemove))) {
-        policy.sessionCleanupOnNodeRemove = 'preserve';
-    }
-    if (!SPAWNED_SESSION_VISIBILITY_MODES.has(String(policy.spawnedSessionVisibility))) {
-        policy.spawnedSessionVisibility = DEFAULT_MESH_POLICY.spawnedSessionVisibility;
-    }
-    // Load-balancing: normalize the scheduling strategy so an invalid/blank value
-    // falls back to 'first_eligible' (strict no-change). Only persist the field when
-    // it is explicitly a non-default value to keep existing meshes.json untouched.
-    const normalizedStrategy = normalizeMeshSchedulingStrategy(policy.schedulingStrategy);
-    if (normalizedStrategy === 'first_eligible') {
-        delete policy.schedulingStrategy;
-    } else {
-        policy.schedulingStrategy = normalizedStrategy;
-    }
-    // Convergence routing: strict opt-in (default false). Only persist when explicitly
-    // enabled so existing meshes.json stays byte-for-byte untouched.
-    if (policy.autoConvergeCodeChange === true) {
-        policy.autoConvergeCodeChange = true;
-    } else {
-        delete policy.autoConvergeCodeChange;
-    }
-    return policy;
-}
-
-function normalizeAutoFastForwardPolicy(value: unknown): NonNullable<RepoMeshPolicy['autoFastForward']> {
-    const record = value && typeof value === 'object' && !Array.isArray(value)
-        ? value as Record<string, unknown>
-        : {};
-    const maxBehind = Number(record.maxBehind);
-    return {
-        enabled: record.enabled !== false,
-        ...(Number.isFinite(maxBehind) && maxBehind >= 0 ? { maxBehind: Math.floor(maxBehind) } : {}),
-        requireCleanSubmodules: record.requireCleanSubmodules !== false,
-    };
-}
+// Single source of truth for default+merge+per-field normalization is
+// mergeAndNormalizePolicy in repo-mesh-types.ts. This thin alias keeps the local
+// call sites (createMesh/updateMesh) reading naturally while ensuring config
+// writes go through the exact same normalizer the scheduler/display paths use.
+const mergeMeshPolicy = mergeAndNormalizePolicy;
 
 export function listMeshes(): LocalMeshEntry[] {
     return loadMeshConfig().meshes;

package/src/index.ts

@@ -135,6 +135,9 @@ export type {
   RepoMeshLedgerStatus,
   MeshAsyncJobLifecycle,
   RepoMeshSchedulingStrategy,
+  RepoMeshSchedulingStatus,
+  RepoMeshNodeSchedulingStatus,
+  RepoMeshNodeProviderSchedulingStatus,
 } from './repo-mesh-types.js';
 export {
   DEFAULT_MESH_POLICY,
@@ -143,6 +146,12 @@ export {
   DEFAULT_MESH_SCHEDULING_STRATEGY,
   normalizeMeshSchedulingStrategy,
   resolveNodeSchedulingPriority,
+  resolveProviderMaxParallel,
+  mergeAndNormalizePolicy,
+  normalizeAutoFastForwardPolicy,
+  resolveMaxParallelTasks,
+  MESH_MAX_PARALLEL_TASKS_MIN,
+  MESH_MAX_PARALLEL_TASKS_MAX,
   MESH_CONVERGE_REFINE_TAG,
   MESH_CONVERGE_FAST_FORWARD_TAG,
   resolveAutoConvergeCodeChange,
@@ -246,6 +255,10 @@ export type { MeshActiveWorkRecord, MeshActiveWorkStatus, MeshActiveWorkSummary,
 export { buildMeshAsyncRefineJobs, summarizeMeshAsyncRefineJobs, STALE_TERMINAL_REFINE_WINDOW_MS, RECENT_TERMINAL_REFINE_CAP } from './mesh/mesh-refine-status.js';
 export type { MeshAsyncRefineJobStatus, MeshAsyncRefineJobSummary, MeshAsyncRefineJobsSummary } from './mesh/mesh-refine-status.js';
 
+// ── Mesh Scheduling Runtime (observability projection) ──
+export { buildMeshSchedulingRuntime } from './mesh/mesh-scheduling-runtime.js';
+export type { MeshSchedulingRuntime, MeshNodeSchedulingRuntime, MeshNodeProviderSchedulingRuntime } from './mesh/mesh-scheduling-runtime.js';
+
 // ── Mesh Host Ownership ──
 export { buildMeshHostRequiredFailure, createDefaultMeshHostMetadata, isMeshHostOwner, normalizeMeshDaemonRole, requireMeshHostQueueOwner, resolveMeshHostStatus } from './mesh/mesh-host-ownership.js';
 

package/src/mesh/coordinator-prompt.ts

@@ -31,7 +31,7 @@ import type {
     RepoMeshStatus,
     RepoMeshNodeStatus,
 } from '../repo-mesh-types.js';
-import { DEFAULT_MESH_POLICY } from '../repo-mesh-types.js';
+import { mergeAndNormalizePolicy } from '../repo-mesh-types.js';
 
 /**
  * Cheap, locally-derived "what just happened" snapshot for the coordinator
@@ -196,7 +196,7 @@ Repository: \`${mesh.repoIdentity}\`${mesh.defaultBranch ? `\nDefault branch: \`
     if (operatingNotes) sections.push(operatingNotes);
 
     // ── Policy ──
-    sections.push(buildPolicySection({ ...DEFAULT_MESH_POLICY, ...(mesh.policy || {}) }));
+    sections.push(buildPolicySection(mergeAndNormalizePolicy(undefined, mesh.policy)));
 
     // ── Tools ──
     sections.push(TOOLS_SECTION);
@@ -278,7 +278,7 @@ function expandPromptPlaceholders(template: string, ctx: CoordinatorPromptContex
         mission: ctx.missionSection?.trim() || '',
         recentActivity: buildRecentActivitySection(ctx.recentActivity) || '',
         operatingNotes: buildOperatingNotesSection(ctx.operatingNotes) || '',
-        policy: buildPolicySection({ ...DEFAULT_MESH_POLICY, ...(mesh.policy || {}) }),
+        policy: buildPolicySection(mergeAndNormalizePolicy(undefined, mesh.policy)),
         tools: TOOLS_SECTION,
         workflow: WORKFLOW_SECTION,
         rules: buildRulesSection(coordinatorCliType),

package/src/mesh/mesh-event-forwarding.ts

@@ -886,8 +886,24 @@ function injectMeshSystemMessage(components: DaemonComponents, args: {
             // sibling/stale dispatch row this event does not own, marking it 'acked' prematurely and
             // hiding a genuine non-delivery. Skip the dispatch ack for that ghost case (the delivery
             // acks below are bound to actual deliveries and stay a no-op for a warmup session).
-            if (startedTaskId || sessionHasActiveAssignment(args.meshId, sessionId)) {
+            //
+            // MESH-DISPATCH-MISROUTE (fix 3, consumer residual): when the event carries no taskId
+            // (a legacy/relayed worker whose producer never stamped meshActiveTaskId) but the
+            // session owns EXACTLY ONE active dispatch, resolve that row's taskId and flip it by PK
+            // instead of the session_id sweep — the sweep flips every non-terminal row for the
+            // session ("may flip a sibling dispatch row"). With ≥2 active rows the owner is
+            // ambiguous, so resolvedAckTaskId stays undefined and we DROP the ack rather than
+            // mis-flip a sibling (the genuine ack arrives once the producer/reconcile names a task).
+            if (startedTaskId) {
                 updateDirectDispatchStatus(args.meshId, sessionId, 'acked', startedTaskId);
+            } else if (sessionHasActiveAssignment(args.meshId, sessionId)) {
+                const soleTaskId = (() => {
+                    try { return MeshRuntimeStore.getInstance().getSoleActiveDirectDispatchTaskId(args.meshId, sessionId); }
+                    catch { return null; }
+                })();
+                if (soleTaskId) {
+                    updateDirectDispatchStatus(args.meshId, sessionId, 'acked', soleTaskId);
+                }
             }
             const activeDeliveries = ((): { id: string; taskId: string | null }[] => {
                 try { return MeshRuntimeStore.getInstance().getActiveSessionDeliveries(args.meshId, sessionId); }

package/src/mesh/mesh-runtime-store.ts

@@ -903,6 +903,29 @@ export class MeshRuntimeStore {
         `).run({ status, meshId, sessionId, updatedAt: now });
     }
 
+    /**
+     * 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 {
+        if (!sessionId) return null;
+        const rows = this.db.prepare(`
+            SELECT task_id FROM mesh_direct_dispatches
+            WHERE mesh_id = ? AND session_id = ?
+              AND status NOT IN ('completed', 'failed', 'stale')
+        `).all(meshId, sessionId) as Array<{ task_id: string }>;
+        if (rows.length !== 1) return null;
+        const taskId = typeof rows[0]?.task_id === 'string' ? rows[0].task_id.trim() : '';
+        return taskId || null;
+    }
+
     cleanupTerminalDirectDispatches(olderThanMs: number): void {
         const cutoff = new Date(Date.now() - olderThanMs).toISOString();
         this.db.prepare(`

package/src/mesh/mesh-scheduling-runtime.ts

@@ -0,0 +1,199 @@
+// Mesh scheduling-runtime view — a read-only, derived projection of how the queue
+// scheduler currently sees the mesh: which tie-break strategy is live, the global
+// parallel caps and how much of them is consumed, and per-node load / priority /
+// per-(node, provider) caps plus a structured "why this node can't take more write
+// work right now" reason set.
+//
+// This is OBSERVABILITY ONLY. It re-derives the same numbers the live claim path
+// (maybeAutoLaunchOneQueueSession → orderEligibleNodes → claimNextQueueTask) acts
+// on, but never mutates anything and never drives a scheduling decision. It is built
+// from the in-memory mesh config + the queue snapshot, so callers (mesh_status) get a
+// consistent picture without touching the SQLite claim transaction. Keeping the
+// derivation here — next to the constants it mirrors — means the exposed numbers and
+// the enforced numbers stay defined in one module family.
+
+import type { RepoMeshNodePolicy, RepoMeshSchedulingStrategy } from '../repo-mesh-types.js';
+import {
+    normalizeMeshSchedulingStrategy,
+    resolveMaxParallelTasks,
+    resolveNodeSchedulingPriority,
+    resolveProviderMaxParallel,
+} from '../repo-mesh-types.js';
+import { normalizeMeshNodeId } from '@adhdev/mesh-shared';
+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;
+}
+
+function isReadonly(task: MeshWorkQueueEntry): boolean {
+    return task.taskMode === 'live_debug_readonly';
+}
+
+function isAssigned(task: MeshWorkQueueEntry): boolean {
+    return task.status === 'assigned';
+}
+
+/**
+ * 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 function buildMeshSchedulingRuntime(
+    mesh: MeshLike | null | undefined,
+    queue: MeshWorkQueueEntry[],
+): MeshSchedulingRuntime {
+    const strategy = normalizeMeshSchedulingStrategy(mesh?.policy?.schedulingStrategy);
+    const maxParallelTasks = resolveMaxParallelTasks(mesh?.policy?.maxParallelTasks);
+    // Read-only diagnoses are exempt from the write cap and get their own higher
+    // safety cap (2× the write cap, floor 2) — identical to the claim path.
+    const maxReadonlyParallelTasks = Math.max(2, maxParallelTasks * 2);
+
+    const assignedTasks = (Array.isArray(queue) ? queue : []).filter(isAssigned);
+    const activeWriteAssigned = assignedTasks.filter(t => !isReadonly(t)).length;
+    const activeReadonlyAssigned = assignedTasks.filter(isReadonly).length;
+    const globalWriteCapReached = activeWriteAssigned >= maxParallelTasks;
+    const globalReadonlyCapReached = activeReadonlyAssigned >= maxReadonlyParallelTasks;
+
+    // Pre-bucket assigned tasks by node so per-node load and per-provider counts are
+    // a single pass rather than O(nodes × queue).
+    const writeAssignedByNode = new Map<string, number>();
+    const assignedByNode = new Map<string, number>();
+    const providerCountByNode = new Map<string, Map<string, number>>();
+    for (const task of assignedTasks) {
+        const nodeId = typeof task.assignedNodeId === 'string' ? task.assignedNodeId.trim() : '';
+        if (!nodeId) continue;
+        assignedByNode.set(nodeId, (assignedByNode.get(nodeId) ?? 0) + 1);
+        if (!isReadonly(task)) {
+            writeAssignedByNode.set(nodeId, (writeAssignedByNode.get(nodeId) ?? 0) + 1);
+        }
+        const provider = typeof task.assignedProviderType === 'string' ? task.assignedProviderType : '';
+        if (provider) {
+            let byProvider = providerCountByNode.get(nodeId);
+            if (!byProvider) { byProvider = new Map(); providerCountByNode.set(nodeId, byProvider); }
+            byProvider.set(provider, (byProvider.get(provider) ?? 0) + 1);
+        }
+    }
+
+    const nodes: MeshNodeSchedulingRuntime[] = [];
+    for (const rawNode of (Array.isArray(mesh?.nodes) ? mesh!.nodes! : [])) {
+        const nodeId = normalizeMeshNodeId(rawNode);
+        if (!nodeId) continue;
+        const policy = (rawNode?.policy || undefined) as RepoMeshNodePolicy | undefined;
+        const load = assignedByNode.get(nodeId) ?? 0;
+        const schedulingPriority = resolveNodeSchedulingPriority(policy);
+
+        const capReasons: string[] = [];
+        if (globalWriteCapReached) capReasons.push('global_max_parallel_tasks_reached');
+        // Write isolation: a node already holding an assigned write task can't take another.
+        if ((writeAssignedByNode.get(nodeId) ?? 0) > 0) capReasons.push('node_has_active_assignment');
+
+        // Per-(node, provider) caps, with live consumption.
+        let providerRoles: MeshNodeProviderSchedulingRuntime[] | undefined;
+        const declaredRoles = Array.isArray(policy?.providerRoles) ? policy!.providerRoles! : [];
+        if (declaredRoles.length) {
+            const byProvider = providerCountByNode.get(nodeId);
+            providerRoles = [];
+            for (const role of declaredRoles) {
+                if (!role || typeof role !== 'object') continue;
+                const providerType = typeof role.providerType === 'string' ? role.providerType.trim() : '';
+                if (!providerType) continue;
+                const maxParallel = resolveProviderMaxParallel(policy, providerType);
+                const activeAssigned = byProvider?.get(providerType) ?? 0;
+                const capReached = maxParallel !== undefined && activeAssigned >= maxParallel;
+                providerRoles.push({
+                    providerType,
+                    ...(maxParallel !== undefined ? { maxParallel } : {}),
+                    activeAssigned,
+                    capReached,
+                });
+                if (capReached) capReasons.push(`max_provider_parallel_reached:${providerType}`);
+            }
+            if (!providerRoles.length) providerRoles = undefined;
+        }
+
+        const maxConcurrentSessions = Number(policy?.maxConcurrentSessions);
+        const hasSessionCap = Number.isFinite(maxConcurrentSessions) && maxConcurrentSessions >= 0;
+
+        nodes.push({
+            nodeId,
+            load,
+            schedulingPriority,
+            ...(hasSessionCap ? { maxConcurrentSessions: Math.floor(maxConcurrentSessions) } : {}),
+            ...(providerRoles ? { providerRoles } : {}),
+            capReached: capReasons.length > 0,
+            capReasons,
+        });
+    }
+
+    return {
+        strategy,
+        maxParallelTasks,
+        maxReadonlyParallelTasks,
+        activeWriteAssigned,
+        activeReadonlyAssigned,
+        globalWriteCapReached,
+        globalReadonlyCapReached,
+        nodes,
+    };
+}