@adhdev/daemon-core 0.9.82-rc.484 → 0.9.82-rc.486

package/src/mesh/mesh-queue-assignment.ts

@@ -2,7 +2,7 @@ import { existsSync } from 'fs';
 import type { DaemonComponents } from '../boot/daemon-lifecycle.js';
 import { MESH_CONNECT_TIMEOUT_MS } from '../runtime-defaults.js';
 import { loadConfig } from '../config/config.js';
-import { getMesh } from '../config/mesh-config.js';
+import { getMesh, getDifficultyBrains } from '../config/mesh-config.js';
 import { detectCLI } from '../detection/cli-detector.js';
 import { LOG } from '../logging/logger.js';
 import { appendLedgerEntry } from './mesh-ledger.js';
@@ -15,7 +15,7 @@ import { traceMeshEventDrop } from './mesh-event-trace.js';
 import { awaitWithWarmupDeadline, resolveWarmupDeadlineOpts } from './mesh-warmup-deadline.js';
 import { resolveDelegatedWorkerAutoApprove, resolveProviderMaxParallel, resolveNodeSchedulingPriority, normalizeMeshSchedulingStrategy, resolveMaxParallelTasks, resolveMaxReadonlyParallelTasks } from '../repo-mesh-types.js';
 import type { RepoMeshSchedulingStrategy } from '../repo-mesh-types.js';
-import { normalizeMeshNodeId, meshNodeIdMatches, daemonIdsEquivalent, canonicalDaemonId, normalizeMeshWorkspaceForCompare, meshWorkspacesEquivalent, sessionIdsEquivalent, type MeshNodeIdentified } from '@adhdev/mesh-shared';
+import { normalizeMeshNodeId, meshNodeIdMatches, daemonIdsEquivalent, canonicalDaemonId, normalizeMeshWorkspaceForCompare, meshWorkspacesEquivalent, sessionIdsEquivalent, deriveSlotsFromLegacy, normalizeNodeCapabilitySlots, isMeshTaskDifficulty, type MeshNodeIdentified, type NodeCapabilitySlot, type MeshTaskDifficulty } from '@adhdev/mesh-shared';
 import { findTerminalLedgerEvidenceForTask, hasUnterminalDirectDispatchLedgerEntry } from './mesh-events-stale.js';
 import { readNonEmptyString } from './mesh-events-utils.js';
 import { readMeshNodeDaemonId } from './mesh-node-identity.js';
@@ -92,12 +92,62 @@ export function getMeshWithCache(components: DaemonComponents, meshId: string):
  * worktree node therefore read a permanently stale 'running' here, so
  * shouldDeferDispatchForBootstrap deferred its claim forever. We now MERGE the inline
  * cache's dynamic runtime bootstrap state onto the config node (config keeps its static
