@adhdev/daemon-core 0.9.82-rc.459 → 0.9.82-rc.460

package/src/mesh/coordinator-prompt.ts

@@ -51,8 +51,14 @@ export interface CoordinatorRecentActivity {
         /** Short task title/message, already truncated by the caller. */
         summary?: string;
     }>;
-    /** Count of task_failed entries inside the recent (30-min) window. */
+    /** Count of task_failed entries inside the recent window. */
     recentFailureCount?: number;
+    /**
+     * Size of the "recent" window in minutes. Drives the "failed in the last
+     * N min" phrasing. Omitted → defaults to 30, matching the prior hardcoded
+     * wording so existing callers render identically.
+     */
+    windowMinutes?: number;
     /** Pending (unclaimed) tasks in the work queue. */
     pendingTasks?: number;
     /** Assigned-but-not-yet-terminal tasks in the work queue. */
@@ -122,7 +128,76 @@ export interface CoordinatorPromptContext {
  * That layering lets a user customize prompts at three increasing scopes
  * (machine, mesh, single launch) without losing the daemon's stock rules.
  */
+/**
+ * 6-4: total prompt soft cap. When the assembled prompt exceeds this, we shed
+ * the two runtime-accumulated, daemon-generated sections — operating notes
+ * first, then recent activity — because they grow unboundedly from the ledger.
+ * We NEVER trim user append/override content or the fixed hardcoded sections
+ * (identity/nodes/policy/tools/workflow/onboarding/rules): those carry user
+ * intent or invariant instructions. If shedding both still overflows, we keep
+ * the prompt as-is rather than mangling protected content.
+ */
+const PROMPT_SOFT_CAP_BYTES = 60 * 1024;
+
+/**
+ * Which daemon-generated optional sections to drop from the default base.
+ * Used only by the 6-4 soft-cap retry — an override base ignores these
+ * because its operating-notes/recent-activity content comes from the user's
+ * own {{placeholder}}s and is not ours to trim.
+ */
+interface DefaultPromptDropFlags {
+    dropOperatingNotes?: boolean;
+    dropRecentActivity?: boolean;
+}
+
 export function buildCoordinatorSystemPrompt(ctx: CoordinatorPromptContext): string {
+    // First pass: assemble with everything included.
+    let prompt = assembleCoordinatorPrompt(ctx, {});
+    if (byteLength(prompt) <= PROMPT_SOFT_CAP_BYTES) return prompt;
+
+    // Over the soft cap. Only the default base carries daemon-generated
+    // operating-notes / recent-activity sections we're allowed to shed; an
+    // override base is user content and stays whole. If we're on an override
+    // base there's nothing safe to trim, so return the first pass unchanged.
+    if (usesOverrideBase(ctx)) return prompt;
+
+    const shed: string[] = [];
+
+    // 1) Shed operating notes first.
+    prompt = assembleCoordinatorPrompt(ctx, { dropOperatingNotes: true });
+    shed.push('operating notes');
+    if (byteLength(prompt) <= PROMPT_SOFT_CAP_BYTES) {
+        return appendTruncationNotice(prompt, shed);
+    }
+
+    // 2) Still over → also shed recent activity.
+    prompt = assembleCoordinatorPrompt(ctx, { dropOperatingNotes: true, dropRecentActivity: true });
+    shed.push('recent activity');
+    return appendTruncationNotice(prompt, shed);
+}
+
+/** True when the base prompt is a mesh-level or user-file override (not the daemon default). */
+function usesOverrideBase(ctx: CoordinatorPromptContext): boolean {
+    if (ctx.mesh.coordinator?.systemPromptOverride?.trim()) return true;
+    return readUserPromptFile(ctx.coordinatorCliType, 'md') !== null;
+}
+
+/** UTF-8 byte length — the cap is a byte budget, not a code-unit count. */
+function byteLength(s: string): number {
+    return Buffer.byteLength(s, 'utf8');
+}
+
+/**
+ * Append a single trailing line recording which daemon-generated sections were
+ * shed to fit the soft cap, so the coordinator (and anyone reading the prompt)
+ * knows the omission was deliberate, not a data-loss bug.
+ */
+function appendTruncationNotice(prompt: string, shed: string[]): string {
+    if (shed.length === 0) return prompt;
+    return `${prompt}\n\n_Prompt exceeded the ${Math.floor(PROMPT_SOFT_CAP_BYTES / 1024)}KB soft cap; omitted to fit: ${shed.join(', ')}. Full detail remains in the ledger (\`mesh_task_history\` / \`mesh_record_note\`)._`;
+}
+
+function assembleCoordinatorPrompt(ctx: CoordinatorPromptContext, drop: DefaultPromptDropFlags): string {
     const { mesh, userInstruction, coordinatorCliType } = ctx;
 
     // ── Pick the base prompt ──
@@ -135,7 +210,7 @@ export function buildCoordinatorSystemPrompt(ctx: CoordinatorPromptContext): str
         if (userOverride !== null) {
             base = expandPromptPlaceholders(userOverride, ctx);
         } else {
-            base = buildDefaultCoordinatorPrompt(ctx);
+            base = buildDefaultCoordinatorPrompt(ctx, drop);
         }
     }
 
@@ -163,7 +238,7 @@ export function buildCoordinatorSystemPrompt(ctx: CoordinatorPromptContext): str
     return sections.join('\n\n');
 }
 
