@adhdev/daemon-core 0.9.82-rc.260 → 0.9.82-rc.262

package/src/commands/router.ts

@@ -1397,6 +1397,31 @@ type MeshRefinePatchEquivalenceSummary = {
     stdout?: string;
     stderr?: string;
     actionableHint?: MeshRefineSubmoduleConflictHint;
+    /**
+     * Set when a `merge-tree` submodule conflict was reclassified as a trivial
+     * gitlink fast-forward and the gate passed via a synthesized merge tree.
+     */
+    gitlinkTrivialFastForward?: {
+        resolved: boolean;
+        gitlinks: Array<{ path: string; baseCommit?: string; branchCommit?: string; fastForward: boolean }>;
+        reason?: string;
+    };
+};
+
+type MeshRefineEffectiveDiffSummary = {
+    status: MeshRefineStageStatus;
+    /** True when there is at least one root-tree change between base and branch (incl. gitlink bumps). */
+    hasEffectiveDiff: boolean;
+    baseHead: string;
+    branchHead: string;
+    /** Root-level paths that differ between base and branch (capped). */
+    changedPaths?: string[];
+    /** Submodule paths with uncommitted/divergent commits but NO committed gitlink bump in the root tree. */
+    submoduleHints?: Array<{ path: string; reason: string }>;
+    durationMs: number;
+    error?: string;
+    stdout?: string;
+    stderr?: string;
 };
 
 type MeshRefineSubmoduleConflictHint = {
@@ -1496,6 +1521,44 @@ type MeshRefineJobHandle = {
 
 type MeshRefineTerminalJob = MeshRefineJobHandle & { result?: Record<string, unknown> };
 
+type MeshRefineBatchJobStatus = 'accepted' | 'completed' | 'failed';
+
+/**
+ * Async handle returned by the batch Refinery the instant a convergence run is
+ * accepted. Mirrors {@link MeshRefineJobHandle} (async:true / status:'accepted' +
+ * terminal pending-event + ledger delivery) but scopes a whole batch of sibling
+ * nodes rather than a single node. The synthetic `batchLabel` is used as the
+ * `nodeLabel` for the shared refine event/message renderer.
+ */
+type MeshRefineBatchJobHandle = {
+    success: true;
+    async: true;
+    batch: true;
+    status: MeshRefineBatchJobStatus;
+    jobId: string;
+    interactionId: string;
+    meshId: string;
+    batchLabel: string;
+    nodeIds: string[];
+    nodeCount: number;
+    order: string[];
+    startedAt: string;
+    completedAt?: string;
+    duplicate?: boolean;
+    targetCoordinatorDaemonId?: string;
+    eventDelivery: {
+        pendingEvents: true;
+        ledger: true;
+    };
+    evidence: {
+        pendingEventsCommand: 'get_pending_mesh_events';
+        ledgerCommand: 'get_mesh_ledger_slice';
+        taskHistoryKind: 'task_dispatched' | 'task_completed' | 'task_failed';
+    };
+};
+
+type MeshRefineBatchTerminalJob = MeshRefineBatchJobHandle & { result?: Record<string, unknown> };
+
 const REFINE_VALIDATION_CATEGORIES = ['typecheck', 'test', 'lint', 'build'] as const;
 const REFINE_VALIDATION_TIMEOUT_MS = 120_000;
 const REFINE_VALIDATION_OUTPUT_LIMIT_BYTES = 128 * 1024;
@@ -1581,8 +1644,46 @@ async function runMeshRefinePatchEquivalenceGate(
             maxBuffer: REFINE_PATCH_EQUIVALENCE_OUTPUT_LIMIT_BYTES,
         });
         const mergeBase = git(['merge-base', baseHead, branchHead]).trim();
-        const mergeTreeStdout = git(['merge-tree', '--write-tree', baseHead, branchHead]);
-        const mergedTree = mergeTreeStdout.trim().split(/\s+/)[0] || '';
+
+        // `git merge-tree --write-tree` refuses to merge gitlinks that differ
+        // across base/branch even when the advance is a strict fast-forward,
+        // failing with "Recursive merging with submodules currently only
+        // supports trivial cases". When that happens we check whether the
+        // conflict is *entirely* trivial-ff gitlinks and, if so, synthesize the
+        // merged tree ourselves (base tree + branch-side gitlinks).
+        let mergedTree = '';
+        let mergeTreeStdout = '';
+        let gitlinkTrivialFastForward: MeshRefinePatchEquivalenceSummary['gitlinkTrivialFastForward'];
+        try {
+            mergeTreeStdout = git(['merge-tree', '--write-tree', baseHead, branchHead]);
+            mergedTree = mergeTreeStdout.trim().split(/\s+/)[0] || '';
+        } catch (mergeTreeErr: any) {
+            const output = `${mergeTreeErr?.message || ''}\n${mergeTreeErr?.stdout || ''}\n${mergeTreeErr?.stderr || ''}`;
+            const isSubmoduleConflict = /(submodule|160000)/i.test(output)
+                || /Recursive merging with submodules/i.test(output);
+            if (!isSubmoduleConflict) throw mergeTreeErr;
+            const evaluation = evaluateGitlinkTrivialFastForward(repoRoot, baseHead, branchHead);
+            if (!evaluation.trivial) {
+                return {
+                    status: 'failed',
+                    equivalent: false,
+                    baseHead,
+                    branchHead,
+                    mergeBase: mergeBase || undefined,
+                    durationMs: Date.now() - startedAt,
+                    error: mergeTreeErr?.message || String(mergeTreeErr),
+                    stdout: truncateValidationOutput(mergeTreeErr?.stdout),
+                    stderr: truncateValidationOutput(mergeTreeErr?.stderr),
+                    gitlinkTrivialFastForward: { resolved: false, gitlinks: evaluation.gitlinks, reason: evaluation.reason },
+                    actionableHint: buildPatchEquivalenceSubmoduleConflictHint(repoRoot, baseHead, branchHead, output),
+                };
+            }
+            // All conflicting gitlinks fast-forward and nothing else conflicts:
+            // synthesize the merge result as base's tree with branch-side gitlinks.
+            mergedTree = synthesizeTrivialFastForwardMergeTree(repoRoot, baseHead, branchHead, evaluation.gitlinks) || '';
+            gitlinkTrivialFastForward = { resolved: true, gitlinks: evaluation.gitlinks };
+        }
+
         if (!mergeBase || !mergedTree) {
             return {
                 status: 'failed',
@@ -1594,6 +1695,7 @@ async function runMeshRefinePatchEquivalenceGate(
                 durationMs: Date.now() - startedAt,
                 error: 'patch equivalence preflight could not resolve merge-base or synthetic merge tree',
                 stdout: truncateValidationOutput(mergeTreeStdout),
+                gitlinkTrivialFastForward,
             };
         }
         const expectedPatchId = await computeGitPatchId(repoRoot, mergeBase, branchHead);
@@ -1609,6 +1711,7 @@ async function runMeshRefinePatchEquivalenceGate(
             expectedPatchId,
             actualPatchId,
             durationMs: Date.now() - startedAt,
+            gitlinkTrivialFastForward,
         };
     } catch (e: any) {
         return {
@@ -1630,6 +1733,101 @@ async function runMeshRefinePatchEquivalenceGate(
     }
 }
 
+/**
+ * No-op guard: detect a "silent no-op" merge before the Refinery merge runs.
+ *
+ * A silent no-op occurs when the refine target branch's ROOT tree is byte-identical
+ * to the merge base (origin/main). This is the trap where a submodule (e.g. oss) has
+ * real commits but the root branch never committed the gitlink (oss-pointer) bump, so
+ * the root diff Refinery would merge is empty. Merging that produces a merge commit with
+ * no content change — reported as "success" while the actual work never reaches main.
+ *
+ * A committed gitlink bump (the legitimate oss-pointer bump) DOES show up in the root
+ * tree diff (as a 160000-mode entry), so this guard does NOT block legitimate refines —
+ * it only fires when the root tree diff vs base is COMPLETELY empty.
+ *
+ * Runs after the patch-equivalence gate; the "already merged via other path" case
+ * (branch has real changes already present in base) is handled upstream and never
+ * reaches here, so an empty root diff at this point is genuinely a no-op.
+ */
+export async function runMeshRefineEffectiveDiffGate(
+    repoRoot: string,
+    baseHead: string,
+    branchHead: string,
+): Promise<MeshRefineEffectiveDiffSummary> {
+    const startedAt = Date.now();
+    try {
+        const { execFileSync } = await import('node:child_process');
+        const git = (args: string[], opts?: { cwd?: string }) => execFileSync('git', args, {
+            cwd: opts?.cwd || repoRoot,
+            encoding: 'utf8',
+            maxBuffer: REFINE_PATCH_EQUIVALENCE_OUTPUT_LIMIT_BYTES,
+        });
+        // Root tree diff between base and branch. --raw surfaces gitlink (160000) entries,
+        // so a committed submodule-pointer bump counts as an effective change. An empty
+        // result means the branch's root tree is identical to base → nothing would merge.
+        const rawDiff = git(['diff', '--raw', baseHead, branchHead]).trim();
+        if (rawDiff) {
+            const changedPaths = rawDiff
+                .split('\n')
+                .map(line => line.split('\t').slice(1).join('\t').trim())
+                .filter(Boolean)
+                .slice(0, 50);
+            return {
+                status: 'passed',
+                hasEffectiveDiff: true,
+                baseHead,
+                branchHead,
+                changedPaths,
+                durationMs: Date.now() - startedAt,
+            };
+        }
+
+        // No root diff → silent no-op. Try to surface which submodule(s) have commits that
+        // were never captured by a committed gitlink bump, to make the message actionable.
+        const submoduleHints: Array<{ path: string; reason: string }> = [];
+        try {
+            // `git submodule status` flags submodules whose checked-out commit differs from
+            // the recorded gitlink with a leading '+'. That difference is exactly the
+            // uncommitted-pointer-bump situation this guard exists to catch.
+            const status = git(['submodule', 'status']);
+            for (const line of status.split('\n')) {
+                const trimmed = line.trimEnd();
+                if (!trimmed) continue;
+                if (trimmed.startsWith('+')) {
+                    const parts = trimmed.slice(1).trim().split(/\s+/);
+                    const path = parts[1] || parts[0] || '(unknown)';
+                    submoduleHints.push({
+                        path,
+                        reason: 'submodule checked-out commit differs from the committed gitlink (pointer bump not committed on the root branch)',
+                    });
+                }
+            }
+        } catch { /* submodule status is best-effort */ }
+
+        return {
+            status: 'failed',
+            hasEffectiveDiff: false,
+            baseHead,
+            branchHead,
+            ...(submoduleHints.length ? { submoduleHints } : {}),
+            durationMs: Date.now() - startedAt,
+        };
+    } catch (e: any) {
+        // On error, do NOT block the merge — fail open so a probe failure can't wedge refine.
+        return {
+            status: 'skipped',
+            hasEffectiveDiff: true,
+            baseHead,
+            branchHead,
+            durationMs: Date.now() - startedAt,
+            error: e?.message || String(e),
+            stdout: truncateValidationOutput(e?.stdout),
+            stderr: truncateValidationOutput(e?.stderr),
+        };
+    }
+}
+
 function buildPatchEquivalenceSubmoduleConflictHint(
     repoRoot: string,
     baseHead: string,
@@ -1695,6 +1893,230 @@ function readTreeObject(repoRoot: string, ref: string, path: string): string | u
     }
 }
 
+/**
+ * Resolve the absolute path to the repo's real git directory. In a linked
+ * worktree, `.git` is a file pointing elsewhere, so we cannot assume a `.git`
+ * subdirectory exists — a temporary index file must live in the actual git dir.
+ */
+function resolveGitDir(repoRoot: string): string {
+    const out = execFileSync('git', ['rev-parse', '--absolute-git-dir'], {
+        cwd: repoRoot,
+        encoding: 'utf8',
+        maxBuffer: 1024 * 1024,
+    }).trim();
+    return out;
+}
+
+/**
+ * Result of evaluating whether a `git merge-tree --write-tree` submodule
+ * conflict is in fact a trivial gitlink fast-forward that should pass the
+ * patch-equivalence gate.
+ *
+ * `git merge-tree` (and `git merge` with the default recursive strategy)
+ * refuses to 3-way merge gitlinks unless the case is "trivial" — and it
+ * treats *any* gitlink that differs across merge-base/base/branch as
+ * non-trivial, even when the branch-side commit is a strict descendant of the
+ * base-side commit (i.e. a real fast-forward). Refinery only ever wants to
+ * accept the branch's recorded gitlink, so a fast-forwardable bump is safe to
+ * resolve to the branch side without any conflict.
+ */
+type GitlinkTrivialFastForwardEvaluation = {
+    /** True only when the merge-tree conflict is *fully* explained by trivial-ff gitlinks. */
+    trivial: boolean;
+    /** Why the evaluation declined to treat the conflict as trivial (set when trivial=false). */
+    reason?: string;
+    /** Per-path detail for the changed gitlinks that were inspected. */
+    gitlinks: Array<{
+        path: string;
+        baseCommit?: string;
+        branchCommit?: string;
+        fastForward: boolean;
+    }>;
+};
+
+/**
+ * Check, inside a submodule repo, whether `baseCommit` is an ancestor of
+ * `branchCommit` (i.e. advancing the gitlink from base→branch is a pure
+ * fast-forward). Returns false on any error or when either commit is missing
+ * locally — safety first, ambiguity stays "not a fast-forward".
+ */
+function isSubmoduleFastForward(submoduleRepoPath: string, baseCommit: string, branchCommit: string): boolean {
+    if (!baseCommit || !branchCommit) return false;
+    if (baseCommit === branchCommit) return true;
+    try {
+        if (!fs.existsSync(submoduleRepoPath)) return false;
+        // Both commits must exist locally for the ancestry check to be meaningful.
+        execFileSync('git', ['cat-file', '-e', `${baseCommit}^{commit}`], { cwd: submoduleRepoPath, stdio: 'ignore' });
+        execFileSync('git', ['cat-file', '-e', `${branchCommit}^{commit}`], { cwd: submoduleRepoPath, stdio: 'ignore' });
+        // exit 0 ⇒ baseCommit is an ancestor of branchCommit ⇒ branch fast-forwards base.
+        execFileSync('git', ['merge-base', '--is-ancestor', baseCommit, branchCommit], { cwd: submoduleRepoPath, stdio: 'ignore' });
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Read the set of paths that differ between two refs, tagging whether each is a
+ * gitlink (submodule, mode 160000) on either side. Returns one entry per
+ * changed path. Empty on error.
+ */
+function readChangedPathKinds(repoRoot: string, fromRef: string, toRef: string): Array<{ path: string; isGitlink: boolean }> {
+    try {
+        const output = execFileSync('git', ['diff', '--raw', '--no-abbrev', fromRef, toRef], {
+            cwd: repoRoot,
+            encoding: 'utf8',
+            maxBuffer: REFINE_PATCH_EQUIVALENCE_OUTPUT_LIMIT_BYTES,
+        });
+        const result: Array<{ path: string; isGitlink: boolean }> = [];
+        const seen = new Set<string>();
+        for (const line of output.split('\n')) {
+            if (!line.trim()) continue;
+            const metaAndPath = line.split('\t');
+            const meta = metaAndPath[0] || '';
+            const path = metaAndPath[metaAndPath.length - 1]?.trim();
+            if (!path || seen.has(path)) continue;
+            seen.add(path);
+            const parts = meta.split(/\s+/);
+            const isGitlink = !!(parts[0]?.includes('160000') || parts[1]?.includes('160000'));
+            result.push({ path, isGitlink });
+        }
+        return result;
+    } catch {
+        return [];
+    }
+}
+
+/**
+ * Decide whether a merge-tree submodule conflict between base and branch is a
+ * trivial gitlink fast-forward (and nothing else).
+ *
+ * The conflict is treated as trivial ONLY when:
+ *   1. at least one changed gitlink exists,
+ *   2. every changed gitlink fast-forwards (base-commit is an ancestor of the
+ *      branch-commit inside that submodule's repo), and
+ *   3. the *only* paths that changed on both sides of the merge (i.e. the paths
+ *      that could possibly produce a 3-way conflict — the intersection of
+ *      mergeBase→base and mergeBase→branch changes) are gitlinks. Any
+ *      overlapping non-gitlink path means a genuine content conflict could be
+ *      hiding behind the submodule failure, so we keep the block.
+ *
+ * If any of these fail, the conflict is left as a genuine block. This never
+ * passes a regular-file conflict or a diverged (non-ff) gitlink.
+ */
+export function evaluateGitlinkTrivialFastForward(
+    repoRoot: string,
+    baseHead: string,
+    branchHead: string,
+): GitlinkTrivialFastForwardEvaluation {
+    const changedGitlinks = readChangedGitlinkPaths(repoRoot, baseHead, branchHead).map(path => {
+        const baseCommit = readTreeObject(repoRoot, baseHead, path);
+        const branchCommit = readTreeObject(repoRoot, branchHead, path);
+        const submoduleRepoPath = pathResolve(repoRoot, path);
+        const fastForward = !!baseCommit && !!branchCommit
+            && isSubmoduleFastForward(submoduleRepoPath, baseCommit, branchCommit);
+        return { path, baseCommit, branchCommit, fastForward };
+    });
+
+    if (changedGitlinks.length === 0) {
+        return { trivial: false, reason: 'no_changed_gitlinks', gitlinks: changedGitlinks };
+    }
+
+    const nonFastForward = changedGitlinks.filter(entry => !entry.fastForward);
+    if (nonFastForward.length > 0) {
+        return {
+            trivial: false,
+            reason: `diverged_gitlinks:${nonFastForward.map(entry => entry.path).join(',')}`,
+            gitlinks: changedGitlinks,
+        };
+    }
+
+    // Prove there is no *other* conflict (regular files, or a gitlink that
+    // diverged on both sides). A 3-way merge can only conflict on a path that
+    // changed on BOTH sides relative to the merge-base. Compute that overlap and
+    // require every overlapping path to be a gitlink — non-gitlink overlap means
+    // a genuine content conflict that must stay blocked.
+    let mergeBase = '';
+    try {
+        mergeBase = execFileSync('git', ['merge-base', baseHead, branchHead], {
+            cwd: repoRoot,
+            encoding: 'utf8',
+            maxBuffer: 1024 * 1024,
+        }).trim();
+    } catch {
+        return { trivial: false, reason: 'merge_base_unresolved', gitlinks: changedGitlinks };
+    }
+    if (!mergeBase) {
+        return { trivial: false, reason: 'merge_base_unresolved', gitlinks: changedGitlinks };
+    }
+
+    const baseSideChanges = readChangedPathKinds(repoRoot, mergeBase, baseHead);
+    const branchSideChanges = readChangedPathKinds(repoRoot, mergeBase, branchHead);
+    const baseChangedPaths = new Map(baseSideChanges.map(entry => [entry.path, entry]));
+    // Overlapping paths = candidates for a real 3-way conflict.
+    const overlapping = branchSideChanges.filter(entry => baseChangedPaths.has(entry.path));
+    const nonGitlinkOverlap = overlapping.filter(entry => {
+        const baseEntry = baseChangedPaths.get(entry.path);
+        return !(entry.isGitlink && baseEntry?.isGitlink);
+    });
+    if (nonGitlinkOverlap.length > 0) {
+        return {
+            trivial: false,
+            reason: `non_gitlink_overlap:${nonGitlinkOverlap.map(entry => entry.path).join(',')}`,
+            gitlinks: changedGitlinks,
+        };
+    }
+
+    return { trivial: true, gitlinks: changedGitlinks };
+}
+
+/**
+ * Synthesize the merge result for a trivial gitlink fast-forward: take
+ * `baseHead`'s tree and overlay each changed gitlink's branch-side commit.
+ * This mirrors what `git merge-tree` would have produced had it not bailed on
+ * the submodule recursion limitation. Returns the tree SHA, or undefined on
+ * failure. Caller must have already proven (via evaluateGitlinkTrivialFastForward)
+ * that every changed gitlink fast-forwards and no other path conflicts.
+ */
+function synthesizeTrivialFastForwardMergeTree(
+    repoRoot: string,
+    baseHead: string,
+    branchHead: string,
+    gitlinks: Array<{ path: string; branchCommit?: string }>,
+): string | undefined {
+    try {
+        const baseTree = execFileSync('git', ['rev-parse', `${baseHead}^{tree}`], {
+            cwd: repoRoot,
+            encoding: 'utf8',
+            maxBuffer: 1024 * 1024,
+        }).trim();
+        if (!baseTree) return undefined;
+        const updates = gitlinks
+            .filter(entry => entry.branchCommit)
+            .map(entry => `160000 commit ${entry.branchCommit}\t${entry.path}`)
+            .join('\n');
+        if (!updates) return baseTree;
+        const tmpIndex = pathJoin(resolveGitDir(repoRoot), `adhdev-refine-ff-${baseHead.slice(0, 12)}-${branchHead.slice(0, 12)}.index`);
+        const env = { ...process.env, GIT_INDEX_FILE: tmpIndex };
+        try {
+            execFileSync('git', ['read-tree', baseTree], { cwd: repoRoot, env, stdio: 'ignore' });
+            execFileSync('git', ['update-index', '--index-info'], {
+                cwd: repoRoot,
+                env,
+                input: `${updates}\n`,
+                encoding: 'utf8',
+                stdio: ['pipe', 'ignore', 'ignore'],
+            });
+            const newTree = execFileSync('git', ['write-tree'], { cwd: repoRoot, env, encoding: 'utf8' }).trim();
+            return newTree || undefined;
+        } finally {
+            try { fs.rmSync(tmpIndex, { force: true }); } catch { /* ignore */ }
+        }
+    } catch {
+        return undefined;
+    }
+}
+
 async function alignRefinerySubmodulesAfterMerge(
     repoRoot: string,
     previousBaseHead: string,
@@ -2520,6 +2942,10 @@ export class DaemonCommandRouter {
     private runningRefineJobs = new Map<string, MeshRefineJobHandle>();
     /** Terminal async Refinery jobs preserve a clear answer after the worktree node has been removed. */
     private terminalRefineJobs = new Map<string, MeshRefineTerminalJob>();
+    /** In-memory async batch Refinery jobs keyed by meshId (one batch convergence per mesh at a time). */
+    private runningRefineBatchJobs = new Map<string, MeshRefineBatchJobHandle>();
+    /** Terminal async batch Refinery jobs preserve the last batch outcome for late readers. */
+    private terminalRefineBatchJobs = new Map<string, MeshRefineBatchTerminalJob>();
 
     constructor(deps: CommandRouterDeps) {
         this.deps = deps;
@@ -3935,6 +4361,53 @@ export class DaemonCommandRouter {
                 };
             }
 
+            // No-op guard: block a silent no-op merge where the root tree is identical to base.
+            // This catches the trap where a submodule has commits but the root branch never
+            // committed the gitlink (oss-pointer) bump — merging would report success while the
+            // real change never lands on main. A committed gitlink bump shows up in the root
+            // diff, so legitimate oss-pointer refines pass through untouched.
+            const effectiveDiffStarted = Date.now();
+            const effectiveDiff = await runMeshRefineEffectiveDiffGate(repoRoot, baseHead, branchHead);
+            recordMeshRefineStage(refineStages, 'effective_diff', effectiveDiff.status, effectiveDiffStarted, {
+                hasEffectiveDiff: effectiveDiff.hasEffectiveDiff,
+                changedPaths: effectiveDiff.changedPaths,
+                submoduleHints: effectiveDiff.submoduleHints,
+                ...(effectiveDiff.error ? { error: effectiveDiff.error } : {}),
+            });
+            if (effectiveDiff.status === 'failed' && !effectiveDiff.hasEffectiveDiff) {
+                const hintLines = (effectiveDiff.submoduleHints || []).map(h => `  - ${h.path}: ${h.reason}`);
+                const message = [
+                    `Refinery no-op guard: branch '${branch}' has no effective root-tree diff against '${baseBranch}' (${baseHead.slice(0, 12)}); nothing would merge.`,
+                    'This usually means a submodule (e.g. oss) has commits but the root branch never committed the gitlink (pointer) bump, so the merge would be a silent no-op while the real change never reaches main.',
+                    hintLines.length ? `Submodules with uncommitted pointer bumps:\n${hintLines.join('\n')}` : '',
+                    `Fix: commit the submodule pointer bump on '${branch}' (git add <submodule-path> && git commit), then re-run refine.`,
+                ].filter(Boolean).join('\n');
+                return {
+                    success: false,
+                    code: 'no_effective_diff',
+                    convergenceStatus: 'blocked_review',
+                    error: message,
+                    branch,
+                    into: baseBranch,
+                    validationSummary,
+                    patchEquivalence,
+                    effectiveDiff,
+                    refineStages,
+                    finalBranchConvergenceState: {
+                        branch,
+                        baseBranch,
+                        merged: false,
+                        removed: false,
+                        validation: 'passed',
+                        patchEquivalence: 'passed',
+                        effectiveDiff: 'no_effective_diff',
+                        status: 'blocked_review',
+                        reason: 'no_effective_diff',
+                        ...(effectiveDiff.submoduleHints?.length ? { submoduleHints: effectiveDiff.submoduleHints } : {}),
+                    },
+                };
+            }
+
             let mergeResult: Record<string, unknown> | undefined;
             const mergeStarted = Date.now();
             try {
@@ -4294,10 +4767,24 @@ export class DaemonCommandRouter {
             };
         }
 
-        // Execute: refine each node in order. The per-node refine pipeline fetches
-        // origin/<base> fresh, so each merged sibling advances the base before the
-        // next node's auto-rebase + patch-equivalence re-check. A blocked/failed node
-        // is isolated; the batch continues with the remaining nodes.
+        // Execute: refine each node in order via the shared convergence core.
+        return this.runMeshRefineBatchConvergence(meshId, orderedNodes, ordering, args);
+    }
+
+    /**
+     * Convergence core shared by the synchronous batch entry and the async batch job.
+     * Refines each node in order: the per-node refine pipeline fetches origin/<base>
+     * fresh, so each merged sibling advances the base before the next node's auto-rebase
+     * + patch-equivalence re-check. A blocked/failed node is isolated; the batch
+     * continues with the remaining nodes. Does NOT touch the per-node merge logic — it
+     * only sequences calls to executeMeshRefineNodeSynchronously and aggregates outcomes.
+     */
+    private async runMeshRefineBatchConvergence(
+        meshId: string,
+        orderedNodes: any[],
+        ordering: { order: string[]; rationale?: unknown },
+        args: any,
+    ): Promise<CommandRouterResult> {
         type BatchNodeOutcome = {
             nodeId: string;
             workspace: string;
@@ -4372,6 +4859,261 @@ export class DaemonCommandRouter {
         };
     }
 
+    private buildRefineBatchJobKey(meshId: string): string {
+        return `${meshId}::batch`;
+    }
+
+    private buildRefineBatchJobHandle(args: {
+        meshId: string;
+        nodeIds: string[];
+        order: string[];
+        status?: MeshRefineBatchJobStatus;
+        startedAt?: string;
+        completedAt?: string;
+        jobId?: string;
+        interactionId?: string;
+        coordinatorDaemonId?: string;
+    }): MeshRefineBatchJobHandle {
+        return {
+            success: true,
+            async: true,
+            batch: true,
+            status: args.status || 'accepted',
+            jobId: args.jobId || `refine_batch_${createInteractionId()}`,
+            interactionId: args.interactionId || createInteractionId(),
+            meshId: args.meshId,
+            batchLabel: `batch:${args.nodeIds.length} node${args.nodeIds.length === 1 ? '' : 's'}`,
+            nodeIds: args.nodeIds,
+            nodeCount: args.nodeIds.length,
+            order: args.order,
+            startedAt: args.startedAt || new Date().toISOString(),
+            ...(args.completedAt ? { completedAt: args.completedAt } : {}),
+            ...(args.coordinatorDaemonId ? { targetCoordinatorDaemonId: args.coordinatorDaemonId } : {}),
+            eventDelivery: { pendingEvents: true, ledger: true },
+            evidence: {
+                pendingEventsCommand: 'get_pending_mesh_events',
+                ledgerCommand: 'get_mesh_ledger_slice',
+                taskHistoryKind: args.status === 'completed' ? 'task_completed' : args.status === 'failed' ? 'task_failed' : 'task_dispatched',
+            },
+        };
+    }
+
+    /**
+     * Emit a batch Refinery terminal/accepted event through the SAME pending-event +
+     * forward mechanism single-node refine uses (queueRefineJobEvent), so the
+     * coordinator's existing refine:accepted/completed/failed handling and message
+     * renderer apply unchanged. The aggregate per-node results ride along in `result`.
+     */
+    private queueRefineBatchJobEvent(
+        event: 'refine:accepted' | 'refine:completed' | 'refine:failed',
+        handle: MeshRefineBatchJobHandle,
+        result?: Record<string, unknown>,
+    ): void {
+        const metadataEvent = {
+            source: 'refine_mesh_node_async_job',
+            batch: true,
+            jobId: handle.jobId,
+            interactionId: handle.interactionId,
+            meshId: handle.meshId,
+            nodeId: handle.batchLabel,
+            nodeIds: handle.nodeIds,
+            workspace: undefined,
+            status: handle.status,
+            startedAt: handle.startedAt,
+            completedAt: handle.completedAt,
+            order: handle.order,
+            ...(result ? { result } : {}),
+        };
+        const eventPayload = {
+            event,
+            meshId: handle.meshId,
+            nodeLabel: handle.batchLabel,
+            nodeId: handle.batchLabel,
+            metadataEvent,
+            queuedAt: Date.now(),
+            ...(handle.targetCoordinatorDaemonId ? { targetCoordinatorDaemonId: handle.targetCoordinatorDaemonId } : {}),
+        };
+        if (typeof this.deps.instanceManager?.getByCategory === 'function') {
+            const forwarded = handleMeshForwardEvent(
+                { instanceManager: this.deps.instanceManager } as any,
+                {
+                    event,
+                    meshId: handle.meshId,
+                    nodeId: handle.batchLabel,
+                    jobId: handle.jobId,
+                    interactionId: handle.interactionId,
+                    status: handle.status,
+                    startedAt: handle.startedAt,
+                    completedAt: handle.completedAt,
+                    ...(result ? { result } : {}),
+                },
+            );
+            if (forwarded?.success === true) return;
+            LOG.warn('Mesh', `[Refinery] Failed to forward async refine batch event ${event}: ${forwarded?.error || 'unknown error'}`);
+        }
+        queuePendingMeshCoordinatorEvent(eventPayload);
+    }
+
+    private async appendRefineBatchJobLedger(
+        kind: 'task_dispatched' | 'task_completed' | 'task_failed',
+        handle: MeshRefineBatchJobHandle,
+        result?: Record<string, unknown>,
+    ): Promise<void> {
+        try {
+            const { appendLedgerEntry } = await import('../mesh/mesh-ledger.js');
+            appendLedgerEntry(handle.meshId, {
+                kind,
+                nodeId: handle.batchLabel,
+                payload: {
+                    source: 'refine_mesh_node_async_job',
+                    refineJob: {
+                        batch: true,
+                        jobId: handle.jobId,
+                        interactionId: handle.interactionId,
+                        status: handle.status,
+                        meshId: handle.meshId,
+                        nodeIds: handle.nodeIds,
+                        order: handle.order,
+                        targetCoordinatorDaemonId: handle.targetCoordinatorDaemonId,
+                        startedAt: handle.startedAt,
+                        completedAt: handle.completedAt,
+                    },
+                    async: true,
+                    batch: true,
+                    ...(result ? {
+                        success: result.success === true,
+                        result,
+                    } : {}),
+                },
+            });
+        } catch (e: any) {
+            LOG.warn('Mesh', `[Refinery] Failed to append async refine batch ledger entry: ${e?.message || e}`);
+        }
+    }
+
+    private async finishMeshRefineBatchJob(
+        handle: MeshRefineBatchJobHandle,
+        orderedNodes: any[],
+        ordering: { order: string[]; rationale?: unknown },
+        args: any,
+    ): Promise<void> {
+        const key = this.buildRefineBatchJobKey(handle.meshId);
+        let result: Record<string, unknown>;
+        try {
+            result = await this.runMeshRefineBatchConvergence(handle.meshId, orderedNodes, ordering, args) as Record<string, unknown>;
+        } catch (e: any) {
+            result = { success: false, error: e?.message || String(e), batch: true };
+        }
+        const completedAt = new Date().toISOString();
+
+        // The batch as a whole "completed" only when every node converged (no blocked /
+        // not_mergeable). A partial batch is reported as a terminal failure so the
+        // coordinator inspects the per-node blockers rather than assuming a clean merge.
+        const summary = (result.summary && typeof result.summary === 'object') ? result.summary as Record<string, number> : undefined;
+        const allConverged = result.allConverged === true;
+        const isTerminalSuccess = result.success === true && allConverged;
+
+        const nextStep = typeof result.nextStep === 'string' && result.nextStep
+            ? result.nextStep
+            : isTerminalSuccess
+                ? 'All batched nodes converged onto base. Continue from the updated mesh state.'
+                : 'Resolve blocked_review / not_mergeable nodes (see per-node code/stage/error in result.results), then re-run mesh_refine_batch for the remaining nodes.';
+        const normalizedResult = {
+            ...result,
+            batch: true,
+            nextStep,
+            ...(summary ? {
+                convergenceStatus: allConverged ? 'all_converged' : 'partial',
+            } : {}),
+        };
+
+        const terminalHandle = this.buildRefineBatchJobHandle({
+            meshId: handle.meshId,
+            nodeIds: handle.nodeIds,
+            order: handle.order,
+            status: isTerminalSuccess ? 'completed' : 'failed',
+            startedAt: handle.startedAt,
+            completedAt,
+            jobId: handle.jobId,
+            interactionId: handle.interactionId,
+            coordinatorDaemonId: handle.targetCoordinatorDaemonId,
+        });
+        const terminal: MeshRefineBatchTerminalJob = { ...terminalHandle, result: normalizedResult };
+        this.terminalRefineBatchJobs.set(key, terminal);
+        this.runningRefineBatchJobs.delete(key);
+        this.invalidateAggregateMeshStatus(handle.meshId);
+        await this.appendRefineBatchJobLedger(isTerminalSuccess ? 'task_completed' : 'task_failed', terminalHandle, normalizedResult);
+        this.queueRefineBatchJobEvent(isTerminalSuccess ? 'refine:completed' : 'refine:failed', terminalHandle, normalizedResult);
+    }
+
+    /**
+     * Async entry for the batch Refinery execute path. Mirrors startMeshRefineJob:
+     * resolves the plan synchronously (so target/ordering errors and the dry-run shape
+     * stay synchronous), then for execute=true registers an in-flight batch job, returns
+     * {async:true, status:'accepted', batch:true, ...plan} immediately, and runs the
+     * convergence loop in the background — emitting the same terminal refine event.
+     * Idempotent: a batch already in flight for this mesh returns the running handle
+     * with duplicate:true rather than spawning a second background job.
+     */
+    private async startMeshRefineBatchJob(meshId: string, requestedNodeIds: string[] | undefined, args: any): Promise<CommandRouterResult> {
+        // Resolve the plan up-front. For dry-run this returns the synchronous plan; for
+        // execute it returns the same plan shape but we hand convergence to the bg job.
+        const plan = await this.batchRefineMeshNodes(meshId, requestedNodeIds, { ...args, dryRun: true, execute: false });
+        const planRecord = plan as Record<string, unknown>;
+        if (planRecord.success !== true) return plan;
+
+        // If the caller actually asked for a dry-run, return the plan as-is (sync).
+        if (args?.dryRun === true && args?.execute !== true) return plan;
+
+        const order = Array.isArray(planRecord.order) ? (planRecord.order as unknown[]).filter((v): v is string => typeof v === 'string') : [];
+        const nodeIds = order.slice();
+        if (nodeIds.length === 0) {
+            // No convergeable nodes — nothing to dispatch; return the empty plan synchronously.
+            return { ...planRecord, success: true, batch: true, dryRun: false, async: false };
+        }
+
+        const key = this.buildRefineBatchJobKey(meshId);
+        const running = this.runningRefineBatchJobs.get(key);
+        if (running) return { ...running, duplicate: true };
+
+        // Re-resolve the ordered node objects against current membership so the bg job
+        // refines real nodes (the plan only carries ids). preferInline matches refine_mesh_node.
+        const meshRecord = await this.getMeshForCommand(meshId, args?.inlineMesh, { preferInline: true });
+        const mesh = meshRecord?.mesh;
+        const allNodes: any[] = Array.isArray(mesh?.nodes) ? mesh.nodes : [];
+        const orderedNodes = nodeIds
+            .map(id => allNodes.find(n => n.id === id || n.nodeId === id))
+            .filter((n): n is any => !!n);
+        if (orderedNodes.length === 0) {
+            return { success: false, error: 'Batch nodes no longer resolvable in mesh', batch: true };
+        }
+        const ordering = {
+            order,
+            rationale: planRecord.orderingRationale,
+        };
+
+        const coordinatorDaemonId = typeof args?.coordinatorDaemonId === 'string' && args.coordinatorDaemonId.trim()
+            ? args.coordinatorDaemonId.trim()
+            : (this.deps.statusInstanceId || undefined);
+        const handle = this.buildRefineBatchJobHandle({ meshId, nodeIds, order, coordinatorDaemonId });
+        this.runningRefineBatchJobs.set(key, handle);
+        await this.appendRefineBatchJobLedger('task_dispatched', handle);
+        this.queueRefineBatchJobEvent('refine:accepted', handle);
+
+        setImmediate(() => {
+            void this.finishMeshRefineBatchJob(handle, orderedNodes, ordering, args);
+        });
+
+        // Return the accepted handle plus the plan so the coordinator sees the target set.
+        return {
+            ...handle,
+            order,
+            orderingRationale: planRecord.orderingRationale,
+            plan: planRecord.plan,
+            note: 'Batch convergence accepted and running in the background. Completion/failure (with per-node results) will be delivered as a terminal refine event; do not poll repeatedly.',
+        };
+    }
+
     private async finishMeshRefineJob(handle: MeshRefineJobHandle, args: any): Promise<void> {
         const key = this.buildRefineJobKey(handle.meshId, handle.targetNodeId);
         let result: Record<string, unknown>;
@@ -6196,7 +6938,14 @@ export class DaemonCommandRouter {
                 const requestedNodeIds = Array.isArray(args?.nodeIds)
                     ? (args.nodeIds as unknown[]).filter((v): v is string => typeof v === 'string' && v.trim().length > 0).map(v => v.trim())
                     : undefined;
-                return this.batchRefineMeshNodes(meshId, requestedNodeIds, args);
+                // Dry-run (plan-only) stays synchronous: it does no validation/merge and
+                // returns instantly. Execute goes through the async batch job — immediate
+                // {async:true, status:'accepted'} + background convergence + terminal event,
+                // matching the single-node refine_mesh_node contract so long validation
+                // suites can't time out the IPC and strand the coordinator.
+                const isDryRun = args?.dryRun !== false && args?.execute !== true;
+                if (isDryRun) return this.batchRefineMeshNodes(meshId, requestedNodeIds, args);
+                return this.startMeshRefineBatchJob(meshId, requestedNodeIds, args);
             }
 
             case 'remove_mesh_node': {