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

package/dist/index.mjs

@@ -40418,8 +40418,37 @@ async function runMeshRefinePatchEquivalenceGate(repoRoot, baseHead, branchHead)
       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] || "";
+    let mergedTree = "";
+    let mergeTreeStdout = "";
+    let gitlinkTrivialFastForward;
+    try {
+      mergeTreeStdout = git(["merge-tree", "--write-tree", baseHead, branchHead]);
+      mergedTree = mergeTreeStdout.trim().split(/\s+/)[0] || "";
+    } catch (mergeTreeErr) {
+      const output = `${mergeTreeErr?.message || ""}
+${mergeTreeErr?.stdout || ""}
+${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 || void 0,
+          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)
+        };
+      }
+      mergedTree = synthesizeTrivialFastForwardMergeTree(repoRoot, baseHead, branchHead, evaluation.gitlinks) || "";
+      gitlinkTrivialFastForward = { resolved: true, gitlinks: evaluation.gitlinks };
+    }
     if (!mergeBase || !mergedTree) {
       return {
         status: "failed",
@@ -40430,7 +40459,8 @@ async function runMeshRefinePatchEquivalenceGate(repoRoot, baseHead, branchHead)
         mergedTree: mergedTree || void 0,
         durationMs: Date.now() - startedAt,
         error: "patch equivalence preflight could not resolve merge-base or synthetic merge tree",
-        stdout: truncateValidationOutput(mergeTreeStdout)
+        stdout: truncateValidationOutput(mergeTreeStdout),
+        gitlinkTrivialFastForward
       };
     }
     const expectedPatchId = await computeGitPatchId(repoRoot, mergeBase, branchHead);
@@ -40445,7 +40475,8 @@ async function runMeshRefinePatchEquivalenceGate(repoRoot, baseHead, branchHead)
       mergedTree,
       expectedPatchId,
       actualPatchId,
-      durationMs: Date.now() - startedAt
+      durationMs: Date.now() - startedAt,
+      gitlinkTrivialFastForward
     };
   } catch (e) {
     return {
@@ -40468,6 +40499,65 @@ ${e?.stderr || ""}`
     };
   }
 }