-function buildDefaultCoordinatorPrompt(ctx: CoordinatorPromptContext): string {
+function buildDefaultCoordinatorPrompt(ctx: CoordinatorPromptContext, drop: DefaultPromptDropFlags = {}): string {
     const { mesh, status, coordinatorCliType } = ctx;
     const sections: string[] = [];
 
@@ -187,13 +262,19 @@ Repository: \`${mesh.repoIdentity}\`${mesh.defaultBranch ? `\nDefault branch: \`
         sections.push(ctx.missionSection.trim());
     }
 
-    // ── Recent Activity (Gap1) — only present when there's something to show ──
-    const recentActivity = buildRecentActivitySection(ctx.recentActivity);
-    if (recentActivity) sections.push(recentActivity);
+    // ── Recent Activity (Gap1) — only present when there's something to show.
+    //     Shed under the 6-4 soft cap (drop.dropRecentActivity). ──
+    if (!drop.dropRecentActivity) {
+        const recentActivity = buildRecentActivitySection(ctx.recentActivity);
+        if (recentActivity) sections.push(recentActivity);
+    }
 
-    // ── Operating Notes (Gap2-A) — only present when notes exist ──
-    const operatingNotes = buildOperatingNotesSection(ctx.operatingNotes);
-    if (operatingNotes) sections.push(operatingNotes);
+    // ── Operating Notes (Gap2-A) — only present when notes exist. Shed first
+    //     under the 6-4 soft cap (drop.dropOperatingNotes). ──
+    if (!drop.dropOperatingNotes) {
+        const operatingNotes = buildOperatingNotesSection(ctx.operatingNotes);
+        if (operatingNotes) sections.push(operatingNotes);
+    }
 
     // ── Policy ──
     sections.push(buildPolicySection(mergeAndNormalizePolicy(undefined, mesh.policy)));
@@ -390,6 +471,9 @@ function buildRecentActivitySection(activity?: CoordinatorRecentActivity): strin
     const recentFailureCount = Number.isFinite(activity.recentFailureCount)
         ? Number(activity.recentFailureCount)
         : failures.length;
+    const windowMinutes = Number.isFinite(activity.windowMinutes) && Number(activity.windowMinutes) > 0
+        ? Math.floor(Number(activity.windowMinutes))
+        : 30;
 
     // Nothing actionable to show → omit the section entirely.
     if (failures.length === 0 && pending === 0 && assigned === 0 && stalled === 0 && recentFailureCount === 0) {
@@ -404,7 +488,7 @@ function buildRecentActivitySection(activity?: CoordinatorRecentActivity): strin
     if (pending > 0) counts.push(`**${pending}** pending`);
     if (assigned > 0) counts.push(`**${assigned}** assigned`);
     if (stalled > 0) counts.push(`**${stalled}** stalled`);
-    if (recentFailureCount > 0) counts.push(`**${recentFailureCount}** failed in the last 30 min`);
+    if (recentFailureCount > 0) counts.push(`**${recentFailureCount}** failed in the last ${windowMinutes} min`);
     if (counts.length) lines.push(`- Queue/ledger: ${counts.join(', ')}.`);
     if (activity.lastActivityAt) lines.push(`- Last ledger activity: ${activity.lastActivityAt}.`);
 
@@ -430,6 +514,15 @@ function buildRecentActivitySection(activity?: CoordinatorRecentActivity): strin
  * note gets the unchanged prompt. Notes are runtime-accumulated lessons that
  * persist across coordinator restarts and are provider-neutral.
  */
+/**
+ * 6-4 prompt-build caps for the Operating Notes section. These bound how much
+ * of the ledger rides into every coordinator prompt — the ledger itself keeps
+ * more (keep-latest 100 prune lives in mesh-ledger.ts); this is a separate,
+ * tighter cap applied only when composing the prompt.
+ */
+const OPERATING_NOTES_PROMPT_CAP = 20;
+const OPERATING_NOTE_MAX_CHARS = 300;
+
 function buildOperatingNotesSection(notes?: CoordinatorOperatingNote[]): string {
     const valid = Array.isArray(notes)
         ? notes.filter(n => n && typeof n.text === 'string' && n.text.trim())
@@ -442,16 +535,35 @@ function buildOperatingNotesSection(notes?: CoordinatorOperatingNote[]): string
         recovery_lesson: 'recovery lesson',
     };
 
+    // Keep only the most recent OPERATING_NOTES_PROMPT_CAP notes in the prompt.
+    // `valid` is oldest-first (ledger order), so the newest are at the tail.
+    const omittedCount = Math.max(0, valid.length - OPERATING_NOTES_PROMPT_CAP);
+    const shown = omittedCount > 0 ? valid.slice(-OPERATING_NOTES_PROMPT_CAP) : valid;
+
     const lines: string[] = ['## Operating Notes', ''];
     lines.push('Lessons earlier coordinators on this mesh recorded via `mesh_record_note`. Treat them as accumulated operating knowledge — apply them. When you learn a durable lesson (a provider quirk, a pattern to avoid, a recovery lesson), record it with `mesh_record_note` so future coordinators inherit it.');
     lines.push('');
-    for (const n of valid) {
+    for (const n of shown) {
         const cat = n.category && categoryLabel[n.category] ? `[${categoryLabel[n.category]}] ` : '';
-        lines.push(`- ${cat}${n.text.trim()}`);
+        lines.push(`- ${cat}${truncateNote(n.text.trim())}`);
+    }
+    if (omittedCount > 0) {
+        lines.push('');
+        lines.push(`_${omittedCount} older note${omittedCount === 1 ? '' : 's'} omitted (kept in ledger; prune with \`mesh_forget_note\`)._`);
     }
     return lines.join('\n');
 }
 
