@adhdev/daemon-core 0.9.82-rc.28 → 0.9.82-rc.281

package/src/mesh/mesh-missions.ts

@@ -0,0 +1,172 @@
+/**
+ * M3: Mission persistence (minimal form).
+ *
+ * A mission is a persistent record of a multi-task goal so the plan lives in
+ * the system rather than in the coordinator LLM's context. Coordinator
+ * sessions can die or compact; a new coordinator reads the mission back at
+ * launch and continues.
+ *
+ * Explicit non-goals (see docs/mesh-product-plan-v2.md Phase M3): this is not
+ * a workflow engine and there is no automatic takeover daemon. Progress is
+ * never stored — it is derived from queue task statuses (mission_id) at
+ * query time.
+ */
+
+import { randomUUID } from 'crypto';
+import { MeshRuntimeStore } from './mesh-runtime-store.js';
+import { getQueue } from './mesh-work-queue.js';
+
+export type MeshMissionStatus = 'active' | 'paused' | 'completed' | 'abandoned';
+
+export const MESH_MISSION_STATUSES: MeshMissionStatus[] = ['active', 'paused', 'completed', 'abandoned'];
+
+export interface MeshMissionRecord {
+    id: string;
+    meshId: string;
+    title: string;
+    goal: string;
+    status: MeshMissionStatus;
+    createdAt: string;
+    updatedAt: string;
+}
+
+export interface MeshMissionTaskAggregate {
+    total: number;
+    pending: number;
+    assigned: number;
+    completed: number;
+    failed: number;
+    cancelled: number;
+    /** Pending tasks held back by a dependency failure (blockedReason set). */
+    blocked: number;
+    /** Latest updatedAt across the mission's tasks, or null with no tasks. */
+    lastActivityAt: string | null;
+}
+
+export interface MeshMissionSummary extends MeshMissionRecord {
+    tasks: MeshMissionTaskAggregate;
+}
+
+function normalizeMissionStatus(value: unknown): MeshMissionStatus {
+    return MESH_MISSION_STATUSES.includes(value as MeshMissionStatus)
+        ? value as MeshMissionStatus
+        : 'active';
+}
+
+export function upsertMeshMission(meshId: string, input: {
+    id?: string;
+    title: string;
+    goal?: string;
+    status?: string;
+}): MeshMissionRecord {
+    const title = typeof input.title === 'string' ? input.title.trim() : '';
+    if (!title) throw new Error('mission_title_required: a mission needs a non-empty title');
+    if (input.status !== undefined && !MESH_MISSION_STATUSES.includes(input.status as MeshMissionStatus)) {
+        throw new Error(`invalid_mission_status: '${input.status}' (valid: ${MESH_MISSION_STATUSES.join(', ')})`);
+    }
+    const id = typeof input.id === 'string' && input.id.trim() ? input.id.trim() : randomUUID();
+    const store = MeshRuntimeStore.getInstance();
+    const existing = store.getMission(meshId, id);
+    const record = {
+        id,
+        meshId,
+        title,
+        goal: typeof input.goal === 'string' ? input.goal : existing?.goal ?? '',
+        status: normalizeMissionStatus(input.status ?? existing?.status),
+    };
+    store.upsertMission(record);
+    const saved = store.getMission(meshId, id)!;
+    return { ...saved, status: normalizeMissionStatus(saved.status) };
+}
+
+export function getMeshMissions(meshId: string, statuses?: MeshMissionStatus[]): MeshMissionRecord[] {
+    return MeshRuntimeStore.getInstance().getMissions(meshId, statuses)
+        .map(m => ({ ...m, status: normalizeMissionStatus(m.status) }));
+}
+
+export function getMeshMission(meshId: string, missionId: string): MeshMissionRecord | null {
+    const record = MeshRuntimeStore.getInstance().getMission(meshId, missionId);
+    return record ? { ...record, status: normalizeMissionStatus(record.status) } : null;
+}
+
+/** Aggregate task statuses for a mission at query time (no stored progress). */
+export function summarizeMissionTasks(meshId: string, missionId: string): MeshMissionTaskAggregate {
+    const tasks = getQueue(meshId).filter(task => task.missionId === missionId);
+    const aggregate: MeshMissionTaskAggregate = {
+        total: tasks.length,
+        pending: 0,
+        assigned: 0,
+        completed: 0,
+        failed: 0,
+        cancelled: 0,
+        blocked: 0,
+        lastActivityAt: null,
+    };
+    for (const task of tasks) {
+        if (task.status === 'pending') aggregate.pending += 1;
+        else if (task.status === 'assigned') aggregate.assigned += 1;
+        else if (task.status === 'completed') aggregate.completed += 1;
+        else if (task.status === 'failed') aggregate.failed += 1;
+        else if (task.status === 'cancelled') aggregate.cancelled += 1;
+        if (task.status === 'pending' && task.blockedReason) aggregate.blocked += 1;
+        if (task.updatedAt && (!aggregate.lastActivityAt || task.updatedAt > aggregate.lastActivityAt)) {
+            aggregate.lastActivityAt = task.updatedAt;
+        }
+    }
+    return aggregate;
+}
+
+export function summarizeMeshMission(meshId: string, mission: MeshMissionRecord): MeshMissionSummary {
+    return { ...mission, tasks: summarizeMissionTasks(meshId, mission.id) };
+}
+
+/** Active mission summaries for mesh_status / coordinator prompt injection. */
+export function getActiveMeshMissionSummaries(meshId: string): MeshMissionSummary[] {
+    return getMeshMissions(meshId, ['active']).map(mission => summarizeMeshMission(meshId, mission));
+}
+
+/**
+ * Mission summaries for the mesh_status dashboard surface: every active/paused
+ * mission plus a capped, newest-first slice of completed/abandoned history so
+ * the dashboard can render a collapsible "history" section without unbounded
+ * payload growth. Returned newest-first within each group (active/paused first,
+ * then history), so the frontend can split on `status` directly.
+ */
+export function getMeshStatusMissionSummaries(
+    meshId: string,
+    options?: { historyLimit?: number },
+): MeshMissionSummary[] {
+    const historyLimit = Math.max(0, options?.historyLimit ?? 10);
+    const all = getMeshMissions(meshId);
+    const live = all.filter(m => m.status === 'active' || m.status === 'paused');
+    const history = all
+        .filter(m => m.status === 'completed' || m.status === 'abandoned')
+        .sort((a, b) => (b.updatedAt || '').localeCompare(a.updatedAt || ''))
+        .slice(0, historyLimit);
+    return [...live, ...history].map(mission => summarizeMeshMission(meshId, mission));
+}
+
+/**
+ * M3-3: render active missions as a prompt section for {{mission}}.
+ * Empty string when no active mission — the prompt stays byte-identical to
+ * the pre-M3 output in that case (regression guarantee).
+ */
+export function buildMissionPromptSection(meshId: string): string {
+    const summaries = getActiveMeshMissionSummaries(meshId);
+    if (summaries.length === 0) return '';
+    const lines: string[] = ['## Active Mission' + (summaries.length > 1 ? 's' : '')];
+    for (const mission of summaries) {
+        const t = mission.tasks;
+        lines.push(
+            `- **${mission.title}** (id: \`${mission.id}\`)`
+            + (mission.goal ? `\n  Goal: ${mission.goal}` : '')
+            + `\n  Tasks: ${t.total} total — ${t.pending} pending (${t.blocked} blocked), ${t.assigned} assigned, ${t.completed} completed, ${t.failed} failed, ${t.cancelled} cancelled`
+            + (t.lastActivityAt ? `\n  Last activity: ${t.lastActivityAt}` : ''),
+        );
+    }
+    lines.push(
+        'Continue this mission from its current task state. Do not re-enqueue tasks that already exist — check mesh_view_queue first. '
+        + 'Update the mission with mesh_mission_upsert when its goal changes or it reaches a terminal state (completed/abandoned).',
+    );
+    return lines.join('\n');
+}

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

