@adhdev/daemon-core 0.9.82-rc.481 → 0.9.82-rc.483

package/src/config/mesh-config.ts

@@ -22,7 +22,7 @@ import type {
     RepoMeshHostMetadata,
     RepoMeshDaemonRole,
 } from '../repo-mesh-types.js';
-import type { MagiPanel, MagiPanelMember, MagiPanelDefaultKind, MagiKindPanelMap, MagiSlot, MagiTaskKind } from '@adhdev/mesh-shared';
+import type { MagiKindPanelMap, MagiSlot, MagiTaskKind } from '@adhdev/mesh-shared';
 import { mergeAndNormalizePolicy } from '../repo-mesh-types.js';
 import { createDefaultMeshHostMetadata } from '../mesh/mesh-host-ownership.js';
 
@@ -570,6 +570,11 @@ export function updateNode(
     opts: {
         userOverrides?: Partial<RepoMeshNodeCapabilities>;
         policy?: RepoMeshNodePolicy;
+        /** Operator-defined custom capability tags used by mesh queue matching.
+         *  Passing an array replaces the node's custom tags (empty/whitespace
+         *  entries dropped, deduped); an empty result clears them. Omit to leave
+         *  the existing tags untouched. */
+        capabilities?: string[];
         worktreeBootstrap?: LocalMeshNodeEntry['worktreeBootstrap'];
         /** Per-node instruction surfaced in the coordinator prompt. Pass an
          *  empty string or undefined to clear it. */
@@ -610,6 +615,13 @@ export function updateNode(
         node.reportedDaemonBuildVersion = opts.reportedDaemonBuildVersion.trim();
     }
     if (opts.policy) node.policy = { ...node.policy, ...opts.policy };
+    if (Object.prototype.hasOwnProperty.call(opts, 'capabilities')) {
+        // Explicit replace: normalize (trim/dedup/drop-empties); an empty result
+        // clears the tags entirely so the field never persists as [].
+        const tags = normalizeCapabilityTags(opts.capabilities);
+        if (tags && tags.length) node.capabilities = tags;
+        else delete node.capabilities;
+    }
     if (opts.worktreeBootstrap) node.worktreeBootstrap = opts.worktreeBootstrap;
     if (Object.prototype.hasOwnProperty.call(opts, 'systemPrompt')) {
         // Honor explicit clears: { systemPrompt: undefined } drops the field.
@@ -626,8 +638,10 @@ export function updateNode(
 
 // ─── MAGI Panels (machine-local cross-verification quorums) ──
 
-/** Hard cap on members per panel — a sanity bound, not the per-invocation replica cap. */
-const MAX_MAGI_PANEL_MEMBERS = 24;
+// NOTE: the named-panel model (normalizeMagiPanel / list / get / upsert / remove,
+// stored under meshes.json `magiPanels`) was REMOVED. MAGI now resolves its fan-out
+// slots SOLELY from the per-task_kind `magiKindPanels` binding below. `normalizeMagiSlots`
+// is the sole slot normalizer.
 
 function normalizeReplicaCount(value: unknown): number | undefined {
     if (typeof value !== 'number' || !Number.isFinite(value)) return undefined;
@@ -635,138 +649,6 @@ function normalizeReplicaCount(value: unknown): number | undefined {
     return n >= 1 ? n : undefined;
 }
 
-/**
- * Normalize a panel `defaultKind` (the non-binding default output kind). Returns
- * undefined (drop, don't throw) for any absent / unknown value so a stray field
- * never blocks a panel write. 'freeform' is explicitly DROPPED with a warning: a
- * panel is a cross-verification tool and freeform contributes no structured claims
- * (claims:[]), so defaulting to it would silently zero out the very thing the panel
- * exists for. Only the evidence-bearing kinds (claim_audit / rca / design) survive.
- */
-function normalizeMagiPanelDefaultKind(raw: unknown): MagiPanelDefaultKind | undefined {
-    if (raw == null) return undefined;
-    const s = typeof raw === 'string' ? raw.trim().toLowerCase() : '';
-    if (s === 'claim_audit' || s === 'rca' || s === 'design') return s;
-    if (s === 'freeform') {
-        // eslint-disable-next-line no-console
-        console.warn(
-            "[magi] panel defaultKind='freeform' rejected — freeform contributes no structured claims to cross-verification; dropping (use claim_audit / rca / design, or omit).",
-        );
-        return undefined;
-    }
-    // Any other value (typo / unsupported kind): drop silently — the panel still
-    // resolves to the claim_audit fallback at review time.
-    return undefined;
-}
-
-/**
- * Validate + normalize a panel config before persisting. Mirrors the node-config
- * normalization style (mesh-config addNode/updateNode): trims strings, drops
- * empties, requires a provider per member, clamps replica counts. Throws on
- * structurally invalid input so the calling tool returns a clear error rather than
- * writing a malformed panel.
- */
-export function normalizeMagiPanel(config: unknown): MagiPanel {
-    if (!config || typeof config !== 'object' || Array.isArray(config)) {
-        throw new Error('invalid_magi_panel: config must be an object');
-    }
-    const raw = config as Record<string, unknown>;
-    const rawMembers = raw.members;
-    if (!Array.isArray(rawMembers) || rawMembers.length === 0) {
-        throw new Error('invalid_magi_panel: members must be a non-empty array');
-    }
-    if (rawMembers.length > MAX_MAGI_PANEL_MEMBERS) {
-        throw new Error(`invalid_magi_panel: too many members (max ${MAX_MAGI_PANEL_MEMBERS})`);
-    }
-    const members: MagiPanelMember[] = rawMembers.map((entry, idx) => {
-        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
-            throw new Error(`invalid_magi_panel: member[${idx}] must be an object`);
-        }
-        const m = entry as Record<string, unknown>;
-        const provider = typeof m.provider === 'string' ? m.provider.trim() : '';
-        if (!provider) {
-            throw new Error(`invalid_magi_panel: member[${idx}].provider is required`);
-        }
-        const nodeId = typeof m.nodeId === 'string' && m.nodeId.trim() ? m.nodeId.trim() : undefined;
-        const model = typeof m.model === 'string' && m.model.trim() ? m.model.trim() : undefined;
-        const capabilityTags = normalizeCapabilityTags(m.capabilityTags);
-        const n = normalizeReplicaCount(m.n);
-        return {
-            provider,
-            ...(nodeId ? { nodeId } : {}),
-            ...(model ? { model } : {}),
-            ...(capabilityTags ? { capabilityTags } : {}),
-            ...(n !== undefined ? { n } : {}),
-        };
-    });
-    const description = typeof raw.description === 'string' && raw.description.trim()
-        ? raw.description.trim().slice(0, 200)
-        : undefined;
-    const defaultN = normalizeReplicaCount(raw.defaultN);
-    const defaultKind = normalizeMagiPanelDefaultKind(raw.defaultKind);
-    return {
-        ...(description ? { description } : {}),
-        members,
-        ...(defaultN !== undefined ? { defaultN } : {}),
-        ...(defaultKind !== undefined ? { defaultKind } : {}),
-        // dedupExempt is always meaningful for a MAGI panel (intentional same-prompt
-        // fan-out). Persist it true unless the caller explicitly disables it.
-        dedupExempt: raw.dedupExempt === false ? false : true,
-    };
-}
-
-function normalizePanelName(name: unknown): string {
-    const trimmed = typeof name === 'string' ? name.trim() : '';
-    if (!trimmed) throw new Error('invalid_magi_panel: panel name is required');
-    return trimmed.slice(0, 100);
-}
-
-/** All configured MAGI panels (machine-local), keyed by name. Empty when none. */
-export function listMagiPanels(): Record<string, MagiPanel> {
-    return loadMeshConfig().magiPanels ?? {};
-}
-
-/** A single panel by name, or undefined when not configured. */
-export function getMagiPanel(name: string): MagiPanel | undefined {
-    const key = typeof name === 'string' ? name.trim() : '';
-    if (!key) return undefined;
-    return loadMeshConfig().magiPanels?.[key];
-}
-
-/**
- * Upsert a named panel into meshes.json. Defaults to refusing to clobber an
- * existing panel (overwrite=false) — mirrors the mesh_init write/overwrite
- * precedent. Returns the normalized, persisted panel.
- */
-export function upsertMagiPanel(
-    name: string,
-    config: unknown,
-    opts: { overwrite?: boolean } = {},
-): MagiPanel {
-    const key = normalizePanelName(name);
-    const panel = normalizeMagiPanel(config);
-    const stored = loadMeshConfig();
-    const panels = stored.magiPanels ?? {};
-    if (panels[key] && opts.overwrite !== true) {
-        throw new Error(`magi_panel_exists: panel '${key}' already exists — pass overwrite=true to replace it`);
-    }
-    panels[key] = panel;
-    stored.magiPanels = panels;
-    saveMeshConfig(stored);
-    return panel;
-}
-
-/** Remove a named panel. Returns true when a panel was removed. */
-export function removeMagiPanel(name: string): boolean {
-    const key = typeof name === 'string' ? name.trim() : '';
-    if (!key) return false;
-    const stored = loadMeshConfig();
-    if (!stored.magiPanels || !stored.magiPanels[key]) return false;
-    delete stored.magiPanels[key];
-    saveMeshConfig(stored);
-    return true;
-}
-
 // ─── MAGI kind → panel bindings (MAGI-KIND-PANEL) ─────────
 //
 // Per-task_kind slot lists (machine-local, meshes.json `magiKindPanels`). A bare
@@ -788,11 +670,10 @@ function normalizeMagiTaskKindKey(raw: unknown): MagiTaskKind {
 }
 
 /**
- * Validate + normalize a kind-panel's slots. Mirrors normalizeMagiPanel's member
- * normalization: provider required per slot, trims strings, drops empties, clamps
- * replica counts, and additionally carries an optional per-slot `model`. Throws on
- * structurally invalid input (empty list / no provider) so the write returns a clear
- * error. Returns the normalized slot array.
+ * Validate + normalize a kind-panel's slots (the SOLE MAGI slot normalizer): provider
+ * required per slot, trims strings, drops empties, clamps replica counts, and carries
+ * an optional per-slot `model`. Throws on structurally invalid input (empty list / no
+ * provider) so the write returns a clear error. Returns the normalized slot array.
  */
 export function normalizeMagiSlots(slots: unknown): MagiSlot[] {
     if (!Array.isArray(slots) || slots.length === 0) {

package/src/index.ts

@@ -195,7 +195,6 @@ export type { SavedProviderSessionEntry } from './config/saved-sessions.js';
 export {
   listMeshes, getMesh, getMeshByRepo, createMesh, updateMesh, deleteMesh,
   addNode, removeNode, updateNode, normalizeRepoIdentity,
-  listMagiPanels, getMagiPanel, upsertMagiPanel, removeMagiPanel, normalizeMagiPanel,
   listMagiKindPanels, getMagiKindPanel, setMagiKindPanel, removeMagiKindPanel, normalizeMagiSlots,
 } from './config/mesh-config.js';
 export type { CreateMeshOptions, UpdateMeshOptions, AddNodeOptions } from './config/mesh-config.js';
@@ -203,7 +202,7 @@ export type { CreateMeshOptions, UpdateMeshOptions, AddNodeOptions } from './con
 // leaf so the mcp-server — which depends only on @adhdev/daemon-core — can consume
 // them without taking a direct @adhdev/mesh-shared dependency).
 export type {
-  MagiPanel, MagiPanelMember, MagiPanelMap, MagiMode, MagiTaskKind, MagiPanelDefaultKind,
+  MagiMode, MagiTaskKind,
   MagiSlot, MagiKindPanelMap,
   MagiClaim, MagiClaimStance, MagiAgentResponse,
   MagiResponseSource, MagiReplicaGitRef, MagiGitSkew, MagiSynthesizedResponse,

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.
  *
@@ -368,25 +373,43 @@ const TERMINAL_TASK_EVENTS: ReadonlySet<string> = new Set([
 ]);
 
 /**
- * Infrastructure/system events that no coordinator should surface — ledger
- * consistency and dispatch-plane signals. Delivered to the daemon-level handler
- * only (scope 'system').
+ * 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).
  */
-const SYSTEM_EVENTS: ReadonlySet<string> = new Set([
+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
+ * ORIGINATING coordinator (it carries a why+how coordinatorMessage and is
+ * targetCoordinator*-addressed by its producer), so it routes unicast exactly
+ * like a terminal task event. B2a originally classed it 'system' — that made it
+ * a dead letter: no daemon-level system drain exists, so the blocker never
+ * reached any coordinator and the task sat silently undispatched.
+ */
+const COORDINATOR_ALERT_EVENTS: ReadonlySet<string> = new Set([
   'mesh:dispatch_blocked',
 ]);
 
 /**
  * Default the v2 scope for an event by its producer event name (design decision
- * §3). Terminal task events → unicast (routed to the originating coordinator).
- * Ledger-consistency / dispatch-plane events → system. Everything else — node
- * lifecycle and progress signals — → broadcast, which also matches v1's
- * implicit "deliver to any coordinator" behaviour, so an unstamped v1 event and
- * a v2-stamped-as-broadcast event route identically during rollout.
+ * §3). Terminal task events and coordinator-addressed alerts → unicast (routed
+ * to the originating coordinator). Everything else — node lifecycle and
+ * progress signals — → broadcast, which also matches v1's implicit "deliver to
+ * any coordinator" behaviour, so an unstamped v1 event and a v2-stamped-as-
+ * broadcast event route identically during rollout. No event currently defaults
+ * to 'system'; the scope remains in MESH_EVENT_SCOPES for wire compatibility
+ * (an already-queued or version-skewed 'system' event still routes away from
+ * coordinators).
  */
 export function defaultScopeForEvent(eventName: string): MeshEventScope {
-  if (SYSTEM_EVENTS.has(eventName)) return 'system';
-  if (TERMINAL_TASK_EVENTS.has(eventName)) return 'unicast';
+  if (TERMINAL_TASK_EVENTS.has(eventName) || COORDINATOR_ALERT_EVENTS.has(eventName)) return 'unicast';
   return 'broadcast';
 }
 
@@ -439,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;
@@ -454,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

@@ -454,6 +454,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, '     ')}`);
@@ -649,9 +666,7 @@ const TOOLS_SECTION = `## Available Tools
 | \`mesh_write_mesh_json_config\` | Gated write of \`.adhdev/mesh.json\` (repo coordinator-prompt config) from the mesh entry — dry-run/overwrite like mesh_init |
 | \`mesh_magi_review\` | Cross-verify a read-only investigation across a standing panel of independent mesh agents (different machines/providers) instead of a single worker |
 | \`mesh_magi_collect\` | Collect + synthesize a previously dispatched MAGI fan-out by its consensus group id (async companion to mesh_magi_review wait:false) |
-| \`mesh_magi_panel_set\` | Upsert a named MAGI panel (standing set of independent node×provider members) into machine-local config |
-| \`mesh_magi_panel_list\` | List configured MAGI panels and resolve each member's availability against the current mesh (read-only) |
-| \`mesh_magi_kind_panel_set\` | Bind a task_kind → MAGI kind-panel slots (machine-local, wholesale replacement — approve current-vs-new first) |
+| \`mesh_magi_kind_panel_set\` | Bind a task_kind → MAGI kind-panel slots (the SOLE MAGI panel-resolution surface; machine-local, wholesale replacement — approve current-vs-new first) |
 | \`mesh_magi_kind_panel_list\` | List configured task_kind → MAGI kind-panel slot bindings (machine-local, read-only) |`;
 
 const TOOL_EXPOSURE_PREFLIGHT_SECTION = `## Tool Exposure Preflight
@@ -665,6 +680,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.
@@ -694,7 +710,7 @@ When the user asks to **set up / configure / onboard** this repo for Repo Mesh (
 
 **Save scopes — label every draft with its scope before asking for approval:**
 - **repo-file (commit target)** — \`.adhdev/refine.json\`, \`.adhdev/worktree_bootstrap.json\`, \`.adhdev/change-impact.json\`, \`.adhdev/mesh.json\`. These are committed to the repository and shared with every machine/contributor.
-- **machine-local** — MAGI kind→panel bindings and named MAGI panels, node providerPriority (\`~/.adhdev/meshes.json\`). These stay on this machine and are NOT committed.
+- **machine-local** — MAGI kind→panel bindings, node providerPriority (\`~/.adhdev/meshes.json\`). These stay on this machine and are NOT committed.
 
 **Guided sequence:**
 1. **Scan (dry-run)** — Call \`mesh_init\` (write=false, the default). It returns per-domain suggested configs for refine / worktree_bootstrap / change-impact, a recommended providerPriority, AND \`currentConfig\` — the currently-saved config per domain (repo files + machine-local \`magiKindPanels\`). Nothing is written.
@@ -702,8 +718,7 @@ When the user asks to **set up / configure / onboard** this repo for Repo Mesh (
 3. **Approve → gated write** — Only after the user approves, call the matching gated-write tool:
    - repo \`.adhdev/*\` config files → \`mesh_init\` with \`write=true\` (and \`overwrite=true\` ONLY for domains the user approved replacing).
    - \`.adhdev/mesh.json\` (coordinator prompt / operating notes) → \`mesh_write_mesh_json_config\` (write=true, overwrite only if approved).
-   - machine-local MAGI kind→panel slots → \`mesh_magi_kind_panel_set\` (write=true). NOTE: a kind binding is a **wholesale replacement** of that kind's slot list — present the current-vs-new slots first.
-   - machine-local named MAGI panels → \`mesh_magi_panel_set\`. providerPriority → apply via node policy update.
+   - machine-local MAGI kind→panel slots → \`mesh_magi_kind_panel_set\` (write=true). NOTE: a kind binding is a **wholesale replacement** of that kind's slot list — present the current-vs-new slots first. providerPriority → apply via node policy update.
 
 **init vs reinit:**
 - **\`mesh_init\`** — for a fresh, never-onboarded repo. Existing config files are kept (existing-wins) unless the user explicitly approves overwrite. Use for first-time setup.
@@ -721,6 +736,7 @@ 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.
 - **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-event-forwarding.ts

@@ -6,12 +6,12 @@ import { appendLedgerEntry, buildTaskCompletionEvidence, getSessionRecoveryConte
 import type { SessionRecoveryContext } from './mesh-ledger.js';
 import { updateSessionTaskStatus, enqueueTask, updateDirectDispatchStatus, cleanupTerminalDirectDispatches, getActiveDirectDispatches, hasPendingDependents, getQueue } from './mesh-work-queue.js';
 import { markSessionDeliveriesTerminal, updateSessionDeliveryStatus } from './mesh-delivery-policy.js';
-import { MeshRuntimeStore } from './mesh-runtime-store.js';
+import { MeshRuntimeStore, pruneMeshRuntimeRetention } from './mesh-runtime-store.js';
 import { queuePendingMeshCoordinatorEvent, drainPendingMeshCoordinatorEvents, prunePendingMeshCoordinatorEventsRetention, readV2EnvelopeFromWire, type PendingMeshCoordinatorEvent } from './mesh-events-pending.js';
 import type { ProviderInstance } from '../providers/provider-instance.js';
 import { resolveWorkerDelegateRouting, recordUnroutableDelegateEvent, isUnroutableDelegateRejection } from './mesh-routing.js';
 import { resolveMeshHostStatus } from './mesh-host-ownership.js';
-import { enqueueUnresolvedDelegateForward, peekUnresolvedDelegateForwards, ackUnresolvedDelegateForward } from './mesh-unresolved-forward-outbox.js';
+import { enqueueUnresolvedDelegateForward, nudgeUnresolvedForwardRetry } from './mesh-unresolved-forward-outbox.js';
 import { traceMeshEventStage, traceMeshEventDrop } from './mesh-event-trace.js';
 import { getLastDisplayMessage } from '../status/snapshot.js';
 import { resolveDelegatedWorkerAutoApprove } from '../repo-mesh-types.js';
@@ -189,13 +189,16 @@ function sweepExpiredRemoteIdleSessions(): void {
     try {
         MeshRuntimeStore.getInstance().pruneExpiredRemoteIdleSessions();
     } catch { /* best-effort */ }
-    // Piggyback the pending-event retention prune on the same periodic sweep, but
-    // hourly — this is the maintenance hook that keeps mesh_pending_events from
-    // accumulating stale drained/orphaned rows without bound.
+    // Piggyback the retention prunes on the same periodic sweep, but hourly — this
+    // is the maintenance hook that keeps mesh-runtime.db from accumulating stale
+    // rows without bound: mesh_pending_events (drained/orphaned rows) plus, on the
+    // SAME cadence (SoT 1-11 (b)), the event ledger / tool-call log / terminal
+    // queue retention in pruneMeshRuntimeRetention.
     const now = Date.now();
     if (now - lastPendingEventsPruneAt >= PENDING_EVENTS_PRUNE_INTERVAL_MS) {
         lastPendingEventsPruneAt = now;
         prunePendingMeshCoordinatorEventsRetention();
+        pruneMeshRuntimeRetention();
     }
 }
 
@@ -1591,43 +1594,6 @@ export function handleMeshForwardEvent(components: DaemonComponents, payload: Re
     });
 }
 
-// ---------------------------------------------------------------------------
-// Per-coordinator forward serialization (P2P send-backpressure relief).
-//
-// When several workers finish at once, each completion runs forwardUnresolvedDelegate
-// Event and fires its own `mesh_forward_event` push. Firing the whole burst
-// concurrently dumps it into the single per-peer P2P DataChannel buffer in one tick,
-// which starves the rpc_ack/rpc_res replies the same channel must carry — a
-// coordinator's inbound `git_status` then times out even though the worker's own
-// forward acks return in ~1s. To cap the concurrent burst we serialize the immediate
-// pushes per coordinator: at most one push is in flight to a given coordinator at a
-// time, the rest run in arrival order behind it. A lone event (idle lane) still
-// dispatches immediately — only a genuine burst is paced. Durability is unchanged:
-// every event is already persisted to the outbox before the push runs, so serializing
-// only delays the best-effort fast path; PHASE 0 retry still covers any gap. This pairs
-// with the DataChannel send-buffer gate in daemon-cloud's mesh manager (writeRequest),
-// which is the hard guarantee; this throttle keeps the burst from piling up there.
-interface CoordinatorForwardLane { tail: Promise<unknown>; depth: number; }
-const coordinatorForwardLanes = new Map<string, CoordinatorForwardLane>();
-function enqueueCoordinatorForwardPush(coordinatorDaemonId: string, run: () => Promise<unknown>): void {
-    let lane = coordinatorForwardLanes.get(coordinatorDaemonId);
-    if (!lane) { lane = { tail: Promise.resolve(), depth: 0 }; coordinatorForwardLanes.set(coordinatorDaemonId, lane); }
-    const wasIdle = lane.depth === 0;
-    lane.depth += 1;
-    const dec = (): void => { lane!.depth -= 1; };
-    if (wasIdle) {
-        // Idle lane → dispatch synchronously, so a lone completion (the common case) has
-        // ZERO added latency and the push call happens in-line. Only a genuine burst —
-        // events arriving while a push is still in flight — is paced (else branch).
-        lane.tail = Promise.resolve(run()).catch(() => {}).then(dec, dec);
-    } else {
-        // Burst: queue behind the in-flight push(es) in arrival order so the whole burst
-        // is not dumped into the shared DataChannel buffer at once. The tail is guarded
-        // so one rejecting push never wedges the lane for the next.
-        lane.tail = lane.tail.then(() => run()).catch(() => {}).then(dec, dec);
-    }
-}
-
 // ---------------------------------------------------------------------------
 // Worker-side fallback forward for unresolved-mesh delegates.
 //
@@ -1641,8 +1607,9 @@ function enqueueCoordinatorForwardPush(coordinatorDaemonId: string, run: () => P
 // the worker's queue — which it can't, because the worker never queued an unroutable
 // event. Live symptom: `WARN [MeshEvents] delivery_unroutable: ... mesh unresolved`.
 //
-// The fix: the routing object still carries coordinatorDaemonId. Forward the raw event
-// straight to that coordinator daemon over P2P (mesh_forward_event). The coordinator
+// The fix: the routing object still carries coordinatorDaemonId. Persist the raw event
+// to the durable worker-side outbox addressed to that coordinator daemon; the reconcile
+// loop's PHASE 0 delivers it (mesh_forward_event, acked, retry-capped). The coordinator
 // hosts the mesh, so it recovers the mesh id by workspace in handleMeshForwardEvent and
 // injects/queues it normally. meshId is intentionally omitted from the payload (the
 // worker has none); workspace is the routing anchor the coordinator resolves from.
@@ -1656,14 +1623,17 @@ function enqueueCoordinatorForwardPush(coordinatorDaemonId: string, run: () => P
 //
 // Returns true when the event was durably accepted for delivery to the coordinator
 // daemon (so the caller skips the delivery_unroutable diagnostic); false when no
-// fallback was possible (no coordinator anchor / no dispatch transport).
+// fallback was possible (no coordinator anchor / no dispatch transport) OR the durable
+// enqueue itself failed — the delivery_unroutable diagnostic is thereby narrowed to
+// "could not even persist to the queue" (a real potential loss), per the polling-
+// single-model design (docs/refactoring/2026-06-16-mesh-completion-polling-single-model.md §2.1/§2.6).
 //
-// Durability: the directed push to the coordinator is the ONLY delivery route for an
-// unresolved-mesh worker (it is in no mesh.node the coordinator can pull). So instead
-// of a fire-and-forget push that drops on one transient P2P failure, the event is
-// persisted to the worker-side outbox FIRST and only acked after a successful push.
-// A best-effort immediate push keeps latency low on the happy path; a failed or
-// un-acked push leaves the durable row for setupMeshReconcileLoop's PHASE 0 to retry.
+// Single delivery path (polling single-model): the spontaneous best-effort immediate
+// push that used to run here was REMOVED. Every unresolved-delegate event is persisted
+// to the outbox and delivered ONLY by setupMeshReconcileLoop's PHASE 0 retry (acked;
+// a failed push leaves the row queued). For happy-path latency the enqueue emits a
+// data-free reconcile NUDGE (nudgeUnresolvedForwardRetry) asking the loop to run the
+// retry soon; a lost nudge costs at most one reconcile interval, never the event.
 function forwardUnresolvedDelegateEvent(
     components: DaemonComponents,
     routing: ReturnType<typeof resolveWorkerDelegateRouting>,
@@ -1718,10 +1688,11 @@ function forwardUnresolvedDelegateEvent(
         return true;
     }
 
-    // 1) Persist durably FIRST. Idempotent on fingerprint, so a re-fired completion
-    //    does not duplicate the outbox row. If persistence fails we still attempt the
-    //    push below (degrades to the old at-most-once behaviour rather than dropping
-    //    the chance entirely).
+    // Persist durably. Idempotent on fingerprint, so a re-fired completion does not
+    // duplicate the outbox row. The outbox is the ONLY delivery route now (no
+    // spontaneous push), so a hard persistence failure means the event has nowhere to
+    // live — return false so the caller records the delivery_unroutable diagnostic,
+    // which is thereby narrowed to exactly this "could not even enqueue" real-loss case.
     const persisted = enqueueUnresolvedDelegateForward(coordinatorDaemonId, eventName, payload);
     // EVTTRACE: unresolved-mesh worker persisted its completion to the outbox (no meshId
     // available locally; coordinator will recover it on receive).
@@ -1731,56 +1702,21 @@ function forwardUnresolvedDelegateEvent(
         nodeId: readNonEmptyString(routing.nodeId) || readNonEmptyString(event.meshNodeId),
         event: eventName,
     };
-    traceMeshEventStage('outbox_enqueue', fwdTraceCtx, `coordinatorDaemon=${coordinatorDaemonId} meshId=absent`);
-
-    // 2) Best-effort immediate push for low latency. On success, ack the outbox row so
-    //    the retry loop won't re-send it. On failure, leave it queued — PHASE 0 retries.
-    traceMeshEventStage('forward_send', fwdTraceCtx, 'immediate push');
-    // Serialize per coordinator so a multi-worker completion burst is paced rather than
-    // dumped concurrently into the shared P2P DataChannel buffer (see coordinator
-    // ForwardLanes). dispatchMeshCommand was null-checked above; capture it for the
-    // deferred closure.
-    const dispatchMeshCommand = components.dispatchMeshCommand;
-    enqueueCoordinatorForwardPush(coordinatorDaemonId, () =>
-        Promise.resolve(dispatchMeshCommand(coordinatorDaemonId, 'mesh_forward_event', payload))
-            .then((result: any) => {
-                if (result && result.success === false) {
-                    LOG.warn('MeshEvents', `Immediate forward of ${eventName} to coordinator ${coordinatorDaemonId} rejected (${readNonEmptyString(result.error) || 'no reason'}) — left queued for retry`);
-                    traceMeshEventDrop('immediate_forward_rejected', fwdTraceCtx, readNonEmptyString(result.error) || 'no reason');
-                    return;
-                }
-                // Acked. Mark the durable copy delivered so the retry loop skips it.
-                if (persisted) ackUnresolvedDelegateForwardByFingerprint(coordinatorDaemonId, eventName, payload);
-            })
-            .catch((e: any) => {
-                // Coordinator momentarily unreachable; the durable row stays queued and the
-                // reconcile loop retries it. Trace so the relay attempt is visible.
-                LOG.warn('MeshEvents', `Immediate forward of ${eventName} to coordinator ${coordinatorDaemonId} failed: ${e?.message || e} — left queued for retry`);
-            }));
-    LOG.info('MeshEvents', `Durably forwarded ${eventName} for unresolved-mesh worker at ${routing.workspace || '(no workspace)'} to coordinator daemon ${coordinatorDaemonId}`);
+    if (!persisted) {
+        traceMeshEventDrop('outbox_enqueue_failed', fwdTraceCtx, `coordinatorDaemon=${coordinatorDaemonId}`);
+        return false;
+    }
+    traceMeshEventStage('outbox_enqueue', fwdTraceCtx, `coordinatorDaemon=${coordinatorDaemonId} meshId=${readNonEmptyString(payload.meshId) || 'absent'}`);
+
+    // Data-free reconcile nudge (polling single-model §2.1 (B)): ask the reconcile
+    // loop to run its PHASE 0 outbox retry soon instead of pushing the payload here.
+    // Delivery itself stays on the single acked PHASE 0 path; losing the nudge costs
+    // at most one reconcile interval of latency, never the event.
+    nudgeUnresolvedForwardRetry();
+    LOG.info('MeshEvents', `Durably queued ${eventName} for unresolved-mesh worker at ${routing.workspace || '(no workspace)'} to coordinator daemon ${coordinatorDaemonId} (reconcile PHASE 0 delivers)`);
     return true;
 }
 
-// Ack a just-pushed outbox entry by re-deriving its row from the same coordinator +
-// event + payload. We don't thread the row id back from enqueue (the immediate push is
-// fire-then-ack), so locate it among the undrained entries by matching coordinator and
-// the flat payload's forward identity. A miss is harmless — the retry loop's own
-// receiver-side dedup suppresses a duplicate delivery.
-function ackUnresolvedDelegateForwardByFingerprint(
-    coordinatorDaemonId: string,
-    eventName: string,
-    payload: Record<string, unknown>,
-): void {
-    const match = peekUnresolvedDelegateForwards().find(entry =>
-        daemonIdsEquivalent(entry.coordinatorDaemonId, coordinatorDaemonId)
-        && readNonEmptyString(entry.payload.event) === eventName
-        && readNonEmptyString(entry.payload.targetSessionId || entry.payload.sessionId || entry.payload.instanceId)
-            === readNonEmptyString(payload.targetSessionId || payload.sessionId || payload.instanceId)
-        && readNonEmptyString(entry.payload.workspace) === readNonEmptyString(payload.workspace),
-    );
-    if (match) ackUnresolvedDelegateForward(match.id);
-}
-
 /**
  * NOTIF-HELD-DRAIN (Fix 2): event-driven coordinator drain. The reconcile loop delivers a
  * worker's queued completion to an IDLE local coordinator only on its periodic poll. When a