@adhdev/daemon-core 0.9.82-rc.310 → 0.9.82-rc.311

package/src/config/mesh-config.ts

@@ -21,7 +21,7 @@ import type {
     RepoMeshHostMetadata,
     RepoMeshDaemonRole,
 } from '../repo-mesh-types.js';
-import { DEFAULT_MESH_POLICY } from '../repo-mesh-types.js';
+import { DEFAULT_MESH_POLICY, normalizeMeshSchedulingStrategy } from '../repo-mesh-types.js';
 import { createDefaultMeshHostMetadata } from '../mesh/mesh-host-ownership.js';
 
 // ─── Persistence ────────────────────────────────
@@ -118,6 +118,22 @@ function mergeMeshPolicy(base: RepoMeshPolicy | undefined, patch: Partial<RepoMe
     if (!SPAWNED_SESSION_VISIBILITY_MODES.has(String(policy.spawnedSessionVisibility))) {
         policy.spawnedSessionVisibility = 'visible';
     }
+    // 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;
 }
 

package/src/index.ts

@@ -131,8 +131,19 @@ export type {
   RepoMeshLedgerSummaryStatus,
   RepoMeshLedgerStatus,
   MeshAsyncJobLifecycle,
+  RepoMeshSchedulingStrategy,
+} from './repo-mesh-types.js';
+export {
+  DEFAULT_MESH_POLICY,
+  resolveDelegatedWorkerAutoApprove,
+  MESH_SCHEDULING_STRATEGIES,
+  DEFAULT_MESH_SCHEDULING_STRATEGY,
+  normalizeMeshSchedulingStrategy,
+  resolveNodeSchedulingPriority,
+  MESH_CONVERGE_REFINE_TAG,
+  MESH_CONVERGE_FAST_FORWARD_TAG,
+  resolveAutoConvergeCodeChange,
 } from './repo-mesh-types.js';
-export { DEFAULT_MESH_POLICY, resolveDelegatedWorkerAutoApprove } from './repo-mesh-types.js';
 
 // ── Git Surface ──
 export * from './git/index.js';
@@ -217,7 +228,7 @@ export { buildMeshLedgerReconciliationEvidence, buildMeshLedgerReplicaEvidence }
 export type { AnyLedgerSlice, MeshLedgerReconciliationEvidence, MeshLedgerReplicaEvidence, MeshLedgerReplicaStatus } from './mesh/mesh-ledger-reconciliation.js';
 
 // ── Mesh Work Queue (GUPP) ──
-export { enqueueTask, recordDirectDispatchTask, getQueue, claimNextTask, updateTaskStatus, updateSessionTaskStatus, cancelTask, requeueTask, getMeshQueueStats, getMeshQueueRevision, normalizeMeshTaskMode, validateMeshTaskModeRequest, buildMeshNodeCapabilityTags, nodeSatisfiesRequiredTags, normalizeMeshCapabilityTags, insertDirectDispatch, getActiveDirectDispatches, updateDirectDispatchStatus, cleanupTerminalDirectDispatches, markStaleDirectDispatches, deleteDirectDispatchesByTaskId, recordMeshToolCall, assertNoDependencyCycle, hasPendingDependents, describeTaskDependencyState } from './mesh/mesh-work-queue.js';
+export { enqueueTask, recordDirectDispatchTask, getQueue, claimNextTask, updateTaskStatus, updateSessionTaskStatus, cancelTask, requeueTask, getMeshQueueStats, getMeshQueueRevision, normalizeMeshTaskMode, validateMeshTaskModeRequest, buildMeshNodeCapabilityTags, nodeSatisfiesRequiredTags, normalizeMeshCapabilityTags, resolveConvergeRequiredTags, insertDirectDispatch, getActiveDirectDispatches, updateDirectDispatchStatus, cleanupTerminalDirectDispatches, markStaleDirectDispatches, deleteDirectDispatchesByTaskId, recordMeshToolCall, assertNoDependencyCycle, hasPendingDependents, describeTaskDependencyState } from './mesh/mesh-work-queue.js';
 export type { MeshWorkQueueEntry, MeshTaskStatus, MeshTaskMode, MeshWorkQueueStats, MeshQueueMutationOptions, MeshTaskModeValidationResult, DirectDispatchRecord, MeshToolCallRateResult } from './mesh/mesh-work-queue.js';
 export { buildCompactStaleDirectWorkSummary, buildMeshActiveWork, buildMeshActiveWorkSummary, classifyStaleDirectForPrune, PRUNABLE_ORPHAN_STALE_REASONS } from './mesh/mesh-active-work.js';
 export type { StaleDirectPruneClassification } from './mesh/mesh-active-work.js';