+/**
+ * Truncate a single operating note to OPERATING_NOTE_MAX_CHARS, appending an
+ * ellipsis marker so the coordinator knows the note was clipped in the prompt
+ * (the full text stays in the ledger).
+ */
+function truncateNote(text: string): string {
+    if (text.length <= OPERATING_NOTE_MAX_CHARS) return text;
+    return `${text.slice(0, OPERATING_NOTE_MAX_CHARS).trimEnd()}… [truncated]`;
+}
+
 function buildPolicySection(policy: RepoMeshPolicy): string {
     const rules: string[] = [];
     if (policy.requirePreTaskCheckpoint) rules.push('- Create a git checkpoint **before** starting each task');
@@ -584,5 +696,13 @@ function buildRulesSection(coordinatorCliType?: string): string {
 - **Honor per-node instructions.** When a node carries a 📌 Node instruction in the nodes section, include the relevant parts of that instruction in the task message you send to that node. Don't paraphrase the instruction into your own words — quote it verbatim so the worker agent sees exactly what the user wrote.
 - **Mission status does not update itself.** When a mission's tasks are all done or the work is abandoned, explicitly call \`mesh_mission_upsert\` to set status \`completed\` or \`abandoned\`. Never leave a finished mission in \`active\`. All-cancelled tasks with no further work → \`abandoned\`.
 - **Never fabricate tool results.** Always call the actual tool.
-- **Keep the user informed.** One or two sentences after each delegation round.${coordinatorNote}`;
+- **Keep the user informed.** One or two sentences after each delegation round.${coordinatorNote}
+
+### Task Messaging Requirements
+
+When you compose the task message you dispatch to a node, include these requirements so the worker follows repo conventions the daemon can't enforce for it:
+
+- **OSS English commits.** If a task commits anything under \`oss/\` (an AGPL public repo whose history external contributors read), tell the worker explicitly that commit messages in \`oss/\` MUST be English. Root-level commits (proprietary packages) may use any language.
+- **Scoped test runs.** For a validation or code-change task, instruct the worker to run only the tests covering the changed files (\`vitest run <path>\` or \`-t <name>\`), not the whole suite. Run the full suite only when the task is explicitly a full-suite gate — a broad daemon-core run is minutes of wall-clock and the biggest source of worker slowness.
+- **Branch convergence state.** For a worktree task, require the completion report to classify the touched branch into exactly one final state: \`merged_to_main\`, \`pushed_feature_branch_needs_merge\`, \`blocked_review\`, \`cleanup_candidate\`, or \`not_mergeable\`. A task that ends on a non-main branch is not complete unless the report names that state and the next step.`;
 }

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

@@ -6,6 +6,13 @@ import { getLedgerDir, readLedgerEntries, appendLedgerEntry } from './mesh-ledge
 import { MeshRuntimeStore } from './mesh-runtime-store.js';
 import { buildMeshSystemMessage, readNonEmptyString, readRecord, resolveEventSessionId, readMeshCompletionSummary, isWeakCompletionMetadata } from './mesh-events-utils.js';
 import { expandDaemonIdForms } from '@adhdev/mesh-shared';
+import {
+    buildPendingEventEmitStamp,
+    coordinatorIdentityFromEmitFields,
+    MESH_PROTOCOL_VERSION_V2,
+    type CoordinatorIdentity,
+    type MeshEventScope,
+} from './contracts.js';
 
 // ---------------------------------------------------------------------------
 // MCP coordinator pending-event queue — FILE-BASED PERSISTENCE
@@ -44,6 +51,40 @@ export interface PendingMeshCoordinatorEvent {
      * the JSONL file without a dedicated column; it is NOT a drain-scoping key.
      */
     targetCoordinatorSessionId?: string;
+
+    // ─── v2 protocol envelope (B2a) — additive, populated at emit time ────────
+    // Stamped by queuePendingMeshCoordinatorEvent from the fields above plus an
+    // optional emit hint. A v1 reader that ignores these is unaffected (the v2
+    // shape is a strict superset). Absent → the event is a v1 event, treated as
+    // broadcast during rollout.
+    /** '2.0' once stamped. Absent on v1 events. */
+    protocolVersion?: typeof MESH_PROTOCOL_VERSION_V2;
+    /** Idempotency key (UUID). The receiver's authoritative dedup key (B3). */
+    eventId?: string;
+    /** Routing scope. Defaulted from the event name unless the emit hint overrides. */
+    scope?: MeshEventScope;
+    /** Identity of the coordinator that dispatched the work this event reports. */
+    dispatchedBy?: CoordinatorIdentity;
+    /** Present only for unicast scope: the coordinator this event is addressed to. */
+    intendedFor?: CoordinatorIdentity;
+}
+
+/**
+ * Optional emit-time hint passed to queuePendingMeshCoordinatorEvent so a call
+ * site can override the name-defaulted scope or supply richer coordinator
+ * identity (e.g. a coordinatorRunId the base event fields don't carry). Every
+ * field is optional; when omitted the stamp is derived entirely from the
+ * event's own targetCoordinatorDaemonId / targetCoordinatorSessionId. Kept
+ * separate from the event so existing single-arg callers are untouched.
+ */
+export interface PendingEventEmitHint {
+    scope?: MeshEventScope;
+    /** Overrides the coordinator identity derived from the event's target fields. */
+    dispatchedBy?: CoordinatorIdentity;
+    /** Overrides the unicast target derived from the event's target fields. */
+    intendedFor?: CoordinatorIdentity;
+    /** coordinatorRunId to fold into the derived identity when the event lacks one. */
+    coordinatorRunId?: string;
 }
 
 const REFINE_TERMINAL_EVENTS = new Set(['refine:completed', 'refine:failed']);
@@ -327,7 +368,67 @@ function trimPendingEventsIfNeeded(path: string): void {
     } catch { /* best-effort; if trim fails, append still proceeds */ }
 }
 