@@ -0,0 +1,298 @@
+// ---------------------------------------------------------------------------
+// mesh-reconcile-loop — periodic queue → live coordinator reconciliation
+// ---------------------------------------------------------------------------
+// Single-model replacement for the old event-based "spontaneous forward" paths
+// (remote P2P mesh_forward_event dispatch + live-CLI PTY fire-and-forget inject).
+// Those pushed events at the moment a worker transitioned state, and silently
+// dropped on the network (P2P) or when the coordinator was generating.
+//
+// The reliable backbone has always been the pending-events queue (SQLite +
+// JSONL): every mesh coordinator event is persisted there before anything else
+// (see injectMeshSystemMessage). What was missing was an *active* drainer that
+// runs on a schedule rather than only when the coordinator (an LLM) happens to
+// call a mesh tool.
+//
+// This loop is that drainer. On a fixed interval it:
+//   1. Finds live CLI coordinator sessions on THIS daemon (meshCoordinatorFor
+//      stamp). For each mesh, drains the local queue scoped to this daemon and
+//      injects pending events into the coordinator. When a coordinator is idle it
+//      receives every queued event. When ONLY generating coordinators exist (the
+//      common case while the coordinator is blocked awaiting a worker result), the
+//      loop force-drains ONLY the force-inject events (completion / approval / stop /
+//      refine·bootstrap terminal) and force-writes them into the generating PTY —
+//      the same busy-bypass send-guard escape the live-CLI inject used to use.
+//      Non-force progress events stay queued for the next idle tick (injecting them
+//      mid-generation would be noise). This is what makes a coordinator parked in
+//      `generating` while awaiting a worker's completion actually receive it.
+//   2. In cloud mode (dispatchMeshCommand present), pulls each remote worker
+//      node daemon's queue over P2P (get_pending_mesh_events) and re-injects via
+//      handleMeshForwardEvent — the same pull the MCP drainCoordinatorPendingEvents
+//      already does, now driven by the daemon timer instead of an LLM tool call.
+//
+// IMPORTANT — limits of this loop:
+//   - It only delivers to *live CLI coordinator instances* on this daemon. A
+//     pure stdio MCP coordinator (an LLM with no live CLI session to inject
+//     into) has no inject target here; that case stays pull-driven — the LLM
+//     drains the queue when it calls mesh_status / mesh_read_chat. We do NOT try
+//     to "wake" an LLM from the daemon; that is structurally impossible over a
+//     stdio request/response transport. See docs/refactoring/2026-06-15-mesh-event-to-queue-polling.md §4.7.
+//   - Queue persistence (queuePendingMeshCoordinatorEvent) and the SQLite
+//     drained=1 idempotency are the trust backbone and are untouched by this loop.
+// ---------------------------------------------------------------------------
+
+import type { DaemonComponents } from '../boot/daemon-lifecycle.js';
+import { loadConfig } from '../config/config.js';
+import { listMeshes } from '../config/mesh-config.js';
+import { LOG } from '../logging/logger.js';
+import { drainPendingMeshCoordinatorEvents } from './mesh-events-pending.js';
+import type { PendingMeshCoordinatorEvent } from './mesh-events-pending.js';
+import { MeshRuntimeStore } from './mesh-runtime-store.js';
+import { handleMeshForwardEvent, shouldForceInjectMeshEvent, MESH_FORCE_INJECT_EVENTS } from './mesh-events-coordinator.js';
+import { readNonEmptyString } from './mesh-events-utils.js';
+
+// Default reconcile cadence. approval/completion notifications to a live CLI
+// coordinator land within at most one interval. Overridable via env for tuning.
+const DEFAULT_RECONCILE_INTERVAL_MS = 4_000;
+
+function resolveReconcileIntervalMs(): number {
+    const raw = readNonEmptyString(process.env.MESH_RECONCILE_INTERVAL_MS);
+    if (raw) {
+        const parsed = Number.parseInt(raw, 10);
+        if (Number.isFinite(parsed) && parsed >= 1_000 && parsed <= 60_000) return parsed;
+    }
+    return DEFAULT_RECONCILE_INTERVAL_MS;
+}
+
+interface LiveCoordinator {
+    meshId: string;
+    instance: ReturnType<DaemonComponents['instanceManager']['getInstance']>;
+    idle: boolean;
+}
+
+// The set of coordinator-daemon ids THIS daemon answers to when draining the
+// pending-events queue. A unicast completion event is stamped with the worker's
+// meshCoordinatorDaemonId, which can be either:
+//   - the daemon's canonical status id (`standalone_<machineId>` / `daemon_<machineId>`),
+//     stamped by the MCP layer via ctx.localDaemonId (= getStatus().status.instanceId), or
+//   - the bare machineId, stamped by the local queue-assignment path (loadConfig().machineId).
+// Draining with only one of these silently misses events stamped with the other —
+// the exact reason a generating coordinator never self-received local completions.
+// We accept BOTH so the drain matches regardless of which path stamped the event.
+function resolveCoordinatorDaemonIds(components: DaemonComponents): string[] {
+    const ids = new Set<string>();
+    const statusInstanceId = readNonEmptyString((components as { statusInstanceId?: string }).statusInstanceId);
+    if (statusInstanceId) ids.add(statusInstanceId);
+    const machineId = readNonEmptyString(loadConfig().machineId);
+    if (machineId) ids.add(machineId);
+    return [...ids];
+}
+
+// Find live CLI coordinator instances on THIS daemon, keyed by mesh.
+function findLiveCoordinators(components: DaemonComponents): LiveCoordinator[] {
+    const out: LiveCoordinator[] = [];
+    for (const inst of components.instanceManager.getByCategory('cli')) {
+        const state = inst.getState();
+        const settings = state.settings && typeof state.settings === 'object'
+            ? state.settings as Record<string, unknown>
+            : {};
+        const meshId = readNonEmptyString(settings.meshCoordinatorFor);
+        if (!meshId) continue;
+        const status = readNonEmptyString(state.status).toLowerCase();
+        out.push({ meshId, instance: inst, idle: status === 'idle' });
+    }
+    return out;
+}
+
+// Inject a drained pending event into a live coordinator session. Force-inject
+// events carry force:true so they bypass the busy send-guard and land in the PTY
+// even while the coordinator is generating (see shouldForceInjectMeshEvent).
+function injectPendingIntoCoordinator(
+    coordinator: LiveCoordinator['instance'],
+    pending: PendingMeshCoordinatorEvent,
+): void {
+    if (!coordinator || !pending.coordinatorMessage) return;
+    const force = shouldForceInjectMeshEvent(pending.event);
+    coordinator.onEvent('send_message', {
+        input: { text: pending.coordinatorMessage, textFallback: pending.coordinatorMessage },
+        ...(force ? { force: true } : {}),
+    });
+}
+
+// One reconcile tick across every mesh that has a live CLI coordinator here.
+export async function runMeshReconcileTick(components: DaemonComponents): Promise<void> {
+    const coordinators = findLiveCoordinators(components);
+    if (coordinators.length === 0) {
+        // No live CLI coordinator on this daemon — nothing to inject into.
+        // (MCP-only LLM coordinators drain the queue via their own tool calls.)
+        return;
+    }
+
+    // Group coordinators by mesh; multiple coordinator instances for one mesh is
+    // unusual but supported (each gets the same drained events).
+    const byMesh = new Map<string, LiveCoordinator[]>();
+    for (const c of coordinators) {
+        const list = byMesh.get(c.meshId);
+        if (list) list.push(c);
+        else byMesh.set(c.meshId, [c]);
+    }
+
+    const localDaemonId = readNonEmptyString(loadConfig().machineId) || undefined;
+    // The id-set used to scope the local queue drain (status id + machineId). See
+    // resolveCoordinatorDaemonIds — the status id is what the MCP layer stamps and
+    // is mandatory here for a generating CLI coordinator to self-receive completions.
+    const drainDaemonIds = resolveCoordinatorDaemonIds(components);
+    const dispatchMeshCommand = components.dispatchMeshCommand;
+    const store = (() => {
+        try { return MeshRuntimeStore.getInstance(); } catch { return undefined; }
+    })();
+
+    for (const [meshId, meshCoordinators] of byMesh) {
+        // (a) Cloud-only: pull remote worker node daemons' queues over P2P and
+        //     re-inject locally. This is the same cross-daemon pull the MCP
+        //     drainCoordinatorPendingEvents performs, lifted to the daemon timer.
+        //     On standalone (no dispatchMeshCommand) this whole block is skipped,
+        //     keeping cloud/standalone identical for the local case.
+        if (dispatchMeshCommand) {
+            try {
+                await pullRemoteNodeQueues(components, meshId, localDaemonId);
+            } catch (e: any) {
+                LOG.warn('MeshReconcile', `Remote node pull failed for mesh ${meshId}: ${e?.message || e}`);
+            }
+        }
+
+        // (b) Drain the local queue scoped to this coordinator daemon and inject.
+        //     - If an idle coordinator exists, FULL-drain and deliver every event to it
+        //       (it can receive non-force progress events without deadlocking).
+        //     - If only GENERATING coordinators exist, force-drain ONLY the force-inject
+        //       events (completion/approval/stop/refine·bootstrap terminal) and force-inject
+        //       them so a coordinator parked in `generating` while awaiting that very event
+        //       is not deadlocked. Non-force progress events stay queued for the next idle
+        //       tick — injecting them would be noise mid-generation. Both drains mark the
+        //       consumed rows drained=1 atomically, so the pull path can't re-deliver.
+        const idleCoordinators = meshCoordinators.filter(c => c.idle);
+        const generatingCoordinators = meshCoordinators.filter(c => !c.idle);
+        const targetCoordinators = idleCoordinators.length > 0 ? idleCoordinators : generatingCoordinators;
+        const forceOnly = idleCoordinators.length === 0;
+
+        // O(1) guard: skip the drain entirely when the queue is empty.
+        if (store) {
+            try {
+                if (store.pendingEventCount(meshId) === 0) continue;
+            } catch { /* fall through to drain */ }
+        }
+
+        let pendingEvents: PendingMeshCoordinatorEvent[] = [];
+        try {
+            pendingEvents = drainPendingMeshCoordinatorEvents(
+                meshId,
+                drainDaemonIds.length > 0 ? drainDaemonIds : localDaemonId,
+                forceOnly ? { onlyEvents: MESH_FORCE_INJECT_EVENTS } : undefined,
+            );
+        } catch (e: any) {
+            LOG.warn('MeshReconcile', `Drain failed for mesh ${meshId}: ${e?.message || e}`);
+            continue;
+        }
+        if (pendingEvents.length === 0) continue;
+
+        const mode = forceOnly ? 'force-drain → generating' : 'inject → idle';
+        LOG.info('MeshReconcile', `Reconcile ${mode}: ${pendingEvents.length} pending event(s) → ${targetCoordinators.length} coordinator(s) for mesh ${meshId}`);
+        for (const pending of pendingEvents) {
+            for (const c of targetCoordinators) {
+                injectPendingIntoCoordinator(c.instance, pending);
+            }
+        }
+    }
+}
+
+// Cloud-only: poll each remote worker node daemon for pending coordinator events
+// and re-inject them locally via handleMeshForwardEvent (which re-queues +
+// surfaces to the live coordinator on the next tick / immediately if idle).
+async function pullRemoteNodeQueues(
+    components: DaemonComponents,
+    meshId: string,
+    localDaemonId: string | undefined,
+): Promise<void> {
+    const dispatchMeshCommand = components.dispatchMeshCommand;
+    if (!dispatchMeshCommand) return;
+    const mesh = listMeshes().find(m => m.id === meshId);
+    if (!mesh) return;
+
+    const pendingEventArgs: Record<string, unknown> = {
+        meshId,
+        ...(localDaemonId ? { coordinatorDaemonId: localDaemonId } : {}),
+    };
+
+    for (const node of mesh.nodes) {
+        const nodeDaemonId = readNonEmptyString(node.daemonId);
+        // Skip nodes without a daemon, and nodes on THIS daemon (their events are
+        // already in the local queue drained in step (b)).
+        if (!nodeDaemonId) continue;
+        if (localDaemonId && nodeDaemonId === localDaemonId) continue;
+
+        let events: unknown;
+        try {
+            events = await dispatchMeshCommand(nodeDaemonId, 'get_pending_mesh_events', pendingEventArgs);
+        } catch {
+            // Remote pull is best-effort; the node may be offline. Retry next tick.
+            continue;
+        }
+        const list = extractPendingEvents(events).filter(e => readNonEmptyString(e?.meshId) === meshId);
+        for (const event of list) {
+            const payload = buildForwardPayloadFromPending(event);
+            if (!payload.event || !payload.meshId) continue;
+            try {
+                handleMeshForwardEvent(components, payload);
+            } catch { /* best-effort re-inject */ }
+        }
+    }
+}
+
+function extractPendingEvents(raw: unknown): any[] {
+    if (Array.isArray(raw)) return raw;
+    if (raw && typeof raw === 'object') {
+        const events = (raw as Record<string, unknown>).events;
+        if (Array.isArray(events)) return events;
+    }
+    return [];
+}
+
+// Flatten a queued PendingMeshCoordinatorEvent into the flat payload shape
+// handleMeshForwardEvent expects (mirrors the MCP buildMeshForwardPayloadFromPendingEvent).
+function buildForwardPayloadFromPending(event: any): Record<string, unknown> {
+    const metadata = event?.metadataEvent && typeof event.metadataEvent === 'object'
+        ? event.metadataEvent as Record<string, unknown>
+        : {};
+    return {
+        event: readNonEmptyString(event?.event),
+        meshId: readNonEmptyString(event?.meshId),
+        nodeId: readNonEmptyString(event?.nodeId) || readNonEmptyString(metadata.meshNodeId),
+        workspace: readNonEmptyString(event?.workspace) || readNonEmptyString(metadata.workspace),
+        ...metadata,
+    };
+}
+
+interface ReconcileLoopHandle {
+    stop(): void;
+}
+
+// Start the periodic reconcile loop. Returns a handle with stop() for shutdown.
+export function setupMeshReconcileLoop(components: DaemonComponents): ReconcileLoopHandle {
+    const intervalMs = resolveReconcileIntervalMs();
+    let running = false;
+    const timer = setInterval(() => {
+        if (running) return; // never overlap ticks
+        running = true;
+        void runMeshReconcileTick(components)
+            .catch((e: any) => LOG.warn('MeshReconcile', `Reconcile tick error: ${e?.message || e}`))
+            .finally(() => { running = false; });
+    }, intervalMs);
+    // Don't keep the process alive solely for this timer.
+    if (typeof timer.unref === 'function') timer.unref();
+    LOG.info('MeshReconcile', `Mesh reconcile loop started (interval ${intervalMs}ms)`);
+    return {
+        stop() {
+            clearInterval(timer);
+            LOG.info('MeshReconcile', 'Mesh reconcile loop stopped');
+        },
+    };
+}