package/src/mesh/mesh-events-coordinator.ts

@@ -14,7 +14,8 @@ import { queuePendingMeshCoordinatorEvent, drainPendingMeshCoordinatorEvents } f
 import type { PendingMeshCoordinatorEvent } from './mesh-events-pending.js';
 import { resolveWorkerDelegateRouting, recordUnroutableDelegateEvent, isUnroutableDelegateRejection } from './mesh-routing.js';
 import { enqueueUnresolvedDelegateForward, peekUnresolvedDelegateForwards, ackUnresolvedDelegateForward } from './mesh-unresolved-forward-outbox.js';
-import { resolveDelegatedWorkerAutoApprove, resolveProviderMaxParallel } from '../repo-mesh-types.js';
+import { resolveDelegatedWorkerAutoApprove, resolveProviderMaxParallel, resolveNodeSchedulingPriority, normalizeMeshSchedulingStrategy } from '../repo-mesh-types.js';
+import type { RepoMeshSchedulingStrategy } from '../repo-mesh-types.js';
 import { normalizeMeshNodeId, meshNodeIdMatches, type MeshNodeIdentified } from '@adhdev/mesh-shared';
 import {
     findRecentTerminalLedgerEvidence,
@@ -499,6 +500,91 @@ function nodeHasActiveAssignment(meshId: string, nodeId: string): boolean {
     return getQueue(meshId, { status: ['assigned'] as any }).some(task => task.assignedNodeId === nodeId);
 }
 
+/** Active (status='assigned') task count for a node — the load metric for
+ *  least-loaded / round-robin ranking. Lower = preferred. */
+function nodeActiveLoad(meshId: string, nodeId: string): number {
+    return MeshRuntimeStore.getInstance().nodeActiveAssignmentCount(meshId, nodeId);
+}
+
+/**
+ * The mesh-wide scheduling strategy. Defaults to 'first_eligible' (strict
+ * no-change) for any mesh that does not set it. Only governs the final tie-break;
+ * eligibility, capacity, and priority gates apply identically to every strategy.
+ */
+function resolveSchedulingStrategy(mesh: any): RepoMeshSchedulingStrategy {
+    return normalizeMeshSchedulingStrategy(mesh?.policy?.schedulingStrategy);
+}
+
+/**
+ * Order eligible nodes for assignment per the mesh scheduling pipeline:
+ *   PRIORITY (schedulingPriority desc) → TIE-BREAK (strategy).
+ *
+ * The caller has already applied the TAG hard-filter and is responsible for the
+ * MAX-ALLOC capacity gate (the per-node launch/claim checks). This function only
+ * decides the *preference order* among nodes that are otherwise eligible.
+ *
+ * - 'first_eligible' (default): returns the input order verbatim and does NOT touch
+ *   the round-robin cursor — byte-for-byte the pre-feature behavior.
+ * - 'priority_only': schedulingPriority desc, then input order (load ignored).
+ * - 'least_loaded': schedulingPriority desc, then active load asc, then input order.
+ * - 'round_robin': same as least_loaded, but among nodes tied at (priority, load)
+ *   the input order is rotated by a per-mesh cursor that advances once per pass.
+ *
+ * `nodes` carries the original config/array index so the tie-break can fall back to
+ * deterministic input order. `bumpCursor` advances the round-robin cursor exactly
+ * once per scheduling pass (only consulted for 'round_robin').
+ */
+interface RankableNode { nodeId: string; node: any; index: number }
+
+/** Test-only: the pure node-ordering stage (PRIORITY → TIE-BREAK). Exposed so the
+ *  scheduling pipeline can be unit-tested without standing up live CLI sessions. */
+export function __orderEligibleNodesForTests(
+    meshId: string,
+    strategy: RepoMeshSchedulingStrategy,
+    nodes: RankableNode[],
+    opts?: { bumpCursor?: boolean },
+): RankableNode[] {
+    return orderEligibleNodes(meshId, strategy, nodes, opts);
+}
+
+function orderEligibleNodes(
+    meshId: string,
+    strategy: RepoMeshSchedulingStrategy,
+    nodes: RankableNode[],
+    opts?: { bumpCursor?: boolean },
+): RankableNode[] {
+    if (strategy === 'first_eligible' || nodes.length <= 1) {
+        return nodes;
+    }
+
+    const priorityOf = (n: { node: any }) => resolveNodeSchedulingPriority(n.node?.policy);
+
+    // Round-robin rotation offset: rotate the deterministic input order by a
+    // per-mesh cursor so the tie-break winner among equal (priority, load) nodes
+    // cycles across passes. The cursor advances once per scheduling pass.
+    let rotation = 0;
+    if (strategy === 'round_robin') {
+        const cursor = opts?.bumpCursor
+            ? MeshRuntimeStore.getInstance().bumpSchedulerCursor(meshId)
+            : MeshRuntimeStore.getInstance().getSchedulerCursor(meshId);
+        rotation = ((cursor % nodes.length) + nodes.length) % nodes.length;
+    }
+
+    // Rotation rank: position of each node after rotating input order by `rotation`.
+    // For non-round-robin strategies rotation is 0, so this is just the input index.
+    const rotationRank = (index: number) => (index - rotation + nodes.length) % nodes.length;
+
+    return [...nodes].sort((a, b) => {
+        const prioDelta = priorityOf(b) - priorityOf(a); // higher priority first
+        if (prioDelta !== 0) return prioDelta;
+        if (strategy === 'least_loaded' || strategy === 'round_robin') {
+            const loadDelta = nodeActiveLoad(meshId, a.nodeId) - nodeActiveLoad(meshId, b.nodeId);
+            if (loadDelta !== 0) return loadDelta;
+        }
+        return rotationRank(a.index) - rotationRank(b.index);
+    });
+}
+
 /** Active assignments on a (node, provider) — pre-launch guard for the per-(node,
  *  provider) maxParallel cap. The authoritative enforcement is in the claim
  *  transaction; this only avoids spawning a session that would fail the claim. */
@@ -700,7 +786,25 @@ async function maybeAutoLaunchOneQueueSession(components: DaemonComponents, mesh
             continue;
         }
 
-        for (const node of candidateNodes) {
+        // PRIORITY → TIE-BREAK: order the eligible (TAG-filtered) candidate nodes by
+        // the mesh scheduling strategy. 'first_eligible' (default) returns them in
+        // config/array order unchanged, so distribution is strictly opt-in. The
+        // per-node MAX-ALLOC capacity gate (nodeHasActiveAssignment, provider cap,
+        // maxConcurrentSessions) is still applied inside the loop below; this only
+        // chooses which eligible node is *tried first*.
+        const strategy = resolveSchedulingStrategy(mesh);
+        const orderedCandidateNodes = strategy === 'first_eligible'
+            ? candidateNodes
+            : orderEligibleNodes(
+                meshId,
+                strategy,
+                candidateNodes
+                    .map((node: any, index: number) => ({ nodeId: readMeshNodeId(node), node, index }))
+                    .filter((c: RankableNode) => c.nodeId),
+                { bumpCursor: true },
+            ).map((c: RankableNode) => c.node);
+
+        for (const node of orderedCandidateNodes) {
             const nodeId = readMeshNodeId(node);
             if (!nodeId) continue;
             const launchKey = `${meshId}:${nodeId}`;
@@ -866,6 +970,19 @@ export async function triggerMeshQueue(components: DaemonComponents, meshId: str
         };
     }
 
+    // Collect every idle mesh session (local CLI instances + remote idle records)
+    // as drain candidates. The drain ORDER depends on the scheduling strategy:
+    //   - 'first_eligible' (default): local-first, then remote, exactly as before.
+    //   - otherwise: local + remote merged into one pool and drained in scheduling
+    //     order (priority → load → tie-break). This local-first debias is required
+    //     because without it the coordinator's own local node is always visited
+    //     first and greedily absorbs all untargeted work before any remote idle
+    //     session is even considered — the comparator alone can't spread work if
+    //     local is always tried first.
+    type IdleCandidate = { nodeId: string; sessionId: string; providerType: string; origin: 'local' | 'remote'; node: any };
+    const strategy = resolveSchedulingStrategy(mesh);
+    const localCandidates: IdleCandidate[] = [];
+
     const cliInstances = components.instanceManager.getByCategory('cli');
     for (const inst of cliInstances) {
         const state = inst.getState();
@@ -893,7 +1010,7 @@ export async function triggerMeshQueue(components: DaemonComponents, meshId: str
 
         if (providerType) {
             localIdleSessionsChecked += 1;
-            tryAssignQueueTask(components, meshId, nodeId, sessionId, providerType);
+            localCandidates.push({ nodeId, sessionId, providerType, origin: 'local', node: mesh.nodes.find((n: any) => readMeshNodeId(n) === nodeId) });
         } else {
             skippedSessions.push({
                 nodeId,
@@ -908,16 +1025,55 @@ export async function triggerMeshQueue(components: DaemonComponents, meshId: str
         remoteSessions = MeshRuntimeStore.getInstance().getRemoteIdleSessions();
     } catch { /* best-effort */ }
 
+    const remoteCandidates: IdleCandidate[] = [];
     for (const idle of remoteSessions) {
         const node = mesh.nodes.find((n: any) => n.id === idle.nodeId);
         if (node) {
             remoteIdleSessionsChecked += 1;
-            const assigned = tryAssignQueueTask(components, meshId, idle.nodeId, idle.sessionId, idle.providerType);
-            if (assigned) {
-                try {
-                    MeshRuntimeStore.getInstance().deleteRemoteIdleSession(idle.nodeId, idle.sessionId);
-                } catch { /* best-effort */ }
-            }
+            remoteCandidates.push({ nodeId: idle.nodeId, sessionId: idle.sessionId, providerType: idle.providerType, origin: 'remote', node });
+        }
+    }
+
+    const assignIdleCandidate = (candidate: IdleCandidate): void => {
+        const assigned = tryAssignQueueTask(components, meshId, candidate.nodeId, candidate.sessionId, candidate.providerType);
+        if (assigned && candidate.origin === 'remote') {
+            try {
+                MeshRuntimeStore.getInstance().deleteRemoteIdleSession(candidate.nodeId, candidate.sessionId);
+            } catch { /* best-effort */ }
+        }
+    };
+
+    if (strategy === 'first_eligible') {
+        // Strict no-change: drain local idle sessions first (original order), then
+        // remote idle sessions. tryAssignQueueTask is a no-op when nothing matches.
+        for (const candidate of localCandidates) assignIdleCandidate(candidate);
+        for (const candidate of remoteCandidates) assignIdleCandidate(candidate);
+    } else {
+        // Merge local + remote into one pool and drain in scheduling order. Each
+        // assignment mutates a node's active load, and the next pick re-reads it,
+        // so re-ranking after every assignment keeps the spread fair as load shifts.
+        const pool = [...localCandidates, ...remoteCandidates];
+        const baseIndex = new Map<string, number>();
+        pool.forEach((c, i) => { if (!baseIndex.has(c.nodeId)) baseIndex.set(c.nodeId, i); });
+        // Bump the round-robin cursor once for this whole drain pass.
+        const uniqueNodes = [...new Set(pool.map(c => c.nodeId))]
+            .map((nodeId, index) => ({ nodeId, node: pool.find(c => c.nodeId === nodeId)?.node, index }));
+        const ranked = orderEligibleNodes(meshId, strategy, uniqueNodes, { bumpCursor: true });
+        const rankIndex = new Map<string, number>(ranked.map((r, i) => [r.nodeId, i]));
+        const remaining = [...pool];
+        while (remaining.length > 0) {
+            // Re-rank each pass so a node that just took work defers its next session.
+            remaining.sort((a, b) => {
+                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') {
+                    const loadDelta = nodeActiveLoad(meshId, a.nodeId) - nodeActiveLoad(meshId, b.nodeId);
+                    if (loadDelta !== 0) return loadDelta;
+                }
+                return (rankIndex.get(a.nodeId) ?? 0) - (rankIndex.get(b.nodeId) ?? 0);
+            });
+            assignIdleCandidate(remaining.shift()!);
         }
     }
 

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

@@ -268,6 +268,17 @@ export class MeshRuntimeStore {
 
             CREATE INDEX IF NOT EXISTS idx_mesh_missions_mesh_status
                 ON mesh_missions(mesh_id, status, updated_at);
+
+            -- Load-balancing scheduler: per-mesh round-robin rotation cursor. When
+            -- the schedulingStrategy is 'round_robin', several eligible nodes tied at
+            -- the least load are rotated by this cursor so the tie-break winner cycles
+            -- across scheduling passes instead of always favouring the same array-order
+            -- node. Persisted (not a module Map) so rotation survives daemon restarts
+            -- and stays a single source of truth across scheduling entry points.
+            CREATE TABLE IF NOT EXISTS mesh_scheduler_cursor (
+                mesh_id TEXT PRIMARY KEY,
+                cursor INTEGER NOT NULL DEFAULT 0
+            );
         `);
     }
 
@@ -479,6 +490,47 @@ export class MeshRuntimeStore {
         return row !== undefined;
     }
 
+    /**
+     * 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 {
+        const row = this.db.prepare(`
+            SELECT COUNT(*) as count FROM mesh_queue
+            WHERE mesh_id = ? AND status = 'assigned' AND assigned_node_id = ?
+        `).get(meshId, nodeId) as { count: number } | undefined;
+        return row?.count ?? 0;
+    }
+
+    /**
+     * 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 {
+        const row = this.db.prepare(
+            'SELECT cursor FROM mesh_scheduler_cursor WHERE mesh_id = ?'
+        ).get(meshId) as { cursor: number } | undefined;
+        return row?.cursor ?? 0;
+    }
+
+    /**
+     * 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 {
+        return this.transaction(() => {
+            const current = this.getSchedulerCursor(meshId);
+            this.db.prepare(`
+                INSERT INTO mesh_scheduler_cursor (mesh_id, cursor) VALUES (?, ?)
+                ON CONFLICT(mesh_id) DO UPDATE SET cursor = excluded.cursor
+            `).run(meshId, current + 1);
+            return current;
+        });
+    }
+
     /**
      * Count active (status='assigned') tasks on a (node, provider) combination,
      * matched by the assignedProviderType stamped on the payload at claim time.

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

@@ -1,6 +1,7 @@
 import { randomUUID } from 'crypto';
 import { requireMeshHostQueueOwner } from './mesh-host-ownership.js';
 import type { RepoMeshDaemonRole } from '../repo-mesh-types.js';
+import { MESH_CONVERGE_REFINE_TAG, resolveAutoConvergeCodeChange } from '../repo-mesh-types.js';
 import { MeshRuntimeStore } from './mesh-runtime-store.js';
 import { getMesh } from '../config/mesh-config.js';
 
@@ -203,6 +204,45 @@ function firstProviderPriority(policy: unknown): string | undefined {
     return raw.find(type => typeof type === 'string' && type.trim())?.trim();
 }
 
+/**
+ * Synthetic `role=<x>` capability tags advertised by a node's policy.providerRoles.
+ *
+ * When a specific `providerType` is being evaluated, only that provider's declared
+ * role is emitted — so role-based routing (requiredTags: ["role=validation"]) gates
+ * the *selected* provider through the ordinary capability-tag filter. When no
+ * provider is selected (node-level eligibility scan), every declared role is emitted
+ * so the node passes the filter if ANY of its providers could satisfy the role; the
+ * per-provider tag set then narrows it during provider selection.
+ *
+ * Roles are lowercased and deduped. Missing/empty providerRoles emits nothing, so a
+ * node that never declares roles advertises no `role=` tags and is therefore only
+ * matched by role-unconstrained tasks (full backward compatibility).
+ */
+function roleCapabilityTags(policy: unknown, providerType: string | undefined): string[] {
+    const roles = policy && typeof policy === 'object' && !Array.isArray(policy)
+        ? (policy as Record<string, unknown>).providerRoles
+        : undefined;
+    if (!Array.isArray(roles)) return [];
+    const wantedProvider = typeof providerType === 'string' && providerType.trim()
+        ? providerType.trim().toLowerCase()
+        : '';
+    const out: string[] = [];
+    for (const entry of roles) {
+        if (!entry || typeof entry !== 'object') continue;
+        const type = typeof (entry as any).providerType === 'string'
+            ? (entry as any).providerType.trim().toLowerCase()
+            : '';
+        const role = typeof (entry as any).role === 'string'
+            ? (entry as any).role.trim().toLowerCase()
+            : '';
+        if (!role) continue;
+        // When narrowing to a selected provider, only emit that provider's role.
+        if (wantedProvider && type && type !== wantedProvider) continue;
+        out.push(`role=${role}`);
+    }
+    return out;
+}
+
 export function buildMeshNodeCapabilityTags(
     node: { capabilities?: unknown; policy?: unknown; isLocalWorktree?: unknown; worktreeBranch?: unknown } | undefined,
     providerType?: string,
@@ -222,6 +262,24 @@ export function buildMeshNodeCapabilityTags(
         // mesh_enqueue_task with required_tags: ["worktree=<branch>"] routes
         // only to the matching worktree node.
         ...(node?.isLocalWorktree === true && worktreeBranch ? [`worktree=${worktreeBranch}`] : []),
+        // Convergence routing: advertise how this node can land its work onto base.
+        //   - converge=refine: local worktree nodes (on ANY machine — refine_mesh_node
+        //     now forwards to the owning daemon) can run the Refinery merge → push →
+        //     cleanup against their own checkout, so they accept code_change tasks.
+        //   - converge=fast_forward: non-worktree nodes (the machine itself) can only
+        //     ff/push an already-converged branch; they are NOT a destination for
+        //     code_change work (a worktree is created first, and that worktree node
+        //     receives the task instead). Reuses the ordinary required-tags filter —
+        //     the load-balancing scheduler auto-injects converge=refine for code_change
+        //     so such work is hard-filtered onto refine-capable nodes.
+        ...(node?.isLocalWorktree === true ? ['converge=refine'] : ['converge=fast_forward']),
+        // Role-based routing: advertise role=<x> for each (node, provider) role
+        // declared in policy.providerRoles. Narrowed to the selected provider when
+        // one is given so the chosen provider must match a task's required role;
+        // when no provider is selected, all declared roles are advertised for the
+        // node-level eligibility scan. Reuses the ordinary required-tags filter —
+        // no separate role field/gate.
+        ...roleCapabilityTags(node?.policy, providerType),
     ]);
 }
 
@@ -232,6 +290,44 @@ export function nodeSatisfiesRequiredTags(requiredTags: unknown, capabilityTags:
     return required.every(tag => available.has(tag));
 }
 
+/**
+ * Convergence-aware required-tags resolution (load-balancing scheduler, opt-in).
+ *
+ * When the mesh enables policy.autoConvergeCodeChange, a `converge=refine` required
+ * tag is merged into a code_change task's required tags at enqueue time, so the
+ * scheduler hard-filters the task onto refine-capable worktree nodes only (on any
+ * machine — refine_mesh_node forwards to the owning daemon). Because the tag is
+ * persisted on the queue entry, BOTH the eligibility scan (maybeAutoLaunchOneQueueSession)
+ * and the claim transaction (claimNextQueueTask → nodeSatisfiesRequiredTags) enforce
+ * it consistently.
+ *
+ * Strict backward compatibility — the injection is skipped (returns the explicit tags
+ * unchanged) when ANY of:
+ *   - the mesh does not opt in (autoConvergeCodeChange !== true), or
+ *   - the task is not code_change (validation / live_debug_readonly / launch_app /
+ *     convergence carry no merge cost and may run anywhere), or
+ *   - the task is explicitly targeted (targetNodeId): the operator chose the node, so
+ *     we do not second-guess it by filtering on convergence capability.
+ * Idempotent: normalizeMeshCapabilityTags dedupes, so re-injection is a no-op.
+ */
+export function resolveConvergeRequiredTags(
+    meshId: string,
+    taskMode: MeshTaskMode | undefined,
+    explicitRequiredTags: string[],
+    opts?: { targetNodeId?: string },
+): string[] {
+    if (taskMode !== 'code_change') return explicitRequiredTags;
+    if (typeof opts?.targetNodeId === 'string' && opts.targetNodeId.trim()) return explicitRequiredTags;
+    let optedIn = false;
+    try {
+        optedIn = resolveAutoConvergeCodeChange(getMesh(meshId)?.policy as any);
+    } catch {
+        optedIn = false;
+    }
+    if (!optedIn) return explicitRequiredTags;
+    return normalizeMeshCapabilityTags([...explicitRequiredTags, MESH_CONVERGE_REFINE_TAG]);
+}
+
 function withQueueLock<T>(_meshId: string, fn: () => T): T {
     return MeshRuntimeStore.getInstance().transaction(fn);
 }
@@ -325,7 +421,15 @@ export function enqueueTask(
             taskMode: modeValidation.taskMode,
             targetNodeId: opts?.targetNodeId,
             targetSessionId: opts?.targetSessionId,
-            requiredTags: normalizeMeshCapabilityTags(opts?.requiredTags),
+            // Convergence routing (opt-in): auto-inject converge=refine for code_change
+            // tasks so they hard-filter onto refine-capable worktree nodes. No-op unless
+            // the mesh opts in; explicit target_node_id / required_tags are preserved.
+            requiredTags: resolveConvergeRequiredTags(
+                meshId,
+                modeValidation.taskMode,
+                normalizeMeshCapabilityTags(opts?.requiredTags),
+                { targetNodeId: opts?.targetNodeId },
+            ),
             ...(dependsOn.length > 0 ? { dependsOn } : {}),
             ...(typeof opts?.missionId === 'string' && opts.missionId.trim() ? { missionId: opts.missionId.trim() } : {}),
             createdAt: new Date().toISOString(),