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

package/src/logging/log-redactor.ts

@@ -0,0 +1,100 @@
+/**
+ * Log redactor — mask secrets before a raw daemon log line leaves the machine.
+ *
+ * Daemon logs can incidentally contain credentials: ADHDev API keys (adk_*),
+ * machine secrets (adm_*), provider keys (adp_*), bearer tokens, JWTs, TURN
+ * `username:credential` pairs, and `SECRET=...` style env dumps. The mesh
+ * `get_mesh_node_logs` command ships a log tail over P2P to the coordinator, so
+ * every line MUST pass through redactLogLine() first — otherwise a secret in a
+ * remote daemon's log is exfiltrated to whoever is driving the coordinator.
+ *
+ * Patterns are intentionally conservative: each masks the secret material while
+ * preserving enough surrounding shape that the line stays useful for debugging
+ * (e.g. `adk_••••1234`, `Bearer ••••redacted`). When in doubt, mask.
+ */
+
+const MASK = '••••redacted';
+
+/** Keep the last 4 chars of a token so logs stay correlatable without leaking it. */
+function maskKeepTail(token: string): string {
+    if (token.length <= 8) return MASK;
+    return `${MASK}${token.slice(-4)}`;
+}
+
+interface RedactionRule {
+    readonly name: string;
+    readonly pattern: RegExp;
+    readonly replace: (match: string, ...groups: string[]) => string;
+}
+
+// NOTE: order matters — more specific rules (key=value, Bearer, TURN) run before
+// the bare-token rules so the structured forms aren't half-masked by a greedy
+// generic rule.
+const RULES: RedactionRule[] = [
+    // `JWT_SECRET=...`, `TOKEN=...`, `API_KEY=...`, `password: ...` env/config dumps.
+    // Captures the key + delimiter and masks only the value.
+    {
+        name: 'key_value_secret',
+        pattern: /\b([A-Z0-9_]*(?:SECRET|TOKEN|API[_-]?KEY|PASSWORD|PASSWD|PRIVATE[_-]?KEY|CREDENTIAL|CLIENT[_-]?SECRET)[A-Z0-9_]*)(\s*[:=]\s*)(["']?)([^\s"',;]+)\3/gi,
+        replace: (_m, key: string, delim: string, quote: string) => `${key}${delim}${quote}${MASK}${quote}`,
+    },
+    // Authorization: Bearer <token>
+    {
+        name: 'bearer_token',
+        pattern: /\b(Bearer\s+)([A-Za-z0-9._\-+/=]{8,})/g,
+        replace: (_m, prefix: string, token: string) => `${prefix}${maskKeepTail(token)}`,
+    },
+    // ADHDev credential prefixes: API key (adk_), machine secret (adm_), provider key (adp_).
+    {
+        name: 'adhdev_prefixed_secret',
+        pattern: /\b(ad[kmp]_)([A-Za-z0-9]{6,})/g,
+        replace: (_m, prefix: string, token: string) => `${prefix}${maskKeepTail(prefix + token)}`,
+    },
+    // JWT: three base64url segments separated by dots, header starts with eyJ.
+    {
+        name: 'jwt',
+        pattern: /\beyJ[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]{4,}/g,
+        replace: () => MASK,
+    },
+    // TURN credential: a long credential value following a `credential` key in
+    // any common shape — `credential: x`, `credential=x`, or `credential "x"`.
+    // Mask the credential value only, preserving the key + delimiter/quote.
+    {
+        name: 'turn_credential',
+        pattern: /\b(credential["']?\s*(?:[:=]\s*)?["']?)([^\s"',;]{6,})/gi,
+        replace: (_m, prefix: string) => `${prefix}${MASK}`,
+    },
+    // TURN REST username:credential of the form `<expiry-ts>:<base64hmac>`,
+    // where the hmac part is long base64. Mask the hmac.
+    {
+        name: 'turn_rest_pair',
+        pattern: /\b(\d{10,}:)([A-Za-z0-9+/]{20,}={0,2})\b/g,
+        replace: (_m, prefix: string) => `${prefix}${MASK}`,
+    },
+];
+
+/**
+ * Mask secrets in a single log line. Idempotent-ish: re-running over an
+ * already-masked line leaves the MASK token in place (it contains no secret
+ * shape). Never throws — a redaction failure must not crash the log path.
+ */
+export function redactLogLine(line: string): string {
+    if (!line) return line;
+    let out = line;
+    for (const rule of RULES) {
+        try {
+            out = out.replace(rule.pattern, rule.replace as (substring: string, ...args: any[]) => string);
+        } catch {
+            // A pathological line must never break log shipping — skip this rule.
+        }
+    }
+    return out;
+}
+
+/** Redact an array of log lines in place-safe fashion (returns a new array). */
+export function redactLogLines(lines: string[]): string[] {
+    return lines.map((line) => redactLogLine(line));
+}
+
+/** Exposed for tests/introspection: the rule names applied, in order. */
+export const LOG_REDACTION_RULE_NAMES: readonly string[] = RULES.map((r) => r.name);

package/src/logging/log-tail-reader.ts

@@ -0,0 +1,220 @@
+/**
+ * Daemon log tail reader — read the last N bytes of a daemon log file, newest
+ * bytes first, bounded so the result is safe to ship over a mesh P2P channel.
+ *
+ * Used by the mesh `get_mesh_node_logs` command: the coordinator asks a (possibly
+ * remote) daemon for its recent log tail instead of having to open a session and
+ * grep the file by hand. Because the mesh RPC envelope is sent as a single
+ * datachannel message (~256KB SCTP ceiling, no chunking), the returned tail is
+ * HARD-bounded by `tailBytes` (default 64KB, capped at MAX_TAIL_BYTES=128KB) and
+ * flags `truncated:true` when the file was larger.
+ *
+ * Boundary-safe: lines are cut on the newline byte (0x0A) only, which never
+ * appears inside a multibyte UTF-8 sequence, so decoding each complete byte
+ * segment never splits a multibyte char.
+ */
+
+import * as fs from 'fs';
+import { getCurrentDaemonLogPath, getDaemonLogDir } from './logger.js';
+
+export const DEFAULT_TAIL_BYTES = 64 * 1024;
+export const MAX_TAIL_BYTES = 128 * 1024;
+const READ_CHUNK_BYTES = 64 * 1024;
+
+export interface ReadDaemonLogTailArgs {
+    /** Date of the log file to read (defaults to today). YYYY-MM-DD string or Date. */
+    date?: string | Date;
+    /** Max bytes of tail to return. Clamped to (0, MAX_TAIL_BYTES]. Default 64KB. */
+    tailBytes?: number;
+    /** Optional regex source string; only lines matching (case-insensitive) are kept. */
+    grep?: string;
+    /** Optional epoch-ms floor; only lines whose leading [HH:MM:SS...] / ISO ts >= this are kept. */
+    sinceMs?: number;
+}
+
+export interface DaemonLogTailResult {
+    success: boolean;
+    error?: string;
+    lines: string[];
+    truncated: boolean;
+    logPath: string;
+    platform: NodeJS.Platform;
+    bytesReturned: number;
+    /** True when a grep/since filter dropped lines from the raw tail window. */
+    filtered: boolean;
+    /** The grep source actually applied (echoed back for clarity). */
+    grep?: string;
+}
+
+function resolveLogPath(date?: string | Date): string {
+    if (date instanceof Date) return getCurrentDaemonLogPath(date);
+    if (typeof date === 'string' && date.trim()) {
+        const parsed = new Date(`${date.trim()}T00:00:00.000Z`);
+        if (!Number.isNaN(parsed.getTime())) return getCurrentDaemonLogPath(parsed);
+    }
+    return getCurrentDaemonLogPath();
+}
+
+function clampTailBytes(tailBytes?: number): number {
+    if (!Number.isFinite(tailBytes) || (tailBytes as number) <= 0) return DEFAULT_TAIL_BYTES;
+    return Math.min(Math.floor(tailBytes as number), MAX_TAIL_BYTES);
+}
+
+/**
+ * Read up to `limitBytes` from the end of `filePath`, on a UTF-8 line boundary.
+ * Returns the decoded text, whether the read was truncated (file bigger than the
+ * window), and the number of bytes actually decoded.
+ */
+function readByteBoundedTail(filePath: string, limitBytes: number): { text: string; truncated: boolean; bytesReturned: number } {
+    const fd = fs.openSync(filePath, 'r');
+    try {
+        const stat = fs.fstatSync(fd);
+        const size = stat.size;
+        if (size === 0) return { text: '', truncated: false, bytesReturned: 0 };
+
+        const want = Math.min(limitBytes, size);
+        let start = size - want;
+        const truncated = start > 0;
+
+        // Collect chunks newest-last into a buffer covering [start, size).
+        const buffers: Buffer[] = [];
+        let position = start;
+        while (position < size) {
+            const chunkSize = Math.min(READ_CHUNK_BYTES, size - position);
+            const chunk = Buffer.alloc(chunkSize);
+            fs.readSync(fd, chunk, 0, chunkSize, position);
+            buffers.push(chunk);
+            position += chunkSize;
+        }
+        let buf = Buffer.concat(buffers);
+
+        // If we truncated mid-line, drop the leading partial line so we never emit
+        // a half-decoded line (and never split a multibyte char at the window edge).
+        if (truncated) {
+            const firstNewline = buf.indexOf(0x0a);
+            if (firstNewline >= 0) {
+                buf = buf.subarray(firstNewline + 1);
+            }
+        }
+        return { text: buf.toString('utf-8'), truncated, bytesReturned: buf.length };
+    } finally {
+        fs.closeSync(fd);
+    }
+}
+
+// Parse a leading timestamp from a log line into epoch ms. The unified logger
+// writes `[HH:MM:SS.mmm]` (local time, today's date) and the startup banner uses
+// a full timestamp; we best-effort parse `[HH:MM:SS...]` against the file's date.
+// Returns null when no timestamp can be extracted (line is then kept by sinceMs).
+function parseLineEpochMs(line: string, fileDate: Date): number | null {
+    const m = line.match(/^\[(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,3}))?\]/);
+    if (!m) {
+        // Try an embedded ISO timestamp as a fallback.
+        const iso = line.match(/\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:\.\d+)?/);
+        if (iso) {
+            const t = Date.parse(iso[0].replace(' ', 'T'));
+            return Number.isNaN(t) ? null : t;
+        }
+        return null;
+    }
+    const d = new Date(fileDate);
+    d.setHours(Number(m[1]), Number(m[2]), Number(m[3]), m[4] ? Number(m[4].padEnd(3, '0')) : 0);
+    return d.getTime();
+}
+
+/**
+ * Read the daemon log tail for `date` (default today), bounded to `tailBytes`,
+ * with optional grep (regex source) and sinceMs filters. Falls back to the
+ * size-rotation backup (`*.1.log`) when the primary file does not exist.
+ */
+export function readDaemonLogTail(args: ReadDaemonLogTailArgs = {}): DaemonLogTailResult {
+    const platform = process.platform;
+    const limitBytes = clampTailBytes(args.tailBytes);
+    let logPath = resolveLogPath(args.date);
+
+    // Fall back to the size-rotation backup if the active file is absent.
+    if (!fs.existsSync(logPath)) {
+        const backup = logPath.replace(/\.log$/, '.1.log');
+        if (fs.existsSync(backup)) {
+            logPath = backup;
+        } else {
+            return {
+                success: false,
+                error: `No daemon log file at ${logPath} (dir: ${getDaemonLogDir()})`,
+                lines: [],
+                truncated: false,
+                logPath,
+                platform,
+                bytesReturned: 0,
+                filtered: false,
+            };
+        }
+    }
+
+    let raw: { text: string; truncated: boolean; bytesReturned: number };
+    try {
+        raw = readByteBoundedTail(logPath, limitBytes);
+    } catch (e: any) {
+        return {
+            success: false,
+            error: `Failed to read ${logPath}: ${e?.message ?? String(e)}`,
+            lines: [],
+            truncated: false,
+            logPath,
+            platform,
+            bytesReturned: 0,
+            filtered: false,
+        };
+    }
+
+    let lines = raw.text.split('\n');
+    // A trailing newline yields a final empty element — drop it.
+    if (lines.length && lines[lines.length - 1] === '') lines.pop();
+    const rawCount = lines.length;
+
+    // since filter
+    if (Number.isFinite(args.sinceMs)) {
+        const fileDate = args.date instanceof Date
+            ? args.date
+            : typeof args.date === 'string' && args.date.trim()
+                ? new Date(`${args.date.trim()}T00:00:00.000Z`)
+                : new Date();
+        const floor = args.sinceMs as number;
+        lines = lines.filter((line) => {
+            const ts = parseLineEpochMs(line, fileDate);
+            // Keep lines with no parseable timestamp (continuation/stack lines).
+            return ts === null || ts >= floor;
+        });
+    }
+
+    // grep filter
+    let appliedGrep: string | undefined;
+    if (typeof args.grep === 'string' && args.grep.trim()) {
+        appliedGrep = args.grep.trim();
+        let re: RegExp | null = null;
+        try {
+            re = new RegExp(appliedGrep, 'i');
+        } catch {
+            re = null;
+        }
+        if (re) {
+            const compiled = re;
+            lines = lines.filter((line) => compiled.test(line));
+        } else {
+            // Invalid regex → fall back to a literal substring match.
+            const needle = appliedGrep.toLowerCase();
+            lines = lines.filter((line) => line.toLowerCase().includes(needle));
+        }
+    }
+
+    return {
+        success: true,
+        lines,
+        truncated: raw.truncated,
+        logPath,
+        platform,
+        bytesReturned: raw.bytesReturned,
+        filtered: lines.length !== rawCount,
+        ...(appliedGrep ? { grep: appliedGrep } : {}),
+    };
+}

package/src/mesh/coordinator-prompt.ts

@@ -342,6 +342,7 @@ const TOOLS_SECTION = `## Available Tools
 | \`mesh_read_debug\` | Collect a daemon-side chat/parser debug bundle for a session |
 | \`mesh_task_history\` | Read the task ledger — dispatches, completions, failures. Use to understand what has been done before deciding next steps |
 | \`mesh_git_status\` | Check git status on a specific node |
+| \`mesh_read_node_logs\` | Fetch a remote node's daemon log tail directly over P2P (grep/since/byte-bounded, secrets redacted) — no session/PowerShell needed to debug a node's daemon |
 | \`mesh_fast_forward_node\` | Safely dry-run or explicitly execute an obvious clean fast-forward without launching an agent session |
 | \`mesh_checkpoint\` | Create a git checkpoint on a node |
 | \`mesh_approve\` | Approve/reject a pending agent action |

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.