+async function runMeshRefineEffectiveDiffGate(repoRoot, baseHead, branchHead) {
+  const startedAt = Date.now();
+  try {
+    const { execFileSync: execFileSync6 } = await import("child_process");
+    const git = (args, opts) => execFileSync6("git", args, {
+      cwd: opts?.cwd || repoRoot,
+      encoding: "utf8",
+      maxBuffer: REFINE_PATCH_EQUIVALENCE_OUTPUT_LIMIT_BYTES
+    });
+    const rawDiff = git(["diff", "--raw", baseHead, branchHead]).trim();
+    if (rawDiff) {
+      const changedPaths = rawDiff.split("\n").map((line) => line.split("	").slice(1).join("	").trim()).filter(Boolean).slice(0, 50);
+      return {
+        status: "passed",
+        hasEffectiveDiff: true,
+        baseHead,
+        branchHead,
+        changedPaths,
+        durationMs: Date.now() - startedAt
+      };
+    }
+    const submoduleHints = [];
+    try {
+      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 path39 = parts[1] || parts[0] || "(unknown)";
+          submoduleHints.push({
+            path: path39,
+            reason: "submodule checked-out commit differs from the committed gitlink (pointer bump not committed on the root branch)"
+          });
+        }
+      }
+    } catch {
+    }
+    return {
+      status: "failed",
+      hasEffectiveDiff: false,
+      baseHead,
+      branchHead,
+      ...submoduleHints.length ? { submoduleHints } : {},
+      durationMs: Date.now() - startedAt
+    };
+  } catch (e) {
+    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, baseHead, branchHead, output) {
   if (!/(submodule|160000)/i.test(output) || !/(conflict|failed to merge)/i.test(output)) return void 0;
   const conflicts = readChangedGitlinkPaths(repoRoot, baseHead, branchHead).map((path39) => ({
@@ -40524,6 +40614,135 @@ function readTreeObject(repoRoot, ref, path39) {
     return void 0;
   }
 }
+function resolveGitDir(repoRoot) {
+  const out = execFileSync5("git", ["rev-parse", "--absolute-git-dir"], {
+    cwd: repoRoot,
+    encoding: "utf8",
+    maxBuffer: 1024 * 1024
+  }).trim();
+  return out;
+}
+function isSubmoduleFastForward(submoduleRepoPath, baseCommit, branchCommit) {
+  if (!baseCommit || !branchCommit) return false;
+  if (baseCommit === branchCommit) return true;
+  try {
+    if (!fs23.existsSync(submoduleRepoPath)) return false;
+    execFileSync5("git", ["cat-file", "-e", `${baseCommit}^{commit}`], { cwd: submoduleRepoPath, stdio: "ignore" });
+    execFileSync5("git", ["cat-file", "-e", `${branchCommit}^{commit}`], { cwd: submoduleRepoPath, stdio: "ignore" });
+    execFileSync5("git", ["merge-base", "--is-ancestor", baseCommit, branchCommit], { cwd: submoduleRepoPath, stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function readChangedPathKinds(repoRoot, fromRef, toRef) {
+  try {
+    const output = execFileSync5("git", ["diff", "--raw", "--no-abbrev", fromRef, toRef], {
+      cwd: repoRoot,
+      encoding: "utf8",
+      maxBuffer: REFINE_PATCH_EQUIVALENCE_OUTPUT_LIMIT_BYTES
+    });
+    const result = [];
+    const seen = /* @__PURE__ */ new Set();
+    for (const line of output.split("\n")) {
+      if (!line.trim()) continue;
+      const metaAndPath = line.split("	");
+      const meta = metaAndPath[0] || "";
+      const path39 = metaAndPath[metaAndPath.length - 1]?.trim();
+      if (!path39 || seen.has(path39)) continue;
+      seen.add(path39);
+      const parts = meta.split(/\s+/);
+      const isGitlink = !!(parts[0]?.includes("160000") || parts[1]?.includes("160000"));
+      result.push({ path: path39, isGitlink });
+    }
+    return result;
+  } catch {
+    return [];
+  }
+}
+function evaluateGitlinkTrivialFastForward(repoRoot, baseHead, branchHead) {
+  const changedGitlinks = readChangedGitlinkPaths(repoRoot, baseHead, branchHead).map((path39) => {
+    const baseCommit = readTreeObject(repoRoot, baseHead, path39);
+    const branchCommit = readTreeObject(repoRoot, branchHead, path39);
+    const submoduleRepoPath = pathResolve2(repoRoot, path39);
+    const fastForward = !!baseCommit && !!branchCommit && isSubmoduleFastForward(submoduleRepoPath, baseCommit, branchCommit);
+    return { path: path39, 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
+    };
+  }
+  let mergeBase = "";
+  try {
+    mergeBase = execFileSync5("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]));
+  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 };
+}
+function synthesizeTrivialFastForwardMergeTree(repoRoot, baseHead, branchHead, gitlinks) {
+  try {
+    const baseTree = execFileSync5("git", ["rev-parse", `${baseHead}^{tree}`], {
+      cwd: repoRoot,
+      encoding: "utf8",
+      maxBuffer: 1024 * 1024
+    }).trim();
+    if (!baseTree) return void 0;
+    const updates = gitlinks.filter((entry) => entry.branchCommit).map((entry) => `160000 commit ${entry.branchCommit}	${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 {
+      execFileSync5("git", ["read-tree", baseTree], { cwd: repoRoot, env, stdio: "ignore" });
+      execFileSync5("git", ["update-index", "--index-info"], {
+        cwd: repoRoot,
+        env,
+        input: `${updates}
+`,
+        encoding: "utf8",
+        stdio: ["pipe", "ignore", "ignore"]
+      });
+      const newTree = execFileSync5("git", ["write-tree"], { cwd: repoRoot, env, encoding: "utf8" }).trim();
+      return newTree || void 0;
+    } finally {
+      try {
+        fs23.rmSync(tmpIndex, { force: true });
+      } catch {
+      }
+    }
+  } catch {
+    return void 0;
+  }
+}
 async function alignRefinerySubmodulesAfterMerge(repoRoot, previousBaseHead, currentHead, options = {}) {
   const startedAt = Date.now();
   const changedGitlinkPaths = readChangedGitlinkPaths(repoRoot, previousBaseHead, currentHead).filter((path39) => !(options.submoduleIgnorePaths || []).includes(path39));
@@ -41191,6 +41410,10 @@ var DaemonCommandRouter = class {
   runningRefineJobs = /* @__PURE__ */ new Map();
   /** Terminal async Refinery jobs preserve a clear answer after the worktree node has been removed. */
   terminalRefineJobs = /* @__PURE__ */ new Map();
+  /** In-memory async batch Refinery jobs keyed by meshId (one batch convergence per mesh at a time). */
+  runningRefineBatchJobs = /* @__PURE__ */ new Map();
+  /** Terminal async batch Refinery jobs preserve the last batch outcome for late readers. */
+  terminalRefineBatchJobs = /* @__PURE__ */ new Map();
   constructor(deps) {
     this.deps = deps;
   }
@@ -42420,6 +42643,48 @@ ${tail}` : ""
           }
         };
       }
+      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:
+${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;
       const mergeStarted = Date.now();
       try {
@@ -42761,6 +43026,17 @@ ${tail}` : ""
         note: "Dry-run: no validation, rebase, or merge was executed. Re-run with execute=true to converge nodes in this order."
       };
     }
+    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.
+   */
+  async runMeshRefineBatchConvergence(meshId, orderedNodes, ordering, args) {
     const results = [];
     for (const node of orderedNodes) {
       let result;
@@ -42815,6 +43091,204 @@ ${tail}` : ""
       }
     };
   }
+  buildRefineBatchJobKey(meshId) {
+    return `${meshId}::batch`;
+  }
+  buildRefineBatchJobHandle(args) {
+    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 || (/* @__PURE__ */ 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`.
+   */
+  queueRefineBatchJobEvent(event, handle, result) {
+    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: void 0,
+      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 },
+        {
+          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);
+  }
+  async appendRefineBatchJobLedger(kind, handle, result) {
+    try {
+      const { appendLedgerEntry: appendLedgerEntry2 } = await Promise.resolve().then(() => (init_mesh_ledger(), mesh_ledger_exports));
+      appendLedgerEntry2(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) {
+      LOG.warn("Mesh", `[Refinery] Failed to append async refine batch ledger entry: ${e?.message || e}`);
+    }
+  }
+  async finishMeshRefineBatchJob(handle, orderedNodes, ordering, args) {
+    const key = this.buildRefineBatchJobKey(handle.meshId);
+    let result;
+    try {
+      result = await this.runMeshRefineBatchConvergence(handle.meshId, orderedNodes, ordering, args);
+    } catch (e) {
+      result = { success: false, error: e?.message || String(e), batch: true };
+    }
+    const completedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const summary = result.summary && typeof result.summary === "object" ? result.summary : void 0;
+    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 = { ...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.
+   */
+  async startMeshRefineBatchJob(meshId, requestedNodeIds, args) {
+    const plan = await this.batchRefineMeshNodes(meshId, requestedNodeIds, { ...args, dryRun: true, execute: false });
+    const planRecord = plan;
+    if (planRecord.success !== true) return plan;
+    if (args?.dryRun === true && args?.execute !== true) return plan;
+    const order = Array.isArray(planRecord.order) ? planRecord.order.filter((v) => typeof v === "string") : [];
+    const nodeIds = order.slice();
+    if (nodeIds.length === 0) {
+      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 };
+    const meshRecord = await this.getMeshForCommand(meshId, args?.inlineMesh, { preferInline: true });
+    const mesh = meshRecord?.mesh;
+    const allNodes = Array.isArray(mesh?.nodes) ? mesh.nodes : [];
+    const orderedNodes = nodeIds.map((id) => allNodes.find((n) => n.id === id || n.nodeId === id)).filter((n) => !!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 || void 0;
+    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 {
+      ...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."
+    };
+  }
   async finishMeshRefineJob(handle, args) {
     const key = this.buildRefineJobKey(handle.meshId, handle.targetNodeId);
     let result;
@@ -44362,7 +44836,9 @@ ${tail}` : ""
         const meshId = typeof args?.meshId === "string" ? args.meshId.trim() : "";
         if (!meshId) return { success: false, error: "meshId required" };
         const requestedNodeIds = Array.isArray(args?.nodeIds) ? args.nodeIds.filter((v) => typeof v === "string" && v.trim().length > 0).map((v) => v.trim()) : void 0;
-        return this.batchRefineMeshNodes(meshId, requestedNodeIds, args);
+        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": {
         const meshId = typeof args?.meshId === "string" ? args.meshId.trim() : "";