- * fields; worktreeBootstrap is preferred from the inline cache when the inline entry
- * carries a status) so the gate view sees the terminal stamp. Regression-safe: when the
- * inline entry has no bootstrap status the config value is kept, and when bootstrap is
- * genuinely still 'running' (no terminal stamp yet) the gate still defers — only a node
- * whose inline stamp has actually reached a terminal state opens the gate.
+ * fields; worktreeBootstrap is preferred from the inline cache) so EVERY consumer of the
+ * merged view — not just tryAssignQueueTask's gate — observes the terminal stamp.
+ *
+ * RESIDUAL-getMeshWithCache-bootstrap-overlay (precedence guard): the overlay is DIRECTIONAL —
+ * it prefers the inline entry ONLY when the inline runtime state is actually fresher, never
+ * merely because the inline entry carries a status. inlineBootstrapIsFresher() (below) permits
+ * the overlay in exactly two cases, mirroring the mission's "terminal OR strictly newer" rule:
+ *   (1) the inline state is TERMINAL ('complete'/'failed') while the config state is NOT — the
+ *       markWorktreeBootstrapTerminalState synchronous stamp the async config persist has not
+ *       yet caught up to; this is the whole point of the overlay (opens the gate).
+ *   (2) both states are non-terminal but the inline startedAt is STRICTLY newer — a re-driven
+ *       bootstrap whose fresher 'running' epoch the config has not observed.
+ * It REFUSES the overlay when the config state is already terminal and the inline state is a
+ * stale/non-terminal 'running' — otherwise a stale inline 'running' would MASK a genuinely
+ * complete config node and re-defer its claim forever (the exact anti-case this guard closes).
+ * And when both are 'running' with no newer epoch, the config value is kept and the gate still
+ * defers — the half-built-worktree → empty-session defense is preserved: only a terminal-confirmed
+ * inline state, never an ambiguous read, ever opens the gate.
+ */
+const BOOTSTRAP_TERMINAL_STATUSES = new Set(['complete', 'failed']);
+
+function bootstrapEpochMs(bootstrap: any): number {
+    const raw = readNonEmptyString(bootstrap?.startedAt) || readNonEmptyString(bootstrap?.completedAt);
+    if (!raw) return 0;
+    const parsed = Date.parse(raw);
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+
+/**
+ * Directional freshness test for the bootstrap overlay: may the inline runtime state
+ * REPLACE the config runtime state? True only when the inline state is terminal and the
+ * config state is not (the synchronous terminal stamp the async persist lags), or when
+ * both are non-terminal but the inline epoch is strictly newer. A terminal config state is
+ * never overwritten by a non-terminal inline read (the stale-'running'-masks-complete
+ * anti-case), and equal states never trigger a rewrite.
  */
+function inlineBootstrapIsFresher(inlineBootstrap: any, configBootstrap: any): boolean {
+    const inlineStatus = readNonEmptyString(inlineBootstrap?.status);
+    if (!inlineStatus) return false;
+    const configStatus = readNonEmptyString(configBootstrap?.status);
+    const inlineTerminal = BOOTSTRAP_TERMINAL_STATUSES.has(inlineStatus);
+    const configTerminal = !!configStatus && BOOTSTRAP_TERMINAL_STATUSES.has(configStatus);
+    // Config already terminal: only a DIFFERENT terminal inline state (e.g. config 'complete'
+    // vs a later 'failed' re-drive) may supersede it; a non-terminal inline read must never
+    // mask a terminal config state.
+    if (configTerminal) {
+        return inlineTerminal && inlineStatus !== configStatus
+            && bootstrapEpochMs(inlineBootstrap) > bootstrapEpochMs(configBootstrap);
+    }
+    // Config not terminal: an inline terminal state is always fresher (opens the gate).
+    if (inlineTerminal) return true;
+    // Both non-terminal: prefer inline only when its epoch is strictly newer (a re-driven
+    // bootstrap the config has not observed). Equal/older ⇒ keep config, gate still defers.
+    return bootstrapEpochMs(inlineBootstrap) > bootstrapEpochMs(configBootstrap);
+}
+
 function mergeInlineCacheOnlyNodes(localMesh: any, cachedMesh: any): any {
     const localNodes = Array.isArray(localMesh?.nodes) ? localMesh.nodes : [];
     const cachedNodes = Array.isArray(cachedMesh?.nodes) ? cachedMesh.nodes : [];
@@ -111,10 +161,10 @@ function mergeInlineCacheOnlyNodes(localMesh: any, cachedMesh: any): any {
         if (!cachedId) return false;
         return !localNodes.some((localNode: any) => meshNodeIdMatches(localNode, cachedId));
     });
-    // Overlay the inline cache's fresher worktreeBootstrap state onto any config node
-    // that also exists in the inline cache. Only override when the inline entry actually
-    // carries a bootstrap status (an incomplete inline entry never masks a genuine config
-    // 'running'), mirroring the inline-first read the bootstrap gate does directly.
+    // Overlay the inline cache's fresher worktreeBootstrap state onto any config node that
+    // also exists in the inline cache. inlineBootstrapIsFresher() gates the overlay to the
+    // "terminal OR strictly newer" cases, so a stale inline 'running' can never mask a
+    // terminal config state and the gate's deferral is preserved for a genuine 'running'.
     let overlaidLocalNodes: any[] = localNodes;
     let overlaid = false;
     for (let i = 0; i < localNodes.length; i++) {
@@ -122,14 +172,14 @@ function mergeInlineCacheOnlyNodes(localMesh: any, cachedMesh: any): any {
         const localId = readMeshNodeId(localNode);
         if (!localId) continue;
         const inlineMatch = cachedNodes.find((cachedNode: any) => meshNodeIdMatches(cachedNode, localId));
-        const inlineBootstrapStatus = readNonEmptyString(inlineMatch?.worktreeBootstrap?.status);
-        if (!inlineMatch || !inlineBootstrapStatus) continue;
+        if (!inlineMatch) continue;
+        if (!inlineBootstrapIsFresher(inlineMatch.worktreeBootstrap, localNode.worktreeBootstrap)) continue;
         if (!overlaid) {
             overlaidLocalNodes = [...localNodes];
             overlaid = true;
         }
-        // Keep the config node's static fields; prefer the inline cache's dynamic
-        // bootstrap runtime state (fresher terminal stamp).
+        // Keep the config node's static fields; overlay only the dynamic worktreeBootstrap
+        // runtime substate (fresher terminal stamp / epoch) — config identity is unchanged.
         overlaidLocalNodes[i] = { ...localNode, worktreeBootstrap: inlineMatch.worktreeBootstrap };
     }
     if (!cacheOnly.length && !overlaid) return localMesh;
@@ -1091,17 +1141,36 @@ function nodeActiveLoad(meshId: string, nodeId: string): number {
     return MeshRuntimeStore.getInstance().nodeActiveAssignmentCount(meshId, nodeId);
 }
 
+/** True when any node in the mesh has an EXPLICIT capability-slot list configured
+ *  (policy.slots). Legacy-derived slots don't count — only an operator (or the
+ *  orchestrator, with approval) authoring slots signals intent to route by fitness. */
+function meshHasExplicitSlots(mesh: any): boolean {
+    const nodes = Array.isArray(mesh?.nodes) ? mesh.nodes : [];
+    return nodes.some((n: any) => normalizeNodeCapabilitySlots(n?.policy?.slots).length > 0);
+}
+
 /**
  * The mesh-wide scheduling strategy, read from the MACHINE-LOCAL stored mesh
  * policy. Resolution order:
- *   1. the stored mesh policy schedulingStrategy raw 4-union, then
- *   2. 'first_eligible' (strict no-change default).
- * Policy is machine-local only — there is no repo-file (`.adhdev/mesh.json`)
- * overlay. Only governs the final tie-break; eligibility, capacity, and priority
- * gates apply identically to every strategy.
+ *   1. an EXPLICITLY stored schedulingStrategy (operator picked a mode) wins, else
+ *   2. 'fitness' AUTO when the mesh has any node with explicit capability slots —
+ *      configuring slots is itself the signal to route tasks by task→slot fitness
+ *      (difficulty/capability), no separate strategy toggle required, else
+ *   3. 'first_eligible' (strict no-change default for slot-less meshes).
+ *
+ * Persistence economy drops schedulingStrategy from policy when it equals the
+ * first_eligible default (repo-mesh-types normalizeMeshPolicy), so an ABSENT value
+ * means "unset" — safe to auto-upgrade — while a PRESENT value means the operator
+ * chose it and we never override. Policy is machine-local only; this only governs
+ * the final tie-break — eligibility, capacity, and priority gates are unchanged.
  */
 function resolveSchedulingStrategy(mesh: any): RepoMeshSchedulingStrategy {
-    return normalizeMeshSchedulingStrategy(mesh?.policy?.schedulingStrategy);
+    const raw = mesh?.policy?.schedulingStrategy;
+    if (typeof raw === 'string' && raw.trim()) {
+        return normalizeMeshSchedulingStrategy(raw);
+    }
+    // Unset → auto-fitness when slots exist, else the historical default.
+    return meshHasExplicitSlots(mesh) ? 'fitness' : normalizeMeshSchedulingStrategy(undefined);
 }
 
 /**
@@ -1143,7 +1212,7 @@ export function __orderEligibleNodesForTests(
     meshId: string,
     strategy: RepoMeshSchedulingStrategy,
     nodes: RankableNode[],
-    opts?: { bumpCursor?: boolean },
+    opts?: { bumpCursor?: boolean; task?: { difficulty?: string; requiredTags?: string[] } },
 ): RankableNode[] {
     return orderEligibleNodes(meshId, strategy, nodes, opts);
 }
@@ -1199,16 +1268,107 @@ export function __buildSchedulingPoolForTests(
     return buildSchedulingPool(localCandidates, remoteCandidates);
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Node capability slots — task→node/slot fitness (ORCHESTRATION_NODE_SLOTS.md)
+//
+// A node's capability slots are the single source of truth for routing. When a
+// node has explicit `policy.slots` we use them; otherwise we derive slots from the
+// legacy providerPriority/providerRoles + the machine-global difficultyBrains so
+// existing nodes keep working (back-compat). The fitness scorer ranks a node for a
+// specific task by how well its best slot matches the task's difficulty and
+// required tags — with graceful fallback so a task is never blocked by a missing
+// exact match.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** The task shape the fitness scorer reads (a subset of MeshWorkQueueEntry). */
+interface FitnessTask {
+    difficulty?: string;
+    requiredTags?: string[];
+}
+
+/** Resolve a node's capability slots: explicit policy.slots, else derived from legacy. */
+function resolveNodeCapabilitySlots(node: any): NodeCapabilitySlot[] {
+    const explicit = normalizeNodeCapabilitySlots(node?.policy?.slots);
+    if (explicit.length) return explicit;
+    let difficultyBrains: any;
+    try { difficultyBrains = getDifficultyBrains(); } catch { difficultyBrains = undefined; }
+    return deriveSlotsFromLegacy({
+        providerPriority: normalizeProviderPriority(node?.policy),
+        providerRoles: Array.isArray(node?.policy?.providerRoles) ? node.policy.providerRoles : undefined,
+        difficultyBrains,
+    });
+}
+
+/**
+ * Score how well one slot fits a task. Higher = better. A slot whose difficulty
+ * range contains the task's difficulty scores highest; a general-purpose slot
+ * (no declared difficulty) is a valid fallback; a slot whose capability tags cover
+ * the task's requiredTags gets a capability bonus. Never negative — the worst a
+ * slot does is score 0 (still selectable as a last-resort fallback).
+ */
+function scoreSlotForTask(slot: NodeCapabilitySlot, task: FitnessTask): number {
+    let score = 1; // base: any slot can run the task (fallback floor)
+    const diff = isMeshTaskDifficulty(task.difficulty) ? task.difficulty as MeshTaskDifficulty : undefined;
+    if (diff) {
+        if (slot.difficulty?.length) {
+            score += slot.difficulty.includes(diff) ? 100 : 0; // exact difficulty match dominates
+        } else {
+            score += 20; // general-purpose slot: decent fallback for any difficulty
+        }
+    }
+    const req = task.requiredTags?.filter(t => !!t) ?? [];
+    if (req.length) {
+        const cap = new Set(slot.capability ?? []);
+        const covered = req.every(t => cap.has(t));
+        score += covered ? 30 : 0; // capability coverage bonus (hard filter is applied elsewhere)
+    }
+    return score;
+}
+
+/** Best (slot, score) for a task on a node, or null when the node has no slots. */
+function bestSlotForTask(node: any, task: FitnessTask): { slot: NodeCapabilitySlot; score: number } | null {
+    const slots = resolveNodeCapabilitySlots(node);
+    if (!slots.length) return null;
+    let best: { slot: NodeCapabilitySlot; score: number } | null = null;
+    for (const slot of slots) {
+        const score = scoreSlotForTask(slot, task);
+        if (!best || score > best.score) best = { slot, score };
+    }
+    return best;
+}
+
+/** Node-level fitness for a task = its best slot's score (0 when the node has no slots). */
+function nodeFitnessForTask(node: any, task: FitnessTask): number {
+    return bestSlotForTask(node, task)?.score ?? 0;
+}
+
 function orderEligibleNodes(
     meshId: string,
     strategy: RepoMeshSchedulingStrategy,
     nodes: RankableNode[],
-    opts?: { bumpCursor?: boolean },
+    opts?: { bumpCursor?: boolean; task?: FitnessTask },
 ): RankableNode[] {
     if (strategy === 'first_eligible' || nodes.length <= 1) {
         return nodes;
     }
 
+    // Fitness strategy: rank by task→slot fit first (when a task is in scope —
+    // auto-launch drains per-task), then fall through to priority/load/rotation for
+    // ties. Without a task (idle-session drain ranks task-independently) fitness is
+    // inert and this behaves like least_loaded.
+    if (strategy === 'fitness' && opts?.task) {
+        const task = opts.task;
+        return [...nodes].sort((a, b) => {
+            const fitDelta = nodeFitnessForTask(b.node, task) - nodeFitnessForTask(a.node, task);
+            if (fitDelta !== 0) return fitDelta; // higher fitness first
+            const prioDelta = resolveNodeSchedulingPriority(b.node?.policy) - resolveNodeSchedulingPriority(a.node?.policy);
+            if (prioDelta !== 0) return prioDelta;
+            const loadDelta = nodeActiveLoad(meshId, a.nodeId) - nodeActiveLoad(meshId, b.nodeId);
+            if (loadDelta !== 0) return loadDelta;
+            return a.index - b.index;
+        });
+    }
+
     const priorityOf = (n: { node: any }) => resolveNodeSchedulingPriority(n.node?.policy);
 
     // Round-robin rotation offset: rotate the deterministic input order by a
@@ -1492,19 +1652,29 @@ async function resolveUsableProvider(
     nodeId: string,
     node: any,
     requiredTags?: string[],
-): Promise<{ providerType?: string; reason?: string }> {
-    const providerPriority = normalizeProviderPriority(node?.policy);
-    if (!providerPriority.length) return { reason: 'missing_provider_priority' };
+    task?: FitnessTask,
+): Promise<{ providerType?: string; model?: string; thinkingLevel?: string; reason?: string }> {
     const providerLoader = components.providerLoader;
     if (!providerLoader) return { reason: 'provider_loader_unavailable' };
 
+    // Slot-based order (ORCHESTRATION_NODE_SLOTS.md): rank the node's capability
+    // slots by task→slot fitness (difficulty/requiredTags) so the best-fit slot's
+    // provider is tried first, and its model/thinkingLevel ride along. Falls back
+    // to the legacy providerPriority-derived slots when no explicit slots exist.
+    const slots = resolveNodeCapabilitySlots(node);
+    if (!slots.length) return { reason: 'missing_provider_priority' };
+    const orderedSlots = task
+        ? [...slots].sort((a, b) => scoreSlotForTask(b, task) - scoreSlotForTask(a, task))
+        : slots;
+
     const failed: string[] = [];
-    for (const requestedType of providerPriority) {
+    for (const slot of orderedSlots) {
+        const requestedType = slot.provider;
         const normalizedType = typeof providerLoader.resolveAlias === 'function'
             ? providerLoader.resolveAlias(requestedType)
             : requestedType;
         // Skip providers that can't satisfy the task's requiredTags (e.g. provider=hermes-cli
-        // means only hermes-cli qualifies, not any other type in providerPriority).
+        // means only hermes-cli qualifies, not any other slot's provider).
         if (requiredTags?.length && !nodeSatisfiesRequiredTags(requiredTags, buildMeshNodeCapabilityTags(node, normalizedType))) {
             failed.push(`${requestedType}: required_tags_mismatch`);
             continue;
@@ -1528,7 +1698,13 @@ async function resolveUsableProvider(
             }], false);
         }
         (components as any).onStatusChange?.();
-        if (detected) return { providerType: normalizedType };
+        if (detected) {
+            return {
+                providerType: normalizedType,
+                ...(slot.model ? { model: slot.model } : {}),
+                ...(slot.thinkingLevel ? { thinkingLevel: slot.thinkingLevel } : {}),
+            };
+        }
         failed.push(`${requestedType}: not detected`);
     }
     return { reason: `provider_priority_unusable: ${failed.join('; ') || nodeId}` };
@@ -1800,7 +1976,9 @@ async function maybeAutoLaunchOneQueueSession(components: DaemonComponents, mesh
                 candidateNodes
                     .map((node: any, index: number) => ({ nodeId: readMeshNodeId(node), node, index }))
                     .filter((c: RankableNode) => c.nodeId),
-                { bumpCursor: true },
+                // Auto-launch drains one task at a time, so the task IS in scope here —
+                // pass it through for the 'fitness' strategy's task→slot ranking.
+                { bumpCursor: true, task: { difficulty: (task as any).difficulty, requiredTags: task.requiredTags } },
             ).map((c: RankableNode) => c.node);
 
         for (const node of orderedCandidateNodes) {
@@ -1864,11 +2042,16 @@ async function maybeAutoLaunchOneQueueSession(components: DaemonComponents, mesh
 
             autoLaunchInProgress.add(launchKey);
             try {
-                const resolved = await resolveUsableProvider(components, nodeId, node, task.requiredTags);
+                const resolved = await resolveUsableProvider(components, nodeId, node, task.requiredTags, { difficulty: (task as any).difficulty, requiredTags: task.requiredTags });
                 if (!resolved.providerType) {
                     markAutoLaunch(meshId, task.id, { status: 'skipped', reason: resolved.reason || 'provider_unusable', nodeId });
                     continue;
                 }
+                // Slot-derived model/thinking: an explicit task.model/thinkingLevel
+                // (resolved from the enqueue-time brain) still wins; the matched
+                // slot fills only what the task left blank (ORCHESTRATION_NODE_SLOTS.md).
+                const effectiveModel = (typeof task.model === 'string' && task.model.trim()) ? task.model.trim() : resolved.model;
+                const effectiveThinkingLevel = (typeof task.thinkingLevel === 'string' && task.thinkingLevel.trim()) ? task.thinkingLevel.trim() : resolved.thinkingLevel;
 
                 // Don't spawn a session for a (node, provider) already at its declared
                 // maxParallel cap — it would launch only to fail the claim. The claim
@@ -1917,9 +2100,10 @@ async function maybeAutoLaunchOneQueueSession(components: DaemonComponents, mesh
                             settings: remoteSettings,
                             // MAGI-KIND-PANEL model axis: forward the task's model override so the
                             // remote worker session launches with it (initialModel). Best-effort.
-                            ...(typeof task.model === 'string' && task.model.trim() ? { initialModel: task.model.trim() } : {}),
-                            // BRAIN-ROUTING thinking axis: forward the task's thinking level (initialThinkingLevel).
-                            ...(typeof task.thinkingLevel === 'string' && task.thinkingLevel.trim() ? { initialThinkingLevel: task.thinkingLevel.trim() } : {}),
+                            // Slot-aware: task override wins, else the matched slot's model.
+                            ...(effectiveModel ? { initialModel: effectiveModel } : {}),
+                            // BRAIN-ROUTING thinking axis: forward the effective thinking level (initialThinkingLevel).
+                            ...(effectiveThinkingLevel ? { initialThinkingLevel: effectiveThinkingLevel } : {}),
                         });
                     } catch (e: any) {
                         markAutoLaunch(meshId, task.id, { status: 'failed', reason: `remote_launch_dispatch_failed: ${e?.message || String(e)}`, nodeId, providerType: resolved.providerType });
@@ -1949,11 +2133,11 @@ async function maybeAutoLaunchOneQueueSession(components: DaemonComponents, mesh
                     cliType: resolved.providerType,
                     dir: node.workspace,
                     settings: launchSettings,
-                    // MAGI-KIND-PANEL model axis: local launch forwards the task's model
-                    // override as initialModel (CLI → modelLaunchArgs; ACP → setConfigOption).
-                    ...(typeof task.model === 'string' && task.model.trim() ? { initialModel: task.model.trim() } : {}),
-                    // BRAIN-ROUTING thinking axis: forward the task's thinking level (initialThinkingLevel).
-                    ...(typeof task.thinkingLevel === 'string' && task.thinkingLevel.trim() ? { initialThinkingLevel: task.thinkingLevel.trim() } : {}),
+                    // MAGI-KIND-PANEL model axis: local launch forwards the effective model
+                    // (task override, else matched slot) as initialModel (CLI → modelLaunchArgs; ACP → setConfigOption).
+                    ...(effectiveModel ? { initialModel: effectiveModel } : {}),
+                    // BRAIN-ROUTING thinking axis: forward the effective thinking level (initialThinkingLevel).
+                    ...(effectiveThinkingLevel ? { initialThinkingLevel: effectiveThinkingLevel } : {}),
                 });
                 if (!launchResult?.success) {
                     const reason = launchResult?.error || 'launch_cli_failed';
@@ -2161,7 +2345,10 @@ export async function triggerMeshQueue(components: DaemonComponents, meshId: str
                 const aPrio = resolveNodeSchedulingPriority(a.node?.policy);
                 const bPrio = resolveNodeSchedulingPriority(b.node?.policy);
                 if (aPrio !== bPrio) return bPrio - aPrio;
-                if (strategy === 'least_loaded' || strategy === 'round_robin') {
+                // The idle-session drain ranks task-independently (a session pulls
+                // whatever task matches), so 'fitness' here reduces to load-aware
+                // ordering — the same tiebreak as least_loaded/round_robin.
+                if (strategy === 'least_loaded' || strategy === 'round_robin' || strategy === 'fitness') {
                     const loadDelta = nodeActiveLoad(meshId, a.nodeId) - nodeActiveLoad(meshId, b.nodeId);
                     if (loadDelta !== 0) return loadDelta;
                 }

package/src/mesh/mesh-work-queue.ts

@@ -591,6 +591,15 @@ export interface MeshWorkQueueEntry {
      * setConfigOption('thought_level')). Rides in payload JSON. Best-effort like model.
      */
     thinkingLevel?: string;
+    /**
+     * SLOT-ROUTING (ORCHESTRATION_NODE_SLOTS.md): the coordinator's difficulty
+     * classification for this task ('easy'|'medium'|'difficult'|'freeform'),
+     * PERSISTED on the entry so the scheduler can match it against node capability
+     * slots at assignment time. Previously an enqueue-only option consumed to
+     * resolve model/thinkingLevel and then discarded; keeping it lets task→node
+     * fitness matching run. Absent on tasks enqueued without a difficulty.
+     */
+    difficulty?: string;
     /**
      * M1: why this task is held back (e.g. "dependency_failed:<taskId>").
      * Only set by the system on dependency failure under the 'block' policy;
@@ -904,6 +913,10 @@ export function enqueueTask(
     // an unconfigured preset just leaves the explicit values (or none) in place.
     let effectiveModel = typeof opts?.model === 'string' && opts.model.trim() ? opts.model.trim() : undefined;
     let effectiveThinkingLevel = typeof opts?.thinkingLevel === 'string' && opts.thinkingLevel.trim() ? opts.thinkingLevel.trim() : undefined;
+    // SLOT-ROUTING: persist the difficulty class on the entry so the scheduler can
+    // match it against node capability slots at assignment time (not just resolve
+    // model/thinking here). Absent/invalid → undefined (task carries no difficulty).
+    const taskDifficulty = isMeshTaskDifficulty(opts?.difficulty) ? (opts!.difficulty as MeshTaskDifficulty) : undefined;
     if (isMeshTaskDifficulty(opts?.difficulty)) {
         try {
             const preset = getDifficultyBrains()[opts!.difficulty as MeshTaskDifficulty];
@@ -951,6 +964,7 @@ export function enqueueTask(
             ...(typeof opts?.consensusGroupId === 'string' && opts.consensusGroupId.trim() ? { consensusGroupId: opts.consensusGroupId.trim() } : {}),
             ...(effectiveModel ? { model: effectiveModel } : {}),
             ...(effectiveThinkingLevel ? { thinkingLevel: effectiveThinkingLevel } : {}),
+            ...(taskDifficulty ? { difficulty: taskDifficulty } : {}),
             ...(typeof opts?.sourceCoordinatorSessionId === 'string' && opts.sourceCoordinatorSessionId.trim()
                 ? { sourceCoordinatorSessionId: opts.sourceCoordinatorSessionId.trim() }
                 : {}),

package/src/repo-mesh-types.ts

@@ -14,7 +14,7 @@
 import type { GitRepoStatus, GitCompactSummary } from './git/git-types.js';
 import type { MeshMissionSummary, MeshMissionSlimSummary } from './mesh/mesh-missions.js';
 import type { MeshMagiActivitySummary } from './mesh/mesh-magi-status.js';
-import type { MagiKindPanelMap, DifficultyBrainMap } from '@adhdev/mesh-shared';
+import type { MagiKindPanelMap, DifficultyBrainMap, NodeCapabilitySlot } from '@adhdev/mesh-shared';
 
 // ─── Core Mesh Types ────────────────────────────
 
@@ -139,13 +139,18 @@ export type RepoMeshSchedulingStrategy =
     | 'first_eligible'
     | 'least_loaded'
     | 'round_robin'
-    | 'priority_only';
+    | 'priority_only'
+    // ORCHESTRATION_NODE_SLOTS.md: rank nodes by task→capability-slot fitness
+    // (task difficulty/requiredTags vs the node's slots), then priority/load/order.
+    // Falls back to load ordering when no task is in scope (idle-session drain).
+    | 'fitness';
 
 export const MESH_SCHEDULING_STRATEGIES: RepoMeshSchedulingStrategy[] = [
     'first_eligible',
     'least_loaded',
     'round_robin',
     'priority_only',
+    'fitness',
 ];
 
 export const DEFAULT_MESH_SCHEDULING_STRATEGY: RepoMeshSchedulingStrategy = 'first_eligible';
@@ -403,8 +408,22 @@ export interface RepoMeshNodePolicy {
      * enforced as an additional, stricter-wins constraint on top of the global
      * maxParallelTasks/taskMode caps. Missing/empty: the node behaves exactly as
      * before (global caps only). Routing is governed solely by required_tags.
+     *
+     * SUPERSEDED by `slots` (ORCHESTRATION_NODE_SLOTS.md). Kept for back-compat:
+     * when `slots` is absent, providerRoles + providerPriority + the machine-global
+     * difficultyBrains are auto-derived into slots via deriveSlotsFromLegacy.
      */
     providerRoles?: RepoMeshProviderRole[];
+    /**
+     * Node capability slots (ORCHESTRATION_NODE_SLOTS.md) — the ordered "Preferred
+     * AI tools" profile that is the single source of truth for task routing, MAGI
+     * fan-out, and orchestrator-proposed edits. Each slot bundles provider + model
+     * + thinkingLevel + difficulty range + capability tags + per-slot maxParallel.
+     * Order = preference. When absent, the scheduler derives slots from the legacy
+     * providerPriority/providerRoles/difficultyBrains (deriveSlotsFromLegacy) so
+     * existing nodes keep working without reconfiguration.
+     */
+    slots?: NodeCapabilitySlot[];
     /**
      * Per-node override for RepoMeshPolicy.delegatedWorkerAutoApprove. When set, takes
      * precedence over the mesh-level policy for worker sessions launched onto this node.
@@ -440,7 +459,11 @@ export const DEFAULT_MESH_POLICY: RepoMeshPolicy = {
     allowAutoPublishSubmoduleMainCommits: false,
     requireApprovalForDestructiveGit: true,
     dirtyWorkspaceBehavior: 'warn',
-    maxParallelTasks: 2,
+    // Mesh-wide task cap is effectively unlimited by default: the real concurrency
+    // limits live per node / per capability slot (ORCHESTRATION_NODE_SLOTS.md), so a
+    // global ceiling is rarely meaningful. The UI hides this control; set it via the
+    // API only to impose a deliberate mesh-wide cap.
+    maxParallelTasks: 200,
     // Coordinator-spawned worker sessions default to hidden so the dashboard is not
     // flooded with mesh noise tabs/notifications. Users can still surface or unmute
     // any specific session manually; that override is preserved per-device.
@@ -1143,6 +1166,8 @@ export interface RepoMeshNodeStatus {
     activeSessions: string[];
     activeSessionDetails?: RepoMeshSessionStatus[];
     providerPriority?: string[];
+    /** Explicitly-configured node capability slots (ORCHESTRATION_NODE_SLOTS.md). */
+    slots?: NodeCapabilitySlot[];
     launchReady?: boolean;
     /** True when the node is clean, ahead=0, behind>0, and safe for fast-forward consideration. */
     autoFastForwardEligible?: boolean;

package/src/shared-types.ts

@@ -416,6 +416,13 @@ export interface SessionEntry {
     completionMarker?: string;
     seenCompletionMarker?: string;
     surfaceHidden?: boolean;
+    /**
+     * User (or coordinator-policy) muted: suppress attention side-effects
+     * (notifications, toasts, completion audio) for this session WITHOUT removing
+     * it from the inbox list. Distinct from surfaceHidden (which collapses it from
+     * the list). Daemon-owned, in-memory; rides the status snapshot.
+     */
+    muted?: boolean;
     settings?: Record<string, any>;
     /**
      * True owning-daemon id for a session a coordinator synthesises into its own
@@ -488,6 +495,7 @@ export interface CompactSessionEntry {
     completionMarker?: string;
     seenCompletionMarker?: string;
     surfaceHidden?: boolean;
+    muted?: boolean;
     controlValues?: Record<string, string | number | boolean>;
     providerControls?: ProviderControlSchema[];
     summaryMetadata?: ProviderSummaryMetadata;

package/src/status/builders.ts

@@ -34,6 +34,47 @@ import {
 } from '../providers/open-panel-support.js';
 import { TEXT_ONLY_MESSAGE_INPUT_SUPPORT } from '../providers/provider-input-support.js';
 
+/**
+ * A coordinator-spawned worker session that mesh policy launched hidden. This is
+ * the daemon-side equivalent of the web `shouldAutoHideMeshConversation` predicate:
+ * these sessions should default to muted+hidden in the user dashboard (the user
+ * interacts through the ONE coordinator session, not each worker), while the
+ * coordinator↔worker mesh data/completion path (mesh-event-forwarding) is
+ * unaffected.
+ */
+function isCoordinatorSpawnedHiddenWorker(settings: Record<string, any> | undefined): boolean {
+    if (!settings) return false;
+    return settings.launchedByCoordinator === true
+        && typeof settings.meshNodeFor === 'string'
+        && settings.meshNodeFor.trim().length > 0
+        && settings.spawnedSessionVisibility === 'hidden';
+}
+
+/**
+ * A session is surface-hidden (collapsed from the user's inbox/notifications) when
+ * mesh policy spawned it hidden, OR when a coordinator-spawned worker defaults
+ * hidden, OR when the user manually hid it (userHidden). userHidden === false is an
+ * explicit un-hide that overrides the policy/worker default until daemon restart.
+ */
+function resolveSurfaceHidden(settings: Record<string, any> | undefined): boolean {
+    if (!settings) return false;
+    if (settings.userHidden === true) return true;
+    if (settings.userHidden === false) return false;
+    return settings.spawnedSessionVisibility === 'hidden' || isCoordinatorSpawnedHiddenWorker(settings);
+}
+
+/**
+ * A session is muted (attention side-effects suppressed, but still shown in the
+ * list) when the user muted it, OR a coordinator-spawned worker defaults muted.
+ * userMuted === false is an explicit un-mute overriding the worker default.
+ */
+function resolveMuted(settings: Record<string, any> | undefined): boolean {
+    if (!settings) return false;
+    if (settings.userMuted === true) return true;
+    if (settings.userMuted === false) return false;
+    return isCoordinatorSpawnedHiddenWorker(settings);
+}
+
 export type SessionEntryProfile = 'full' | 'live' | 'metadata';
 
 export interface SessionEntryBuildOptions {
@@ -342,7 +383,8 @@ function buildCliSession(state: CliProviderState, options: SessionEntryBuildOpti
         settings: state.settings,
         ...(coordinator && { coordinator }),
         ...(meshQueueStats && { meshQueueStats }),
-        ...(state.settings?.spawnedSessionVisibility === 'hidden' && { surfaceHidden: true }),
+        ...(resolveSurfaceHidden(state.settings) && { surfaceHidden: true }),
+        ...(resolveMuted(state.settings) && { muted: true }),
     };
 }
 
@@ -384,7 +426,8 @@ function buildAcpSession(state: AcpProviderState, options: SessionEntryBuildOpti
         settings: state.settings,
         ...(coordinator && { coordinator }),
         ...(meshQueueStats && { meshQueueStats }),
-        ...(state.settings?.spawnedSessionVisibility === 'hidden' && { surfaceHidden: true }),
+        ...(resolveSurfaceHidden(state.settings) && { surfaceHidden: true }),
+        ...(resolveMuted(state.settings) && { muted: true }),
     };
 }
 

package/src/status/snapshot.ts

@@ -130,7 +130,7 @@ function buildDetectedIdeInfos(
         }));
 }
 
-function buildAvailableProviders(
+export function buildAvailableProviders(
     providerLoader: StatusSnapshotOptions['providerLoader'],
 ): AvailableProviderInfo[] {
     const providers: Array<{