package/src/mesh/mesh-refine-batch.ts

@@ -0,0 +1,197 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Change-area analysis for one worktree node, used to order sibling nodes for
+ * batch refinement so that nodes least likely to conflict merge first.
+ *
+ * The heuristic is deliberately git-only and side-effect-free: it inspects the
+ * commits the node's branch adds on top of the base (`base..branch`) and records
+ *   - whether any submodule gitlink path is touched (high-conflict signal: the
+ *     batch must rebase later siblings onto the advanced submodule main), and
+ *   - the set of changed top-level paths (so siblings touching disjoint trees can
+ *     be ordered ahead of ones that overlap).
+ */
+export interface MeshRefineBatchNodeChangeArea {
+    nodeId: string;
+    workspace: string;
+    branch: string;
+    /** Top-level path segments changed by the branch vs. base (e.g. 'oss', 'packages'). */
+    changedTopLevelPaths: string[];
+    /** Full changed file list (bounded) for overlap detection. */
+    changedFiles: string[];
+    /** Submodule gitlink paths touched by the branch (subset of changedTopLevelPaths). */
+    touchedSubmodulePaths: string[];
+    /** True when the branch touches at least one submodule gitlink. */
+    touchesSubmodule: boolean;
+    /** Number of commits the branch is ahead of base; 0 means nothing to merge. */
+    aheadCount: number;
+    /** Non-fatal analysis error (e.g. base/branch unresolved); ordering falls back to neutral. */
+    error?: string;
+}
+
+export interface MeshRefineBatchOrderingResult {
+    /** Node IDs in the order they should be refined. */
+    order: string[];
+    /** Per-node change areas, keyed by node id, for plan transparency. */
+    changeAreas: Record<string, MeshRefineBatchNodeChangeArea>;
+    /** Human-readable explanation of why the order was chosen. */
+    rationale: string[];
+}
+
+const MAX_CHANGED_FILES = 500;
+
+function topLevel(path: string): string {
+    const slash = path.indexOf('/');
+    return slash === -1 ? path : path.slice(0, slash);
+}
+
+/**
+ * Resolve the set of submodule gitlink paths declared in a repo's .gitmodules,
+ * relative to the repo root. Used to classify which changed paths are submodule
+ * pointer bumps vs. ordinary file edits.
+ */
+async function resolveSubmodulePaths(repoRoot: string): Promise<Set<string>> {
+    try {
+        const { stdout } = await execFileAsync(
+            'git',
+            ['config', '--file', '.gitmodules', '--get-regexp', 'path'],
+            { cwd: repoRoot, encoding: 'utf8' },
+        );
+        const paths = new Set<string>();
+        for (const line of stdout.split('\n')) {
+            const trimmed = line.trim();
+            if (!trimmed) continue;
+            // Format: "submodule.<name>.path <path>"
+            const spaceIdx = trimmed.indexOf(' ');
+            if (spaceIdx === -1) continue;
+            const value = trimmed.slice(spaceIdx + 1).trim();
+            if (value) paths.add(value);
+        }
+        return paths;
+    } catch {
+        // No .gitmodules (or git error) → repo has no submodules to classify.
+        return new Set();
+    }
+}
+
+/**
+ * Analyze one worktree node's change area against its merge base.
+ *
+ * @param baseRef  ref that the node will merge into (e.g. 'origin/main' or a SHA)
+ * @param branchRef the node's branch tip
+ * @param diffCwd  repo to run the diff in (the worktree itself is authoritative for
+ *                 `branch` resolution, but the diff `base..branch` is symmetric, so
+ *                 the worktree cwd works for both refs once base is a reachable SHA).
+ */
+export async function analyzeMeshRefineNodeChangeArea(args: {
+    nodeId: string;
+    workspace: string;
+    branch: string;
+    baseRef: string;
+    branchRef: string;
+    diffCwd: string;
+    submodulePaths: Set<string>;
+}): Promise<MeshRefineBatchNodeChangeArea> {
+    const { nodeId, workspace, branch, baseRef, branchRef, diffCwd, submodulePaths } = args;
+    const base: MeshRefineBatchNodeChangeArea = {
+        nodeId,
+        workspace,
+        branch,
+        changedTopLevelPaths: [],
+        changedFiles: [],
+        touchedSubmodulePaths: [],
+        touchesSubmodule: false,
+        aheadCount: 0,
+    };
+    try {
+        // Use the merge-base so we compare only the node's own commits, not changes
+        // that already landed on base via a sibling earlier in the batch.
+        let mergeBase = baseRef;
+        try {
+            const { stdout } = await execFileAsync('git', ['merge-base', baseRef, branchRef], { cwd: diffCwd, encoding: 'utf8' });
+            const resolved = stdout.trim();
+            if (resolved) mergeBase = resolved;
+        } catch { /* fall back to baseRef directly */ }
+
+        const { stdout: countStdout } = await execFileAsync(
+            'git',
+            ['rev-list', '--count', `${mergeBase}..${branchRef}`],
+            { cwd: diffCwd, encoding: 'utf8' },
+        );
+        base.aheadCount = Number.parseInt(countStdout.trim(), 10) || 0;
+
+        const { stdout: nameStdout } = await execFileAsync(
+            'git',
+            ['diff', '--name-only', `${mergeBase}..${branchRef}`],
+            { cwd: diffCwd, encoding: 'utf8' },
+        );
+        const files = nameStdout.split('\n').map(line => line.trim()).filter(Boolean).slice(0, MAX_CHANGED_FILES);
+        base.changedFiles = files;
+        const topSet = new Set<string>();
+        const submoduleSet = new Set<string>();
+        for (const file of files) {
+            const top = topLevel(file);
+            topSet.add(top);
+            // A changed path is a submodule touch if the file path IS a declared
+            // submodule path (gitlink bumps surface as the submodule path itself).
+            if (submodulePaths.has(file) || submodulePaths.has(top)) {
+                submoduleSet.add(submodulePaths.has(file) ? file : top);
+            }
+        }
+        base.changedTopLevelPaths = [...topSet].sort();
+        base.touchedSubmodulePaths = [...submoduleSet].sort();
+        base.touchesSubmodule = submoduleSet.size > 0;
+        return base;
+    } catch (e: any) {
+        base.error = e?.message || String(e);
+        return base;
+    }
+}
+
+/**
+ * Order nodes for batch refinement to minimize cross-sibling conflicts.
+ *
+ * Heuristic (deterministic, stable):
+ *   1. Nodes that do NOT touch any submodule come first — they cannot advance the
+ *      submodule main, so they never force a later submodule rebase.
+ *   2. Within each group, fewer touched top-level paths first (smaller blast radius).
+ *   3. Tie-break by node id for determinism.
+ *
+ * Submodule-touching siblings are intrinsically serial: each one that merges
+ * advances oss main, so the next must rebase. Ordering them last keeps the
+ * non-submodule merges (which never need a submodule rebase) clean and up front.
+ */
+export function orderMeshRefineBatchNodes(
+    changeAreas: MeshRefineBatchNodeChangeArea[],
+): MeshRefineBatchOrderingResult {
+    const areaById: Record<string, MeshRefineBatchNodeChangeArea> = {};
+    for (const area of changeAreas) areaById[area.nodeId] = area;
+
+    const ranked = [...changeAreas].sort((a, b) => {
+        const aSub = a.touchesSubmodule ? 1 : 0;
+        const bSub = b.touchesSubmodule ? 1 : 0;
+        if (aSub !== bSub) return aSub - bSub;
+        const aBreadth = a.changedTopLevelPaths.length;
+        const bBreadth = b.changedTopLevelPaths.length;
+        if (aBreadth !== bBreadth) return aBreadth - bBreadth;
+        return a.nodeId.localeCompare(b.nodeId);
+    });
+
+    const rationale: string[] = [];
+    const nonSub = ranked.filter(a => !a.touchesSubmodule).map(a => a.nodeId);
+    const sub = ranked.filter(a => a.touchesSubmodule).map(a => a.nodeId);
+    if (nonSub.length) {
+        rationale.push(`Non-submodule nodes first (no submodule-main advance, conflict-free ordering): ${nonSub.join(', ')}`);
+    }
+    if (sub.length) {
+        rationale.push(`Submodule-touching nodes last, serialized (each merge advances submodule main, forcing rebase of the next): ${sub.join(', ')}`);
+    }
+    for (const area of ranked) {
+        if (area.error) rationale.push(`Node ${area.nodeId}: change-area analysis degraded (${area.error}); placed with neutral priority.`);
+    }
+
+    return { order: ranked.map(a => a.nodeId), changeAreas: areaById, rationale };
+}