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

package/src/mesh/contracts.ts

@@ -332,7 +332,12 @@ export function assertPendingMeshCoordinatorEventV2(raw: unknown, path = '$'): P
  * Decide whether a v2 pending event should be delivered to the given drainer.
  * Centralised so every drain implementation uses the same rule.
  *
- *   - 'broadcast': always delivered.
+ *   - 'broadcast': always delivered. NOTE: a terminal task event that reached the
+ *     queue as broadcast is an ownership leak (it belongs to its dispatching
+ *     coordinator). This pure helper does not have the drain-window
+ *     daemon-form/session matching semantics, so the terminal+broadcast
+ *     dispatchedBy filter is applied one layer up in the drainer (see
+ *     mesh-events-pending routeV2EventsForDrainer) where those semantics live.
  *   - 'system': never delivered to coordinators (system handler only).
  *   - 'unicast': delivered iff intendedFor matches drainer identity.
  *
@@ -367,6 +372,18 @@ const TERMINAL_TASK_EVENTS: ReadonlySet<string> = new Set([
   'refine:accepted',
 ]);
 
+/**
+ * True for a terminal task event (completion / stop / refine outcome). A terminal
+ * event belongs to exactly the coordinator that dispatched the task, so it must
+ * never fan out to sibling coordinators that did not dispatch it. Used by the
+ * emit-side stamp (to avoid downgrading an unaddressed terminal event to full
+ * broadcast) and by the drain-side filter (defense-in-depth for any terminal
+ * event that already reached the queue as broadcast).
+ */
+export function isTerminalTaskEvent(eventName: string): boolean {
+  return TERMINAL_TASK_EVENTS.has(eventName);
+}
+
 /**
  * Coordinator-addressed dispatch-plane alerts. `mesh:dispatch_blocked` is the
  * Fix (1) actionable dispatch-skip notification: it exists precisely to page the
@@ -445,9 +462,18 @@ export function coordinatorIdentityFromEmitFields(fields: {
  * returns undefined: the event stays a v1 (unstamped) event and is broadcast-
  * treated during rollout, exactly as before — no regression, no fabricated
  * identity. When the resolved scope is 'unicast' but no `intendedFor` is
- * available, the scope is downgraded to 'broadcast' so the stamp never violates
- * the "unicast requires intendedFor" contract (a terminal event that cannot be
- * addressed to its originator is safest delivered broadly, not dropped).
+ * available, the fallback depends on the event class:
+ *
+ *   - Terminal task events (completion / stop / refine outcome) MUST NOT be
+ *     broadcast to every coordinator — a completion belongs to the coordinator
+ *     that dispatched the task, and broadcasting it makes non-owner coordinators
+ *     (e.g. sibling MAGI coordinators that never dispatched this replica's task)
+ *     act on a completion that is not theirs (MAGI-REPLICA-COMPLETION-EVENT-LEAK).
+ *     For these we address the event to `dispatchedBy` (the dispatching
+ *     coordinator) and KEEP it unicast, so the stamp stays contract-valid and the
+ *     event reaches only its originating coordinator.
+ *   - Any other unicast event with no addressable target falls back to broadcast
+ *     (contract-valid, still delivered, never dropped) — unchanged.
  */
 export function buildPendingEventEmitStamp(opts: {
   eventName: string;
@@ -460,9 +486,18 @@ export function buildPendingEventEmitStamp(opts: {
   let scope: MeshEventScope = opts.scope ?? defaultScopeForEvent(opts.eventName);
   let intendedFor = opts.intendedFor;
   if (scope === 'unicast' && !intendedFor) {
-    // No addressable target for a unicast event — fall back to broadcast so the
-    // stamp is contract-valid and the event is still delivered (never dropped).
-    scope = 'broadcast';
+    if (isTerminalTaskEvent(opts.eventName)) {
+      // Terminal event with no explicit target: address it to the dispatching
+      // coordinator rather than broadcasting to every coordinator. dispatchedBy
+      // is the coordinator that owns the task, so this is the correct — and
+      // contract-valid (unicast requires intendedFor) — narrowing.
+      intendedFor = opts.dispatchedBy;
+    } else {
+      // No addressable target for a non-terminal unicast event — fall back to
+      // broadcast so the stamp is contract-valid and the event is still
+      // delivered (never dropped).
+      scope = 'broadcast';
+    }
   }
   if (scope !== 'unicast') intendedFor = undefined;
   return {

package/src/mesh/coordinator-prompt.ts

@@ -32,6 +32,8 @@ import type {
     RepoMeshNodeStatus,
 } from '../repo-mesh-types.js';
 import { mergeAndNormalizePolicy } from '../repo-mesh-types.js';
+import { getDifficultyBrains } from '../config/mesh-config.js';
+import { MESH_TASK_DIFFICULTIES } from '@adhdev/mesh-shared';
 
 /**
  * Cheap, locally-derived "what just happened" snapshot for the coordinator
@@ -279,6 +281,9 @@ Repository: \`${mesh.repoIdentity}\`${mesh.defaultBranch ? `\nDefault branch: \`
     // ── Policy ──
     sections.push(buildPolicySection(mergeAndNormalizePolicy(undefined, mesh.policy)));
 
+    // ── Brain presets (difficulty → model/thinking) ──
+    sections.push(buildBrainPresetsSection());
+
     // ── Tools ──
     sections.push(TOOLS_SECTION);
 
@@ -454,6 +459,23 @@ function buildNodeConfigSection(mesh: LocalMeshEntry): string {
             : [];
         const providerRolesSuffix = providerRoles.length ? ` | caps: ${providerRoles.join(', ')}` : '';
         lines.push(`- ${explicitLabel} nodeId: \`${n.id}\` | workspace: \`${n.workspace}\`${n.daemonId ? ` | daemon: \`${n.daemonId}\`` : ''}${providerPriority}${providerRolesSuffix}${suffix}`);
+        // Routing tags: what this node advertises for mesh_enqueue_task required_tags.
+        // Surfaced so the coordinator can route by-capability (e.g. enqueue a Windows
+        // build with required_tags:["os=win32"], or a custom "test-runner" node).
+        // os=/arch= use the same userOverrides → reported precedence as the matcher;
+        // the internal converge= tag is omitted (it is not something to target by hand).
+        const routingTags: string[] = [];
+        const custom = Array.isArray((n as any).capabilities) ? (n as any).capabilities : [];
+        for (const t of custom) { const s = typeof t === 'string' ? t.trim() : ''; if (s) routingTags.push(s); }
+        const tagOs = ((n as any).userOverrides?.platform || (n as any).reportedPlatform || '').toString().trim();
+        const tagArch = ((n as any).userOverrides?.arch || (n as any).reportedArch || '').toString().trim();
+        if (tagOs) routingTags.push(`os=${tagOs}`);
+        if (tagArch) routingTags.push(`arch=${tagArch}`);
+        const wtBranch = typeof (n as any).worktreeBranch === 'string' ? (n as any).worktreeBranch.trim() : '';
+        if (n.isLocalWorktree && wtBranch) routingTags.push(`worktree=${wtBranch}`);
+        if (routingTags.length) {
+            lines.push(`  🏷️ routing tags: ${routingTags.map(t => `\`${t}\``).join(', ')}`);
+        }
         const nodePrompt = typeof (n as any).systemPrompt === 'string' ? (n as any).systemPrompt.trim() : '';
         if (nodePrompt) {
             lines.push(`  📌 Node instruction: ${indentFollowing(nodePrompt, '     ')}`);
@@ -582,6 +604,36 @@ function truncateNote(text: string): string {
     return `${text.slice(0, OPERATING_NOTE_MAX_CHARS).trimEnd()}… [truncated]`;
 }
 
+/**
+ * Render the difficulty→brain presets so the coordinator knows what each
+ * `difficulty` value resolves to (which model / thinking level). Machine-local,
+ * read live at prompt-build time — seeded defaults when nothing is configured.
+ */
+function buildBrainPresetsSection(): string {
+    let brains;
+    try { brains = getDifficultyBrains(); } catch { brains = {}; }
+    const lines = [
+        '## Brain presets',
+        '',
+        'When you pass `difficulty` on `mesh_enqueue_task`, it resolves to this model / thinking level (an explicit model/thinkingLevel on the task overrides it). Pick easy for trivial work to save tokens, difficult for hard reasoning.',
+        '',
+    ];
+    for (const key of MESH_TASK_DIFFICULTIES) {
+        const slot = (brains as Record<string, { provider?: string; model?: string; thinkingLevel?: string } | undefined>)[key];
+        if (!slot || (!slot.provider && !slot.model && !slot.thinkingLevel)) {
+            lines.push(`- **${key}**: (no preset — ordinary routing)`);
+            continue;
+        }
+        const parts = [
+            slot.provider ? `provider: \`${slot.provider}\`` : '',
+            slot.model ? `model: \`${slot.model}\`` : '',
+            slot.thinkingLevel ? `thinking: \`${slot.thinkingLevel}\`` : '',
+        ].filter(Boolean).join(' | ');
+        lines.push(`- **${key}**: ${parts}`);
+    }
+    return lines.join('\n');
+}
+
 function buildPolicySection(policy: RepoMeshPolicy): string {
     const rules: string[] = [];
     if (policy.requirePreTaskCheckpoint) rules.push('- Create a git checkpoint **before** starting each task');
@@ -663,6 +715,7 @@ const WORKFLOW_SECTION = `## Orchestration Workflow
 3. **Queue / Delegate** — The Mesh uses an autonomous pull-based Work Queue:
    a. **General Tasks**: Enqueue tasks using \`mesh_enqueue_task\`. Idle node agents will automatically pull tasks from the queue and begin working.
    b. **Node Preparation**: Reuse an existing idle session on the correct node/provider before launching a new chat/session. Call \`mesh_launch_session\` only when no suitable session exists, when the user explicitly asks for a fresh provider/session, or when branch/worktree isolation requires it. If you need branch isolation for parallel work, call \`mesh_clone_node\` to create a worktree node first.
+   b1. **Keep a branch's work on its worktree (worktree affinity).** A worktree node is a durable per-branch workspace, not a one-task throwaway — implement, review, and fix for the same branch all belong on the SAME worktree, and it lives until its work is converged (merged/pushed) and it is cleaned up. So once you clone a worktree for a branch, route every subsequent \`code_change\`/\`validation\`/fix task for that branch back to that same node: pass \`required_tags: ["worktree=<branch>"]\` or \`target_node_id: <that worktree node's id>\`. **Where to get the node id / tag:** the \`mesh_clone_node\` result returns the new node's \`id\` and \`worktreeBranch\` directly — use them immediately. The Configured Nodes list in this prompt is a launch-time snapshot and will NOT list a worktree you cloned after this session started, so do not rely on it for freshly-cloned worktrees; take the id/branch from the \`mesh_clone_node\` result, or call \`mesh_status\` to re-list the live nodes (each worktree there advertises its \`worktree=<branch>\` tag). Do NOT leave same-branch follow-ups untargeted — an untargeted task is claimed by whichever node polls first (usually the base machine node), which strands the work off the branch's worktree. The ONE exception is a \`convergence\` task (merge/push): that is base-only and must NOT be pinned to the worktree.
    c. **Targeted Tasks**: Use \`mesh_send_task\` only when you need to bypass the queue and force a specific node to execute a task immediately.
    d. For the first dispatch of a new task, provide a **complete, self-contained** instruction that includes all context the agent needs (file paths, line numbers, what to change, why). Do not send partial instructions expecting future follow-up.
    e. For a continuation of the same issue in an existing session, send a concise **delta instruction**: current verified state, the exact failed/blocked step, the newly approved action, and final reporting requirements. Do not resend the full original task or open a new chat solely to continue the same work; that wastes coordinator and worker context.
@@ -718,6 +771,8 @@ function buildRulesSection(coordinatorCliType?: string): string {
 - **Route, don't implement.** Delegate all code reading, analysis, and execution to node agents. Never read source files or run commands in the coordinator — keep context lean.
 - **Front-load task messages.** Include everything the agent needs (files, problem, expected fix) in \`mesh_enqueue_task\` / \`mesh_send_task\`. Append a structured result request at the end: ask the worker to conclude with a JSON block containing \`status\`, \`changedFiles\`, \`gitStatus\`, \`validationResults\`, \`errors\`, \`nextAction\`. The daemon parses this automatically; you can read it from \`mesh_task_history\`.
 - **Reuse idle sessions.** For follow-up, retry, commit/push, or cleanup on the same issue, send only the delta to the existing idle session. Start fresh only for independent work, provider mismatch, transcript contamination, or required worktree isolation.
+- **Worktree affinity.** A worktree is a durable per-branch workspace; keep all of a branch's code_change/fix/review work on its worktree node by targeting \`required_tags: ["worktree=<branch>"]\` or \`target_node_id\`. Get the id/branch from the \`mesh_clone_node\` result or a live \`mesh_status\` — the Configured Nodes snapshot won't list a worktree cloned after launch. Untargeted same-branch follow-ups drift to the base node. Only \`convergence\` (merge/push) runs on the base, never pinned to the worktree.
+- **Classify task difficulty to save tokens.** For each task you enqueue, judge its execution difficulty and pass \`difficulty\`: \`easy\` (extraction, renames, doc tweaks, trivial fixes), \`medium\` (ordinary feature/bugfix work), \`difficult\` (architecture, tricky debugging, multi-file refactors, subtle reasoning), or \`freeform\`. The mesh's per-difficulty brain preset then runs easy tasks on a cheaper model at low reasoning effort and hard tasks on a stronger model at high effort — real token savings on simple work. The current presets are shown in the "Brain presets" section below. You may still pass an explicit \`model\`/\`thinkingLevel\` to override the preset for one task.
 - **Respect explicit provider requests.** Map: Hermes → \`hermes-cli\`, Claude/Claude Code → \`claude-cli\`, Codex → \`codex-cli\`, Gemini → \`gemini-cli\`, Antigravity → \`antigravity-cli\`. Never substitute the coordinator's own runtime.
 - **Verify via git, not source.** Use \`mesh_git_status\` to confirm side effects. Treat agent summaries as self-reports, not verification.
 - **Limit parallelism.** Start with 1–2 tasks; scale only on success. Never duplicate a session because \`mesh_read_chat\` shows no final message while tool/terminal activity is ongoing. This caps *concurrent* load — it does not mean serialize independent work: when a new, independent request arrives and there is headroom under \`maxParallelTasks\`, dispatch it right away rather than waiting for an in-flight task or a user nudge (read-only diagnosis especially, since it has no merge cost).

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

@@ -14,6 +14,7 @@ import {
     coordinatorIdentityFromEmitFields,
     coordinatorIdentityKey,
     isMeshEventScope,
+    isTerminalTaskEvent,
     MESH_PROTOCOL_VERSION_V2,
     shouldDeliverPendingEventToCoordinator,
     type CoordinatorIdentity,
@@ -74,6 +75,18 @@ export interface PendingMeshCoordinatorEvent {
     dispatchedBy?: CoordinatorIdentity;
     /** Present only for unicast scope: the coordinator this event is addressed to. */
     intendedFor?: CoordinatorIdentity;
+    /**
+     * True when this event was stamped as a broadcast SOLELY because no owning
+     * coordinator identity was resolvable at emit time (self-fallback: dispatchedBy
+     * is THIS daemon's own machineId, not a real coordinator). Such a broadcast has
+     * no owner, so the MAGI-REPLICA-COMPLETION-EVENT-LEAK guard — which only exists
+     * to stop a NON-owner coordinator from consuming an OWNED terminal event — must
+     * not apply: an ownerless terminal broadcast is a genuine "deliver to any
+     * coordinator that drains on this machine" event and identity-matching its
+     * self-id dispatchedBy against the drainer would wrongly route it away.
+     * Absent (undefined/false) on a normally-owned event → the leak guard applies.
+     */
+    dispatchedBySelfFallback?: boolean;
 }
 
 /**
@@ -408,6 +421,39 @@ function routeV2EventsForDrainer(
         // Broadcast → any coordinator; system → daemon handler only (never a
         // coordinator). Delegates to the contract helper for those two scopes.
         if (validated.scope !== 'unicast') {
+            // Defense-in-depth (MAGI-REPLICA-COMPLETION-EVENT-LEAK): a TERMINAL task
+            // event that reached the queue as broadcast is an ownership leak — a
+            // completion/stop belongs to the coordinator that dispatched the task, so
+            // a sibling coordinator that never dispatched it must NOT act on it. The
+            // emit-side stamp now narrows unaddressed terminal events to unicast, but a
+            // legacy/version-skewed/other-path broadcast can still arrive here; filter
+            // it by dispatchedBy vs the drainer using the SAME daemon-form/session
+            // matching semantics as unicast (identityDeliversTo), so the true owner —
+            // possibly addressed under a different daemon-id form — still receives it.
+            if (validated.scope === 'broadcast' && isTerminalTaskEvent(validated.event)) {
+                // An ownerless self-fallback broadcast (dispatchedBy is this daemon's
+                // own machineId because no coordinator identity existed at emit) has no
+                // coordinator owner — but it must still stay on ITS machine: a replica
+                // completion emitted on machine A must never fan out to a coordinator on
+                // machine B (the MAGI-REPLICA leak). So for a self-fallback event, match
+                // at the MACHINE (daemonId) level — deliver iff the drainer is on the
+                // same machine as the self-dispatcher — instead of the full
+                // identityDeliversTo (which also compares runId/session and would route
+                // the event away from a same-machine coordinator whose id form differs,
+                // the exact symptom for refine:* / agent:generating_completed reaching a
+                // stdio MCP coordinator). Non-self-fallback broadcasts keep the strict
+                // owner check.
+                const deliverSelfFallback = event.dispatchedBySelfFallback
+                    && daemonIdsEquivalent(validated.dispatchedBy.daemonId, drainer.daemonId);
+                if (deliverSelfFallback || identityDeliversTo(validated.dispatchedBy, drainer)) {
+                    ctx.batchSeen.add(eventId);
+                    bump('v2Delivered');
+                    kept.push(event);
+                } else {
+                    bump('v2RoutedAway');
+                }
+                continue;
+            }
             if (shouldDeliverPendingEventToCoordinator(validated, drainer)) {
                 ctx.batchSeen.add(eventId);
                 bump('v2Delivered');
@@ -838,6 +884,13 @@ export function stampPendingEventV2(
     });
     if (!stamp) return event; // no coordinator identity at all (no self id) → stays a v1 event
 
+    // Mark an ownerless (self-fallback) broadcast so the drain-side leak guard can
+    // tell it apart from a genuinely owned broadcast terminal event. selfFallback is
+    // true only when no coordinator identity existed and we minted the stamp under
+    // this daemon's own machineId; a broadcast that stays broadcast for that reason
+    // has no owner to leak from and must reach whatever coordinator drains here.
+    const dispatchedBySelfFallback = selfFallback && stamp.scope === 'broadcast';
+
     return {
         ...event,
         protocolVersion: stamp.protocolVersion,
@@ -845,6 +898,7 @@ export function stampPendingEventV2(
         scope: stamp.scope,
         dispatchedBy: stamp.dispatchedBy,
         ...(stamp.intendedFor ? { intendedFor: stamp.intendedFor } : {}),
+        ...(dispatchedBySelfFallback ? { dispatchedBySelfFallback: true } : {}),
     };
 }
 

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

@@ -76,17 +76,34 @@ export function getMeshWithCache(components: DaemonComponents, meshId: string):
  *
  * Fix: union the local-config nodes with any inline-cache-ONLY nodes, so the claim
  * view matches the command (send_task) view. Base (non-worktree) nodes present in
- * local config stay config-authoritative — their entry is taken verbatim from
- * localMesh, so base node claim/matching is byte-for-byte unchanged. Only nodes
+ * local config stay config-authoritative — their STATIC fields are taken verbatim
+ * from localMesh, so base node claim/matching is byte-for-byte unchanged. Only nodes
  * that exist solely in the inline cache (the cloned worktree nodes) are appended.
  * Identity comparison uses the shared 3-form normalizer (id / nodeId / node_id),
  * identical to every other claim-path consumer — the matching logic is untouched,
  * only which nodes are visible.
+ *
+ * BOOTSTRAP-DEFER VIEW-CONSISTENCY (this fix): for a worktree node that IS registered
+ * in local config, the union previously took the config node verbatim and discarded the
+ * inline-cache entry entirely. But the inline cache holds the FRESHER runtime bootstrap
+ * state — markWorktreeBootstrapTerminalState stamps worktreeBootstrap.status='complete'
+ * synchronously into the inline cache, while local config lags behind the detached async
+ * persist chain (and on the coordinator may never receive it at all). A config-registered
+ * 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.
  */
 function mergeInlineCacheOnlyNodes(localMesh: any, cachedMesh: any): any {
     const localNodes = Array.isArray(localMesh?.nodes) ? localMesh.nodes : [];
     const cachedNodes = Array.isArray(cachedMesh?.nodes) ? cachedMesh.nodes : [];
     if (!cachedNodes.length) return localMesh;
+    // Index inline-cache nodes by identity so we can (a) append cache-only nodes and
+    // (b) prefer the inline runtime bootstrap state on config-registered nodes.
     const cacheOnly = cachedNodes.filter((cachedNode: any) => {
         const cachedId = readMeshNodeId(cachedNode);
         // Unidentifiable cache entries can never be a claim/route target — skip them
@@ -94,8 +111,29 @@ function mergeInlineCacheOnlyNodes(localMesh: any, cachedMesh: any): any {
         if (!cachedId) return false;
         return !localNodes.some((localNode: any) => meshNodeIdMatches(localNode, cachedId));
     });
-    if (!cacheOnly.length) return localMesh;
-    return { ...localMesh, nodes: [...localNodes, ...cacheOnly] };
+    // 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.
+    let overlaidLocalNodes: any[] = localNodes;
+    let overlaid = false;
+    for (let i = 0; i < localNodes.length; i++) {
+        const localNode = localNodes[i];
+        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 (!overlaid) {
+            overlaidLocalNodes = [...localNodes];
+            overlaid = true;
+        }
+        // Keep the config node's static fields; prefer the inline cache's dynamic
+        // bootstrap runtime state (fresher terminal stamp).
+        overlaidLocalNodes[i] = { ...localNode, worktreeBootstrap: inlineMatch.worktreeBootstrap };
+    }
+    if (!cacheOnly.length && !overlaid) return localMesh;
+    return { ...localMesh, nodes: [...overlaidLocalNodes, ...cacheOnly] };
 }
 
 // ---------------------------------------------------------------------------
@@ -1880,6 +1918,8 @@ async function maybeAutoLaunchOneQueueSession(components: DaemonComponents, mesh
                             // 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() } : {}),
                         });
                     } catch (e: any) {
                         markAutoLaunch(meshId, task.id, { status: 'failed', reason: `remote_launch_dispatch_failed: ${e?.message || String(e)}`, nodeId, providerType: resolved.providerType });
@@ -1912,6 +1952,8 @@ async function maybeAutoLaunchOneQueueSession(components: DaemonComponents, mesh
                     // 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() } : {}),
                 });
                 if (!launchResult?.success) {
                     const reason = launchResult?.error || 'launch_cli_failed';

package/src/mesh/mesh-reconcile-loop.ts

@@ -679,6 +679,19 @@ const ASSIGNED_STRANDED_DEADLINE_MS = 5 * 60_000;
 // reclaimed out from under itself.
 const DELIVERED_NO_TURN_DEADLINE_MS = 15 * 60_000;
 
+// DELIVERED-NOT-CONSUMED (remote autoLaunch delivered≠consumed gap): how long a row may sit
+// 'assigned' with a CONFIRMED delivery ('delivered') that was never CONSUMED ('acked' — the
+// worker's agent:generating_started never arrived) before the watchdog re-drives it. Far shorter
+// than DELIVERED_NO_TURN_DEADLINE_MS (15min): a remote autoLaunch marks markAutoLaunch(completed)
+// and returns immediately, relying on agent:ready/reconcile to inject; if the launch→ready→claim
+// window (widened on win32 by the 3–4s git spawn latency) drops the inject, the row sits 'assigned'
+// but the delivery never flips past 'delivered' to 'acked'. The delivered-not-acked state is the
+// cross-daemon consumption signal — positive evidence the worker never started the turn — so we can
+// safely re-open the task after a SHORT grace (well above a normal generating_started round-trip so
+// a merely-slow start is never torn off) instead of waiting the full 15min turn budget. Floored
+// comfortably above the auto-launch cooldown so a legitimate late inject still has room to land.
+const ASSIGNED_DELIVERED_UNCONSUMED_REDRIVE_MS = 25_000;
+
 // RECLAIM-FALSEPOS: how many CONSECUTIVE UNKNOWN busy-verdict ticks (past the delivered-no-turn
 // deadline) must accumulate before a delivered row whose worker session cannot be positively
 // observed is reclaimed. An UNKNOWN verdict means the assigned session is not present in THIS
@@ -728,7 +741,62 @@ function recoverStrandedAssignedDispatches(components: DaemonComponents, meshId:
     for (const row of assigned) {
         const dispatchedAtMs = Date.parse(row.dispatchTimestamp ?? '');
         if (!Number.isFinite(dispatchedAtMs)) continue;              // no dispatch ts → can't age it
-        if (nowMs - dispatchedAtMs < ASSIGNED_STRANDED_DEADLINE_MS) continue;  // still in confirm window
+        const ageMs = nowMs - dispatchedAtMs;
+        // DELIVERED-NOT-CONSUMED short-grace re-drive (remote autoLaunch delivered≠consumed gap).
+        // Runs BEFORE the ASSIGNED_STRANDED_DEADLINE_MS confirm-window gate below because its whole
+        // point is to recover a delivered-but-unconsumed row well inside that window. A remote
+        // autoLaunch marks the dispatch delivered (transport acked) but the worker may never emit
+        // agent:generating_started — the delivery then sits 'delivered' and never flips to 'acked',
+        // so the task is stranded 'assigned' with no live turn. This branch re-opens exactly that
+        // row after a short grace:
+        //   - the delivery IS confirmed handed off (taskHasConfirmedDelivery) but was NEVER consumed
+        //     (!taskDeliveryConsumed → no 'acked'/'completed' delivery) — the cross-daemon "worker
+        //     never started the turn" signal, valid even for a REMOTE session whose local busy
+        //     verdict is UNKNOWN;
+        //   - AND the busy verdict is NOT GENERATING — a locally-present generating session IS
+        //     consuming (ack lost/late), so never touch it (regression guard against tearing a live
+        //     worker off its turn);
+        //   - AND no terminal ledger evidence exists (the completion already landed → leave it).
+        // reclaimStrandedAssignedTask returns the row to 'pending' (bounded by MAX_STRANDED_RECLAIMS)
+        // so PHASE 3 re-dispatches it this same tick onto a fresh idle session — idempotent: it only
+        // mutates a still-'assigned' row, so a completion/ack that raced in already moved the row off
+        // 'assigned' and this is a no-op.
+        if (
+            ageMs >= ASSIGNED_DELIVERED_UNCONSUMED_REDRIVE_MS
+            && ageMs < ASSIGNED_STRANDED_DEADLINE_MS
+            && store.taskHasConfirmedDelivery(meshId, row.id)
+            && !store.taskDeliveryConsumed(meshId, row.id)
+        ) {
+            const terminal = findTerminalLedgerEvidenceForTask({ meshId, taskId: row.id });
+            if (terminal) {
+                const status = terminal.kind === 'task_completed' ? 'completed' : 'failed';
+                updateTaskStatus(meshId, row.id, status);
+                continue;
+            }
+            const verdict = row.assignedSessionId
+                ? resolveSessionBusyVerdict(components, row.assignedSessionId)
+                : 'IDLE_CONFIRMED'; // no session bound → nothing live generating to protect
+            if (verdict !== 'GENERATING') {
+                const redriven = reclaimStrandedAssignedTask(meshId, row.id, {
+                    reason: 'delivered_not_consumed_redrive',
+                    ageMs,
+                });
+                if (redriven) {
+                    LOG.warn('MeshReconcile', `Re-drove delivered-but-unconsumed task ${row.id} on mesh ${meshId} `
+                        + `(node=${row.assignedNodeId ?? '?'} session=${row.assignedSessionId ?? '?'}, delivered but no `
+                        + `generating_started in ${Math.round(ageMs / 1000)}s, verdict ${verdict} → ${redriven.status})`);
+                    traceMeshEventDrop('assigned_delivered_not_consumed_redrive', {
+                        taskId: row.id,
+                        sessionId: row.assignedSessionId,
+                        nodeId: row.assignedNodeId,
+                        meshId,
+                        event: 'agent:generating_started',
+                    }, `delivered_not_consumed ${Math.round(ageMs / 1000)}s → ${redriven.status}`);
+                    continue;
+                }
+            }
+        }
+        if (ageMs < ASSIGNED_STRANDED_DEADLINE_MS) continue;  // still in confirm window
         const terminal = findTerminalLedgerEvidenceForTask({
             meshId,
             taskId: row.id,

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

@@ -1488,6 +1488,28 @@ export class MeshRuntimeStore {
         return !!row;
     }
 
+    /**
+     * DELIVERED-NOT-CONSUMED re-drive support: true when at least one delivery record for
+     * the task has reached a CONSUMED status ('acked' / 'completed'). Distinct from
+     * {@link taskHasConfirmedDelivery} ('delivered' | 'acked' | 'completed'): a delivery is
+     * flipped to 'delivered' the instant the transport hands the dispatch off, but only
+     * flipped to 'acked' when the worker's agent:generating_started event arrives (see the
+     * generating_started handler in mesh-event-forwarding) — i.e. when the session has
+     * actually begun the turn. That distinction is the cross-daemon consumption signal the
+     * short-grace re-drive uses: a row whose delivery is 'delivered' but never 'acked' was
+     * handed to a REMOTE worker that never started generating — the remote autoLaunch
+     * delivered≠consumed gap — even when the session's busy verdict is UNKNOWN (not locally
+     * observable). Indexed by (mesh_id, task_id).
+     */
+    taskDeliveryConsumed(meshId: string, taskId: string): boolean {
+        const row = this.db.prepare(`
+            SELECT 1 FROM mesh_session_delivery
+            WHERE mesh_id = ? AND task_id = ? AND status IN ('acked','completed')
+            LIMIT 1
+        `).get(meshId, taskId) as { 1: number } | undefined;
+        return !!row;
+    }
+
     expireStaleSessionDeliveries(meshId: string): void {
         const now = new Date().toISOString();
         this.db.prepare(`

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

@@ -3,13 +3,13 @@ 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';
+import { getMesh, getDifficultyBrains } from '../config/mesh-config.js';
 import { LOG } from '../logging/logger.js';
 import { appendLedgerEntry } from './mesh-ledger.js';
 import type { MeshLedgerKind } from './mesh-ledger.js';
 import { createSessionDelivery } from './mesh-delivery-policy.js';
 import { isTaskDispatchInFlight, endTaskDispatchInFlight } from './mesh-task-inflight.js';
-import { sessionIdsEquivalent } from '@adhdev/mesh-shared';
+import { sessionIdsEquivalent, isMeshTaskDifficulty, type MeshTaskDifficulty } from '@adhdev/mesh-shared';
 
 export type MeshTaskStatus = 'pending' | 'assigned' | 'completed' | 'failed' | 'cancelled';
 export type MeshActiveTaskStatus = Extract<MeshTaskStatus, 'pending' | 'assigned'>;
@@ -584,6 +584,13 @@ export interface MeshWorkQueueEntry {
      * that cannot honor the model still runs the task (never a fatal launch error).
      */
     model?: string;
+    /**
+     * BRAIN-ROUTING (thinking axis): standard reasoning level ('low'|'medium'|'high')
+     * for the session that executes this task. When the task auto-launches, this is
+     * passed to launch_cli as `initialThinkingLevel` (CLI → thinkingLaunchArgs; ACP →
+     * setConfigOption('thought_level')). Rides in payload JSON. Best-effort like model.
+     */
+    thinkingLevel?: 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;
@@ -862,6 +869,16 @@ export function enqueueTask(
         consensusGroupId?: string;
         /** MAGI-KIND-PANEL: model override forwarded to the executing session's launch (initialModel). */
         model?: string;
+        /** BRAIN-ROUTING: standard thinking level forwarded to launch (initialThinkingLevel). */
+        thinkingLevel?: string;
+        /**
+         * BRAIN-ROUTING: task execution difficulty ('easy'|'medium'|'difficult'|
+         * 'freeform'). When set, the mesh's difficulty→brain preset fills in model /
+         * thinkingLevel that were not passed explicitly (an explicit model/thinkingLevel
+         * wins). Purely a convenience resolver — the stored task still carries the
+         * resolved model/thinkingLevel, so downstream launch is unchanged.
+         */
+        difficulty?: string;
         /** Explicit task id for batch/template flows (M5). Random UUID when omitted. */
         id?: string;
         /** (3) Originating coordinator session id (for session-anchored completion routing). */
@@ -881,6 +898,21 @@ export function enqueueTask(
     const maxRetries = typeof opts?.maxRetries === 'number' && Number.isFinite(opts.maxRetries) && opts.maxRetries >= 0
         ? Math.floor(opts.maxRetries)
         : undefined;
+    // BRAIN-ROUTING: resolve the difficulty preset into effective model / thinking
+    // level. An explicit opts.model / opts.thinkingLevel always wins; the preset only
+    // fills what the caller left blank. Best-effort — a missing/invalid difficulty or
+    // 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;
+    if (isMeshTaskDifficulty(opts?.difficulty)) {
+        try {
+            const preset = getDifficultyBrains()[opts!.difficulty as MeshTaskDifficulty];
+            if (preset) {
+                if (!effectiveModel && preset.model) effectiveModel = preset.model;
+                if (!effectiveThinkingLevel && preset.thinkingLevel) effectiveThinkingLevel = preset.thinkingLevel;
+            }
+        } catch { /* preset read is best-effort — never block enqueue */ }
+    }
     const result = withQueueLock(meshId, () => {
         if (MeshRuntimeStore.getInstance().findQueueEntryById(meshId, id)) {
             throw new Error(`duplicate_task_id: task '${id}' already exists in mesh '${meshId}'`);
@@ -917,7 +949,8 @@ export function enqueueTask(
             ...(maxRetries !== undefined ? { maxRetries } : {}),
             ...(typeof opts?.missionId === 'string' && opts.missionId.trim() ? { missionId: opts.missionId.trim() } : {}),
             ...(typeof opts?.consensusGroupId === 'string' && opts.consensusGroupId.trim() ? { consensusGroupId: opts.consensusGroupId.trim() } : {}),
-            ...(typeof opts?.model === 'string' && opts.model.trim() ? { model: opts.model.trim() } : {}),
+            ...(effectiveModel ? { model: effectiveModel } : {}),
+            ...(effectiveThinkingLevel ? { thinkingLevel: effectiveThinkingLevel } : {}),
             ...(typeof opts?.sourceCoordinatorSessionId === 'string' && opts.sourceCoordinatorSessionId.trim()
                 ? { sourceCoordinatorSessionId: opts.sourceCoordinatorSessionId.trim() }
                 : {}),

package/src/providers/cli-provider-instance.ts

@@ -312,6 +312,7 @@ export class CliProviderInstance implements ProviderInstance {
     private presentationMode: 'terminal' | 'chat';
     private providerSessionId?: string;
     private launchMode: 'new' | 'resume' | 'manual';
+    private initialThinkingLevel?: string;
     private readonly startedAt = Date.now();
     private onProviderSessionResolved?: (info: {
         instanceId: string;
@@ -332,6 +333,10 @@ export class CliProviderInstance implements ProviderInstance {
             providerSessionId?: string;
             launchMode?: 'new' | 'resume' | 'manual';
             extraEnv?: Record<string, string>;
+            /** BRAIN-ROUTING: standard thinking level to apply post-launch via the
+             *  provider's thinkingControlId (runtime-control providers like hermes).
+             *  Providers using thinkingLaunchArgs get it at spawn instead and ignore this. */
+            initialThinkingLevel?: string;
             onProviderSessionResolved?: (info: {
                 instanceId: string;
                 providerType: string;
@@ -347,6 +352,7 @@ export class CliProviderInstance implements ProviderInstance {
         this.presentationMode = 'chat';
         this.providerSessionId = options?.providerSessionId;
         this.launchMode = options?.launchMode || 'new';
+        this.initialThinkingLevel = options?.initialThinkingLevel;
         this.onProviderSessionResolved = options?.onProviderSessionResolved;
         this.adapter = createCliAdapter(provider as CliProviderModule, workingDir, cliArgs, options?.extraEnv || {}, transportFactory) as ProviderCliAdapter;
         if (this.providerSessionId) {
@@ -392,6 +398,7 @@ export class CliProviderInstance implements ProviderInstance {
  // PTY spawn
         await this.adapter.spawn();
         await this.enforceFreshSessionLaunchIfNeeded();
+        await this.applyInitialThinkingLevelViaControl();
         this.maybeAppendRuntimeRecoveryMessage(this.adapter.getRuntimeMetadata());
         if (this.providerSessionId && this.shouldHydrateExistingProviderHistory()) {
             this.restorePersistedHistoryFromCurrentSession();
@@ -1209,6 +1216,45 @@ export class CliProviderInstance implements ProviderInstance {
         this.applyProviderResponse(parsed.payload, { phase: 'immediate' });
     }
 
+    /**
+     * BRAIN-ROUTING (runtime-control thinking axis): for a provider that selects
+     * reasoning effort via a runtime control instead of a launch arg (e.g. hermes
+     * `reasoning`), apply the requested initialThinkingLevel after spawn by invoking
+     * that control's setScript. The provider names the control via thinkingControlId.
+     * The standard level is mapped through thinkingLevelMap first (same as the
+     * launch-arg path). Best-effort: any failure logs and never blocks launch.
+     */
+    private async applyInitialThinkingLevelViaControl(): Promise<void> {
+        const level = typeof this.initialThinkingLevel === 'string' ? this.initialThinkingLevel.trim() : '';
+        if (!level) return;
+        const controlId = (this.provider as any).thinkingControlId;
+        if (!controlId) return; // provider uses thinkingLaunchArgs (or has no support)
+        const controls: any[] = Array.isArray((this.provider as any).controls) ? (this.provider as any).controls : [];
+        const control = controls.find(c => c && c.id === controlId);
+        if (!control || !control.setScript) return;
+        // Map the standard level to the provider's own vocabulary (unchanged if absent).
+        const map = (this.provider as any).thinkingLevelMap as Record<string, string> | undefined;
+        const mapped = (map && typeof map[level] === 'string' && map[level].trim()) ? map[level].trim() : level;
+        try {
+            await waitForCliAdapterReady(this.adapter);
+            const raw = await this.adapter.invokeScript(control.setScript, { value: mapped });
+            const parsed = parseCliScriptResult(raw);
+            if (!parsed.success) {
+                LOG.warn('CLI', `[${this.type}] thinking control '${controlId}' set to '${mapped}' failed: ${parsed.payload?.error || 'unknown'}`);
+                return;
+            }
+            const cliCommand = getCliScriptCommand(parsed.payload);
+            if (cliCommand?.type === 'send_message' && cliCommand.text) {
+                await this.adapter.sendMessage(cliCommand.text);
+            } else if (cliCommand?.type === 'pty_write' && cliCommand.text) {
+                await this.adapter.writeRaw(cliCommand.text + '\r');
+            }
+            LOG.info('CLI', `[${this.type}] applied thinking level '${mapped}' via control '${controlId}'`);
+        } catch (e: any) {
+            LOG.warn('CLI', `[${this.type}] thinking control apply threw: ${e?.message || e}`);
+        }
+    }
+
     private completionHasFinalAssistantMessage(messages: unknown, turnStartedAt?: number): boolean {
         const visibleMessages = (Array.isArray(messages) ? messages : [])
             .filter((message: any) => isUserFacingChatMessage(message as ChatMessage));