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

package/dist/index.js

@@ -28744,8 +28744,12 @@ var TerminalAdapter = class {
     this.rows = opts.rows ?? import_session_host_core6.DEFAULT_SESSION_HOST_ROWS;
     this.screenDebounceMs = opts.screenChangeDebounceMs ?? 80;
     this.tickIntervalMs = opts.tickIntervalMs ?? 0;
-    const { NodePtyTransportFactory: NodePtyTransportFactory2 } = (init_pty_transport(), __toCommonJS(pty_transport_exports));
-    this.factory = opts.transportFactory ?? new NodePtyTransportFactory2();
+    if (opts.transportFactory) {
+      this.factory = opts.transportFactory;
+    } else {
+      const { NodePtyTransportFactory: NodePtyTransportFactory2 } = (init_pty_transport(), __toCommonJS(pty_transport_exports));
+      this.factory = new NodePtyTransportFactory2();
+    }
     this.screen = new TerminalScreen(this.rows, this.cols);
   }
   rows;
@@ -28902,6 +28906,10 @@ var FsmDriver = class {
   specWatcher = null;
   /** Last full FSM evaluation, kept for the debugger. */
   lastFsmEval = null;
+  /** Ring buffer (max 20) of the full FSM evaluation captured at each
+   *  transition — the rich pre-transition table that lastFsmEval only keeps
+   *  for the single most recent evaluation. Separate from stateHistory. */
+  fsmSnapshotHistory = [];
   subscribe(listener) {
     this.listeners.add(listener);
     return () => {
@@ -28992,6 +29000,9 @@ var FsmDriver = class {
   getStateHistory() {
     return this.stateHistory;
   }
+  getFsmSnapshotHistory() {
+    return this.fsmSnapshotHistory;
+  }
   getSections() {
     try {
       const screen = this.adapter.snapshot();
@@ -29087,7 +29098,7 @@ var FsmDriver = class {
     this.lastFsmEval = ev;
     this.prevScreenLines = currentLines;
     if (ev.fired) {
-      this.commitTransition(ev.fired, now);
+      this.commitTransition(ev.fired, now, ev);
       this.emitStateChanged(forceEmit);
       this.scheduleWakeForState();
       return;
@@ -29096,8 +29107,9 @@ var FsmDriver = class {
     this.scheduleWakeForState();
     this.maybeMarkReady();
   }
-  commitTransition(fired, now) {
+  commitTransition(fired, now, ev) {
     const from = this.currentStateId;
+    this.pushFsmSnapshot(from, fired, now, ev);
     this.currentStateId = fired.to;
     this.stateEnteredAt = now;
     this.regionLastChangedAt.clear();
@@ -29108,6 +29120,22 @@ var FsmDriver = class {
     });
     LOG.info("FsmDriver", `[${this.specTag()}] ${from} \u2192 ${fired.to} (${fired.label})`);
   }
+  /** Snapshot the full FSM evaluation that produced a transition into the
+   *  separate fsmSnapshotHistory ring buffer (max 20). The transitions[]
+   *  table is captured by reference — it is freshly built per evaluation in
+   *  evaluateFsm and never mutated after, so no clone is needed. */
+  pushFsmSnapshot(from, fired, now, ev) {
+    this.fsmSnapshotHistory.push({
+      stateFrom: from,
+      stateTo: fired.to,
+      at: now,
+      firedTo: fired.to,
+      firedLabel: fired.label,
+      reason: summarizeTransition(fired),
+      transitions: ev.transitions
+    });
+    if (this.fsmSnapshotHistory.length > 20) this.fsmSnapshotHistory.shift();
+  }
   /** Re-derive the visible modal + controls for the current state and emit a
    *  state_changed if anything differs from the last emit. */
   emitStateChanged(forceEmit) {
@@ -30140,7 +30168,7 @@ init_logger();
 function stripAnsi3(text) {
   return String(text || "").replace(/\x1B\][^\x07]*(?:\x07|\x1B\\)/g, "").replace(/\x1B[P^_X][\s\S]*?(?:\x07|\x1B\\)/g, "").replace(/\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g, "");
 }
-var SpecCliAdapter = class {
+var SpecCliAdapter = class _SpecCliAdapter {
   cliType;
   cliName;
   workingDir;
@@ -30165,6 +30193,23 @@ var SpecCliAdapter = class {
   activeInteractivePrompt = null;
   interactivePromptTransport = null;
   claudeTuiPromptCaptureInFlight = false;
+  /**
+   * Wall clock of the first frame on which a held interactive prompt was
+   * observed to have left the screen. Mirrors the approval FSM's
+   * `modalLostAt` hysteresis (see cli-state-engine.ts): claude-cli's TUI
+   * repaints the choice picker as several PTY chunks, so a single frame
+   * with no "Enter to select" footer is not proof the prompt is gone — it
+   * may just be mid-repaint. We only clear the held prompt once it has
+   * been absent across a short grace window. Reset to null the moment the
+   * prompt footer reappears.
+   *
+   * Without this, a choice prompt resolved *directly in the terminal* (the
+   * user picked an option without going through ADHDev's
+   * setInteractivePromptResponse) was never cleared from
+   * `activeInteractivePrompt`, so getStatus() re-emitted the same prompt
+   * forever — the choice-resolve-stuck bug.
+   */
+  interactivePromptLostAt = null;
   jsonLineTail = "";
   exited = false;
   spawned = false;
@@ -30425,6 +30470,11 @@ var SpecCliAdapter = class {
       // transition from the current state with its per-condition match
       // result + countdown — the canonical "why isn't it moving" answer.
       fsm: this.driver.getFsmDebug?.() ?? null,
+      // v4 FSM transition snapshot history (null for v3 specs). The full
+      // pre-transition evaluation table captured at each transition —
+      // answers "why did this rule fire" after the fact, unlike the live
+      // `fsm` field which only reflects the current instant.
+      fsmHistory: this.driver.getFsmSnapshotHistory?.() ?? null,
       // Extended fields
       name: this.cliName,
       status: this.getStatus().status,
@@ -30462,11 +30512,13 @@ var SpecCliAdapter = class {
         if (ev.state.title) {
           LOG.debug("SpecAdapter", `[${this.cliType}] state.title=${JSON.stringify(ev.state.title)}`);
         }
+        this.maybeClearResolvedClaudeTuiPrompt();
         this.maybeCaptureClaudeTuiPrompt();
         this.statusCallback?.();
         return;
       case "pty_data":
         this.detectInteractivePromptFromPtyChunk(ev.chunk);
+        this.maybeClearResolvedClaudeTuiPrompt();
         this.maybeCaptureClaudeTuiPrompt();
         try {
           this.ptyDataCallback?.(ev.chunk);
@@ -30499,6 +30551,7 @@ var SpecCliAdapter = class {
         if (!prompt) continue;
         this.activeInteractivePrompt = prompt;
         this.interactivePromptTransport = "stream-json";
+        this.interactivePromptLostAt = null;
         this.statusCallback?.();
       } catch {
       }
@@ -30552,6 +30605,47 @@ var SpecCliAdapter = class {
     }
     return messages;
   }
+  /**
+   * Grace window a held interactive prompt must be absent from the screen
+   * before we treat it as resolved-in-terminal and clear it. claude-cli
+   * repaints the picker across multiple PTY chunks, so a single
+   * footer-less frame is not proof the prompt is gone. Sized in the same
+   * spirit as the approval FSM's `approvalCooldown` modal-lost hysteresis.
+   */
+  static INTERACTIVE_PROMPT_LOST_GRACE_MS = 1500;
+  /**
+   * Clear a held interactive prompt once the user has resolved it directly
+   * in the terminal (the choice picker leaves the screen without going
+   * through setInteractivePromptResponse). The approval path already does
+   * this via the FSM's modal-lost hysteresis; the interactive-prompt path
+   * had no equivalent, so a terminal-side answer left activeInteractivePrompt
+   * set and getStatus() re-emitted the same choice modal forever.
+   *
+   * Detection mirrors capture: the claude TUI picker is on-screen exactly
+   * while its "Enter to select" footer is rendered. When the footer is gone
+   * for INTERACTIVE_PROMPT_LOST_GRACE_MS the prompt is genuinely resolved.
+   */
+  maybeClearResolvedClaudeTuiPrompt() {
+    if (this.cliType !== "claude-cli" || !this.activeInteractivePrompt) return;
+    let screenText = "";
+    try {
+      screenText = this.driver.snapshot();
+    } catch {
+      return;
+    }
+    const stillOnScreen = screenText.includes("Enter to select");
+    if (stillOnScreen) {
+      this.interactivePromptLostAt = null;
+      return;
+    }
+    const lostAt = this.interactivePromptLostAt ?? Date.now();
+    if (this.interactivePromptLostAt === null) this.interactivePromptLostAt = lostAt;
+    if (Date.now() - lostAt < _SpecCliAdapter.INTERACTIVE_PROMPT_LOST_GRACE_MS) return;
+    this.activeInteractivePrompt = null;
+    this.interactivePromptTransport = null;
+    this.interactivePromptLostAt = null;
+    this.statusCallback?.();
+  }
   maybeCaptureClaudeTuiPrompt() {
     if (this.cliType !== "claude-cli" || this.activeInteractivePrompt || this.claudeTuiPromptCaptureInFlight) return;
     const screenText = this.driver.snapshot();
@@ -30565,6 +30659,7 @@ var SpecCliAdapter = class {
       if (!prompt) return;
       this.activeInteractivePrompt = prompt;
       this.interactivePromptTransport = "tui";
+      this.interactivePromptLostAt = null;
       this.statusCallback?.();
       return;
     }
@@ -30601,6 +30696,7 @@ var SpecCliAdapter = class {
     if (!prompt) return;
     this.activeInteractivePrompt = prompt;
     this.interactivePromptTransport = "tui";
+    this.interactivePromptLostAt = null;
     this.statusCallback?.();
   }
   getDebugState() {
@@ -30655,6 +30751,9 @@ var SpecCliAdapter = class {
       // and countdown. This is the canonical "why isn't it transitioning"
       // answer — no screenshots needed.
       fsm: this.driver.getFsmDebug?.() ?? null,
+      // v4 FSM transition snapshot history — the captured pre-transition
+      // evaluation table at each transition (null for v3 specs).
+      fsmHistory: this.driver.getFsmSnapshotHistory?.() ?? null,
       messages,
       committedMessages: messages
     };
@@ -40650,8 +40749,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",
@@ -40662,7 +40790,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);
@@ -40677,7 +40806,8 @@ async function runMeshRefinePatchEquivalenceGate(repoRoot, baseHead, branchHead)
       mergedTree,
       expectedPatchId,
       actualPatchId,
-      durationMs: Date.now() - startedAt
+      durationMs: Date.now() - startedAt,
+      gitlinkTrivialFastForward
     };
   } catch (e) {
     return {
@@ -40700,6 +40830,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) => ({
@@ -40756,6 +40945,135 @@ function readTreeObject(repoRoot, ref, path39) {
     return void 0;
   }
 }
+function resolveGitDir(repoRoot) {
+  const out = (0, import_node_child_process6.execFileSync)("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;
+    (0, import_node_child_process6.execFileSync)("git", ["cat-file", "-e", `${baseCommit}^{commit}`], { cwd: submoduleRepoPath, stdio: "ignore" });
+    (0, import_node_child_process6.execFileSync)("git", ["cat-file", "-e", `${branchCommit}^{commit}`], { cwd: submoduleRepoPath, stdio: "ignore" });
+    (0, import_node_child_process6.execFileSync)("git", ["merge-base", "--is-ancestor", baseCommit, branchCommit], { cwd: submoduleRepoPath, stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function readChangedPathKinds(repoRoot, fromRef, toRef) {
+  try {
+    const output = (0, import_node_child_process6.execFileSync)("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 = (0, import_path10.resolve)(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 = (0, import_node_child_process6.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]));
+  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 = (0, import_node_child_process6.execFileSync)("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 = (0, import_path10.join)(resolveGitDir(repoRoot), `adhdev-refine-ff-${baseHead.slice(0, 12)}-${branchHead.slice(0, 12)}.index`);
+    const env = { ...process.env, GIT_INDEX_FILE: tmpIndex };
+    try {
+      (0, import_node_child_process6.execFileSync)("git", ["read-tree", baseTree], { cwd: repoRoot, env, stdio: "ignore" });
+      (0, import_node_child_process6.execFileSync)("git", ["update-index", "--index-info"], {
+        cwd: repoRoot,
+        env,
+        input: `${updates}
+`,
+        encoding: "utf8",
+        stdio: ["pipe", "ignore", "ignore"]
+      });
+      const newTree = (0, import_node_child_process6.execFileSync)("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));
@@ -41423,6 +41741,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;
   }
@@ -42652,6 +42974,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 {
@@ -42993,6 +43357,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;
@@ -43047,6 +43422,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;
@@ -44594,7 +45167,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() : "";