-export function queuePendingMeshCoordinatorEvent(event: PendingMeshCoordinatorEvent): boolean {
+/**
+ * Stamp the v2 protocol envelope onto a pending event at emit time (B2a).
+ *
+ * Non-breaking: returns a NEW event object with protocolVersion/eventId/scope/
+ * dispatchedBy/intendedFor added when a coordinator identity can be derived,
+ * otherwise returns the input unchanged (a v1 event, broadcast-treated during
+ * rollout). Identity and the unicast target are derived from the event's own
+ * targetCoordinatorDaemonId / targetCoordinatorSessionId (already carried by
+ * every producer), so most call sites need no change; the optional `hint`
+ * overrides scope/identity where a site knows better.
+ *
+ * The eventId is generated here (randomUUID) exactly once, so re-queues that
+ * pass an already-stamped event keep their original eventId — the idempotency
+ * key is stable across re-delivery. An already-stamped event is returned as-is.
+ */
+export function stampPendingEventV2(
+    event: PendingMeshCoordinatorEvent,
+    hint?: PendingEventEmitHint,
+): PendingMeshCoordinatorEvent {
+    // Preserve idempotency across re-queues: never re-stamp an event that already
+    // carries a v2 eventId (mesh-reconcile-loop / flushPendingForMeshIdleCoordinators
+    // re-queue built events verbatim).
+    if (event.protocolVersion === MESH_PROTOCOL_VERSION_V2 && readNonEmptyString(event.eventId)) {
+        return event;
+    }
+
+    const dispatchedBy = hint?.dispatchedBy ?? coordinatorIdentityFromEmitFields({
+        daemonId: event.targetCoordinatorDaemonId,
+        coordinatorRunId: hint?.coordinatorRunId,
+        sessionId: event.targetCoordinatorSessionId,
+    });
+    // The unicast target is, by default, the same coordinator the event is already
+    // routed to (its originating coordinator). A hint may override it.
+    const intendedFor: CoordinatorIdentity | undefined = hint?.intendedFor ?? dispatchedBy;
+
+    const stamp = buildPendingEventEmitStamp({
+        eventName: event.event,
+        eventId: randomUUID(),
+        dispatchedBy,
+        intendedFor,
+        scope: hint?.scope,
+    });
+    if (!stamp) return event; // no coordinator identity → stays a v1 event
+
+    return {
+        ...event,
+        protocolVersion: stamp.protocolVersion,
+        eventId: stamp.eventId,
+        scope: stamp.scope,
+        dispatchedBy: stamp.dispatchedBy,
+        ...(stamp.intendedFor ? { intendedFor: stamp.intendedFor } : {}),
+    };
+}
+
+export function queuePendingMeshCoordinatorEvent(
+    rawEvent: PendingMeshCoordinatorEvent,
+    hint?: PendingEventEmitHint,
+): boolean {
+    // B2a: stamp the v2 envelope before dedup/persist so the eventId/scope ride
+    // into both stores and the fingerprint/dedup logic sees the final shape.
+    const event = stampPendingEventV2(rawEvent, hint);
     try {
         if (hasPendingRefineTerminalEventDuplicate(event)) {
             LOG.info('MeshEvents', `Suppressed duplicate pending ${event.event} for refine job ${readRefineJobId(event)}`);
@@ -351,6 +452,15 @@ export function queuePendingMeshCoordinatorEvent(event: PendingMeshCoordinatorEv
                 payload: event,
                 fingerprint: fingerprint || null,
                 queuedAt: event.queuedAt,
+                // v2 envelope columns (B2a) — all nullable so v1 rows coexist. The
+                // authoritative copy still rides inside `payload`; these columns exist
+                // for queryable idempotency (event_id) and scope-based drain filtering
+                // (scope / intended_for) without JSON-parsing every row.
+                protocolVersion: event.protocolVersion ?? null,
+                eventId: event.eventId ?? null,
+                scope: event.scope ?? null,
+                dispatchedBy: event.dispatchedBy ? JSON.stringify(event.dispatchedBy) : null,
+                intendedFor: event.intendedFor ? JSON.stringify(event.intendedFor) : null,
             });
             sqliteOk = true;
         } catch {

package/src/mesh/mesh-ledger.ts

@@ -20,6 +20,11 @@ import { getConfigDir } from '../config/config.js';
 import { daemonIdsEquivalent, sessionIdsEquivalent } from '@adhdev/mesh-shared';
 import { EventEmitter } from 'events';
 import { MeshRuntimeStore } from './mesh-runtime-store.js';
+import {
+    coordinatorIdentityFromEmitFields,
+    MESH_PROTOCOL_VERSION_V2,
+    type MeshLedgerOriginatingCoordinatorV2,
+} from './contracts.js';
 // ─── Types ──────────────────────────────────────
 
 export type MeshLedgerKind =
@@ -627,6 +632,32 @@ export function buildTaskCompletionEvidence(opts: BuildTaskCompletionEvidenceOpt
     };
 }
 
+/**
+ * Build the v2 originating-coordinator stamp for a task_dispatched ledger entry
+ * (B2a / design decision §2). This is the source of truth from which a worker's
+ * completion emit later restores `dispatchedBy` — it records which coordinator
+ * dispatched the task, so the terminal event can be routed (unicast) back to it.
+ *
+ * Nested under `payload.originatingCoordinator`; additive, so existing readers
+ * of the task_dispatched payload are unaffected. Returns undefined when no
+ * coordinator daemon id is known (the pre-v2 path) so the caller omits the stamp
+ * entirely rather than writing a malformed identity — those entries stay v1 and
+ * are broadcast-treated during rollout.
+ */
+export function buildLedgerOriginatingCoordinatorStamp(fields: {
+    coordinatorDaemonId?: string | null;
+    coordinatorRunId?: string | null;
+    coordinatorSessionId?: string | null;
+}): MeshLedgerOriginatingCoordinatorV2 | undefined {
+    const originatingCoordinator = coordinatorIdentityFromEmitFields({
+        daemonId: fields.coordinatorDaemonId,
+        coordinatorRunId: fields.coordinatorRunId,
+        sessionId: fields.coordinatorSessionId,
+    });
+    if (!originatingCoordinator) return undefined;
+    return { originatingCoordinator, protocolVersion: MESH_PROTOCOL_VERSION_V2 };
+}
+
 /**
  * Append a new entry to the mesh ledger.
  * Handles file creation, rotation on size overflow, and atomic writes.

package/src/mesh/mesh-node-identity.ts

@@ -544,6 +544,12 @@ export function foldMeshNodeIdentityToCanonical(node: any): any {
     // flips, because both always agree). Mutating in place (not returning a new
     // object) preserves the cached node-object identity that callers warming an
     // inline mesh from an already-shared snapshot rely on.
+    // Intentional per-field raw compare against the already-computed canonical
+    // value: this is the fold's no-op fast path, checking whether EACH form field
+    // is already folded. Using meshNodeIdMatches (which normalizes across forms)
+    // would defeat the point — we must inspect each raw field's current state, not
+    // a form-agnostic match. Hence the identity-guard opt-out below.
+    // eslint-disable-next-line no-restricted-syntax -- verified same-source canonical no-op guard (see above)
     if (node.id === canonical && node.nodeId === canonical && node.node_id === undefined) return node;
     node.id = canonical;
     node.nodeId = canonical;

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

@@ -1094,6 +1094,57 @@ export function __orderEligibleNodesForTests(
     return orderEligibleNodes(meshId, strategy, nodes, opts);
 }
 
+/** One idle session eligible to claim a queued task, together with the resolved
+ *  mesh node record it belongs to. Local candidates come from live CLI instances,
+ *  remote candidates from the registered remote-idle-session store; the two arrive
+ *  with their `nodeId` under different serialization forms. */
+type IdleCandidate = { nodeId: string; sessionId: string; providerType: string; origin: 'local' | 'remote'; node: any };
+
+/**
+ * Merge local + remote idle candidates into the scheduling pool with a single,
+ * form-canonical node identity.
+ *
+ * INVARIANT: every candidate in the returned pool carries its `nodeId` in
+ * CANONICAL (normalized) form, and `uniqueNodes` has exactly one entry per
+ * physical node. Local and remote candidates arrive with their `nodeId` under
+ * mixed forms (config `id`, wire `nodeId`, DB `node_id`). Downstream scheduling
+ * keys the pool by raw-string equality (Set dedup, baseIndex, rankIndex,
+ * nodeActiveLoad), so two candidates for the SAME physical node under two
+ * different forms would otherwise be treated as two distinct nodes — form-drift
+ * that splits a node's load and double-ranks it. Canonicalizing here (via the
+ * resolved node record, which meshNodeIdMatches already matched form-agnostically)
+ * makes every later `=== nodeId` comparison operate on one agreed form. Falls back
+ * to the raw candidate id when the node is unresolved (an unresolved candidate
+ * cannot be normalized, but also has no sibling to collide with).
+ */
+function buildSchedulingPool(
+    localCandidates: IdleCandidate[],
+    remoteCandidates: IdleCandidate[],
+): { pool: IdleCandidate[]; uniqueNodes: RankableNode[] } {
+    const pool = [...localCandidates, ...remoteCandidates].map(c => ({
+        ...c,
+        nodeId: normalizeMeshNodeId(c.node) ?? c.nodeId,
+    }));
+    // Both sides are canonical now, so raw `===` in the Set dedup and the node
+    // re-lookup is form-safe.
+    const uniqueNodes: RankableNode[] = [...new Set(pool.map(c => c.nodeId))]
+        .map((nodeId, index) => ({
+            nodeId,
+            node: pool.find(c => meshNodeIdMatches({ id: c.nodeId } as MeshNodeIdentified, nodeId))?.node,
+            index,
+        }));
+    return { pool, uniqueNodes };
+}
+
+/** Test-only: the pool-canonicalization + unique-node collapse stage. Exposed so
+ *  the mixed-form dedup invariant can be unit-tested without a live daemon. */
+export function __buildSchedulingPoolForTests(
+    localCandidates: IdleCandidate[],
+    remoteCandidates: IdleCandidate[],
+): { pool: IdleCandidate[]; uniqueNodes: RankableNode[] } {
+    return buildSchedulingPool(localCandidates, remoteCandidates);
+}
+
 function orderEligibleNodes(
     meshId: string,
     strategy: RepoMeshSchedulingStrategy,
@@ -1946,7 +1997,6 @@ export async function triggerMeshQueue(components: DaemonComponents, meshId: str
     //     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[] = [];
 
@@ -2023,12 +2073,13 @@ export async function triggerMeshQueue(components: DaemonComponents, meshId: str
         // 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];
+        // buildSchedulingPool canonicalizes every candidate's nodeId so the Set
+        // dedup, baseIndex, rankIndex, and nodeActiveLoad keying below all agree on
+        // one form (see the invariant on that helper).
+        const { pool, uniqueNodes } = buildSchedulingPool(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];