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

package/dist/mesh/mesh-refine-batch.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Change-area analysis for one worktree node, used to order sibling nodes for
+ * batch refinement so that nodes least likely to conflict merge first.
+ *
+ * The heuristic is deliberately git-only and side-effect-free: it inspects the
+ * commits the node's branch adds on top of the base (`base..branch`) and records
+ *   - whether any submodule gitlink path is touched (high-conflict signal: the
+ *     batch must rebase later siblings onto the advanced submodule main), and
+ *   - the set of changed top-level paths (so siblings touching disjoint trees can
+ *     be ordered ahead of ones that overlap).
+ */
+export interface MeshRefineBatchNodeChangeArea {
+    nodeId: string;
+    workspace: string;
+    branch: string;
+    /** Top-level path segments changed by the branch vs. base (e.g. 'oss', 'packages'). */
+    changedTopLevelPaths: string[];
+    /** Full changed file list (bounded) for overlap detection. */
+    changedFiles: string[];
+    /** Submodule gitlink paths touched by the branch (subset of changedTopLevelPaths). */
+    touchedSubmodulePaths: string[];
+    /** True when the branch touches at least one submodule gitlink. */
+    touchesSubmodule: boolean;
+    /** Number of commits the branch is ahead of base; 0 means nothing to merge. */
+    aheadCount: number;
+    /** Non-fatal analysis error (e.g. base/branch unresolved); ordering falls back to neutral. */
+    error?: string;
+}
+export interface MeshRefineBatchOrderingResult {
+    /** Node IDs in the order they should be refined. */
+    order: string[];
+    /** Per-node change areas, keyed by node id, for plan transparency. */
+    changeAreas: Record<string, MeshRefineBatchNodeChangeArea>;
+    /** Human-readable explanation of why the order was chosen. */
+    rationale: string[];
+}
+/**
+ * Analyze one worktree node's change area against its merge base.
+ *
+ * @param baseRef  ref that the node will merge into (e.g. 'origin/main' or a SHA)
+ * @param branchRef the node's branch tip
+ * @param diffCwd  repo to run the diff in (the worktree itself is authoritative for
+ *                 `branch` resolution, but the diff `base..branch` is symmetric, so
+ *                 the worktree cwd works for both refs once base is a reachable SHA).
+ */
+export declare function analyzeMeshRefineNodeChangeArea(args: {
+    nodeId: string;
+    workspace: string;
+    branch: string;
+    baseRef: string;
+    branchRef: string;
+    diffCwd: string;
+    submodulePaths: Set<string>;
+}): Promise<MeshRefineBatchNodeChangeArea>;
+/**
+ * Order nodes for batch refinement to minimize cross-sibling conflicts.
+ *
+ * Heuristic (deterministic, stable):
+ *   1. Nodes that do NOT touch any submodule come first — they cannot advance the
+ *      submodule main, so they never force a later submodule rebase.
+ *   2. Within each group, fewer touched top-level paths first (smaller blast radius).
+ *   3. Tie-break by node id for determinism.
+ *
+ * Submodule-touching siblings are intrinsically serial: each one that merges
+ * advances oss main, so the next must rebase. Ordering them last keeps the
+ * non-submodule merges (which never need a submodule rebase) clean and up front.
+ */
+export declare function orderMeshRefineBatchNodes(changeAreas: MeshRefineBatchNodeChangeArea[]): MeshRefineBatchOrderingResult;

package/dist/mesh/mesh-refine-status.d.ts

@@ -24,3 +24,39 @@ export declare function buildMeshAsyncRefineJobs(args: {
     ledgerEntries?: MeshLedgerEntry[];
     pendingEvents?: PendingMeshCoordinatorEvent[];
 }): MeshAsyncRefineJobSummary[];
+/** Terminal refine jobs older than this (relative to the newest job in the set) are
+ * "stale" — already-resolved historical refinery rejections/successes that should not
+ * keep inflating the status counts in mesh_status. 6h covers a long working session
+ * while still folding multi-day-old residue. */
+export declare const STALE_TERMINAL_REFINE_WINDOW_MS: number;
+/** Cap on how many recent terminal jobs are counted even if all fall inside the freshness
+ * window — prevents a burst of refines from dominating the summary. */
+export declare const RECENT_TERMINAL_REFINE_CAP = 8;
+export interface MeshAsyncRefineJobsSummary {
+    /** Count of jobs reflected in `byStatus` (active jobs + recent terminal jobs). */
+    total: number;
+    byStatus: Record<string, number>;
+    /** Terminal jobs dropped from the counts because they are stale residue. */
+    staleTerminal: number;
+    /** Non-terminal (accepted/running) jobs still in flight. */
+    activeJobs: MeshAsyncRefineJobSummary[];
+}
+/**
+ * Build a compact summary of refine jobs that folds stale terminal jobs.
+ *
+ * The full job list (from `buildMeshAsyncRefineJobs`) is derived from a recent ledger
+ * window and deduped by jobId, but it still includes every terminal (completed/failed)
+ * job that happens to fall in that window — including multi-day-old refinery rejections
+ * that have long since been resolved. Those stale terminals inflate `byStatus.failed`
+ * and read as "current breakage" when they are historical noise.
+ *
+ * Active (accepted/running) jobs are always counted. Terminal jobs are counted only when
+ * they are recent: within `STALE_TERMINAL_REFINE_WINDOW_MS` of the newest job's activity
+ * time AND among the `RECENT_TERMINAL_REFINE_CAP` most-recent terminals. Everything else
+ * is folded into `staleTerminal` and excluded from `byStatus`.
+ *
+ * Freshness is measured relative to the newest job in the set (not wall-clock), so the
+ * result is deterministic for a given input — important for tests and for stale-clock
+ * environments.
+ */
+export declare function summarizeMeshAsyncRefineJobs(jobs: MeshAsyncRefineJobSummary[]): MeshAsyncRefineJobsSummary;

package/dist/mesh/mesh-work-queue.d.ts

@@ -100,6 +100,32 @@ export declare function enqueueTask(meshId: string, message: string, opts?: {
     /** Explicit task id for batch/template flows (M5). Random UUID when omitted. */
     id?: string;
 } & MeshQueueMutationOptions): MeshWorkQueueEntry;
+/**
+ * Record a direct-dispatch task (mesh_send_task) as an already-assigned queue
+ * entry so it is attributable to a mission.
+ *
+ * Direct dispatch normally bypasses the queue entirely — the task lives only in
+ * the ledger + mesh_direct_dispatches table, neither of which carries a
+ * missionId, so {@link summarizeMissionTasks}/{@link computeMeshTaskStats}
+ * (which both scan the queue for `task.missionId`) count it as 0. When a
+ * mission is attached, we materialise the same queue entry shape an enqueued
+ * task would have, but pre-assigned to the dispatched node/session and stamped
+ * with the dispatch timestamp. The terminal event path (updateSessionTaskStatus
+ * → findAssignedBySession) then flips it to completed/failed exactly like a
+ * pulled task, so mission total + completed aggregates work with no extra wiring.
+ *
+ * Intentionally separate from {@link enqueueTask}: enqueue creates `pending`
+ * work for the queue to assign, whereas this records work already dispatched
+ * out-of-band. They share the missionId stamping rule and mode validation.
+ */
+export declare function recordDirectDispatchTask(meshId: string, message: string, opts: {
+    id: string;
+    missionId: string;
+    assignedNodeId?: string;
+    assignedSessionId?: string;
+    taskMode?: MeshTaskMode | string;
+    dispatchedAt?: string;
+}): MeshWorkQueueEntry | null;
 /**
  * Get all tasks in the queue, optionally filtered by status.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/daemon-core",
-  "version": "0.9.82-rc.259",
+  "version": "0.9.82-rc.260",
   "description": "ADHDev daemon core — CDP, IDE detection, providers, command execution",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/cli-adapters/cli-state-engine.ts

@@ -107,6 +107,26 @@ export class CliStateEngine {
     // ── Approval ─────────────────────────────────────
     lastApprovalResolvedAt = 0;
     lastResolvedModalMessage = '';
+    /**
+     * Monotonic counter bumped every time the FSM *enters* waiting_approval
+     * with a freshly captured modal (see `applyWaitingApproval`). It is the
+     * single discriminator between "the same approval re-observed across TUI
+     * paint flaps" and "a genuinely new, distinct approval".
+     *
+     * The message-equality cooldown below (`lastResolvedModalMessage`) cannot
+     * tell these apart on its own: claude-cli routinely presents consecutive
+     * approvals whose modal message text is identical (e.g. two back-to-back
+     * Bash-command prompts). When that second approval arrived inside
+     * `approvalCooldown`, the message-equality guard silently swallowed the
+     * key write and the approval stuck forever — fatal under auto-approval.
+     *
+     * `approvalEntrySeq` increments on every fresh entry; `lastResolvedEntrySeq`
+     * records which entry the cooldown belongs to. We only short-circuit the
+     * write when we are still resolving *that same* entry — a new entry (new
+     * seq) is always a real, distinct approval and must be written.
+     */
+    approvalEntrySeq = 0;
+    private lastResolvedEntrySeq = -1;
     /**
      * When the engine previously held a modal but the latest parse failed
      * to extract one, we record the timestamp here and only drop the modal
@@ -239,7 +259,10 @@ export class CliStateEngine {
                     ? parsed.activeModal : null;
                 if (parsed?.status === 'waiting_approval' && parsedModal) {
                     modal = parsedModal;
+                    // No modal was held (`this.activeModal` was null above), so a
+                    // freshly parsed approval here is a new entry by definition.
                     this.activeModal = parsedModal;
+                    this.approvalEntrySeq++;
                     if (this.currentStatus !== 'waiting_approval') {
                         this.setStatus('waiting_approval', 'resolve_modal_parse');
                         this.callbacks.onStatusChange();
@@ -263,13 +286,26 @@ export class CliStateEngine {
         const currentModalMessage = typeof modal?.message === 'string' ? modal.message.trim() : '';
         const inCooldown = !!this.lastApprovalResolvedAt
             && (Date.now() - this.lastApprovalResolvedAt) < this.timeouts.approvalCooldown;
-        if (inCooldown && currentModalMessage === this.lastResolvedModalMessage) return;
+        // (fix) Suppress the duplicate key-write ONLY when this is the *same*
+        // approval entry re-observed across TUI paint flaps — i.e. the FSM has
+        // not entered waiting_approval afresh since the last resolve
+        // (approvalEntrySeq unchanged). A new entry (bumped seq) is always a
+        // distinct approval and must be written, even within the cooldown
+        // window and even when its message text matches the previous one.
+        //
+        // Previously this gated on message equality alone, so consecutive
+        // claude-cli approvals that share message text (very common) had the
+        // second write swallowed — the approval stuck unresolved despite
+        // auto-approval being on.
+        const sameEntryReResolve = this.approvalEntrySeq === this.lastResolvedEntrySeq;
+        if (inCooldown && sameEntryReResolve && currentModalMessage === this.lastResolvedModalMessage) return;
 
         this.clearIdleFinishCandidate('resolve_modal');
-        this.recordTrace('resolve_modal', { buttonIndex, activeModal: modal });
+        this.recordTrace('resolve_modal', { buttonIndex, activeModal: modal, approvalEntrySeq: this.approvalEntrySeq });
         this.activeModal = null;
         this.lastApprovalResolvedAt = Date.now();
         this.lastResolvedModalMessage = currentModalMessage;
+        this.lastResolvedEntrySeq = this.approvalEntrySeq;
         this.responseSettleIgnoreUntil = Date.now() + this.timeouts.outputSettle + 400;
         if (this.approvalExitTimeout) { clearTimeout(this.approvalExitTimeout); this.approvalExitTimeout = null; }
         this.setStatus('generating', 'approval_resolved');
@@ -666,7 +702,19 @@ export class CliStateEngine {
             this.callbacks.onStatusChange();
             return;
         }
-        if (!inCooldown) {
+        // (fix) A *real* modal with valid buttons surfacing during the cooldown
+        // window is a genuinely new approval, not a trailing repaint of the one
+        // we just resolved — resolveModal cleared activeModal and flipped status
+        // to generating, so detectStatus only re-reports waiting_approval with a
+        // concrete modal when the CLI actually presents the next prompt.
+        // Previously this case fell through BOTH the `inCooldown && !modal`
+        // branch above and the `!inCooldown` branch below, so the FSM silently
+        // ignored the second approval — leaving it stuck unresolved under
+        // auto-approval. Capture it like any fresh entry (the modal-message
+        // cooldown still de-dupes the same approval inside resolveModal, now
+        // keyed on approvalEntrySeq). The `!modal` flap case stays gated by
+        // cooldown above; only an actionable new modal breaks through here.
+        if (!inCooldown || modal) {
             if (!modal) {
                 LOG.warn('CLI', `[${this.provider.type}] detectStatus=waiting_approval but parseApproval returned null; ignoring`);
                 // (fix) If we previously surfaced waiting_approval but the
@@ -710,6 +758,11 @@ export class CliStateEngine {
             const nextBtnCount = Array.isArray(modal.buttons) ? modal.buttons.length : 0;
             if (!prev || prevBtnCount !== nextBtnCount) {
                 this.activeModal = modal;
+                // A fresh modal was captured (none held, or the button shape
+                // changed). This is a distinct approval entry — bump the seq so
+                // resolveModal's message-equality cooldown does not mistake it
+                // for a flap-repaint of the previously resolved approval.
+                this.approvalEntrySeq++;
                 this.callbacks.onStatusChange();
             }
             if (this.idleTimeout) clearTimeout(this.idleTimeout);

package/src/cli-adapters/provider-cli-adapter.ts

@@ -940,6 +940,7 @@ export class ProviderCliAdapter implements CliAdapter {
             messages: [],
             workingDir: this.workingDir,
             activeModal: effectiveModal,
+            approvalEntrySeq: this.engine.approvalEntrySeq,
             pendingOutboundCount: this.pendingOutboundQueue.length,
             pendingOutboundMessages: this.pendingOutboundQueue.map((message) => ({
                 id: message.id,

package/src/cli-adapters/provider-cli-shared.ts

@@ -29,6 +29,15 @@ export interface CliSessionStatus {
     messages: CliChatMessage[];
     workingDir: string;
     activeModal: { message: string; buttons: string[] } | null;
+    /**
+     * Monotonic counter identifying which approval *entry* the current modal
+     * belongs to. Bumped by the FSM on every fresh waiting_approval entry.
+     * Consumers (e.g. auto-approval) use it to distinguish a genuinely new
+     * approval from the same approval re-observed across TUI paint flaps —
+     * two distinct approvals can carry identical message/button text, so the
+     * seq is the only reliable discriminator.
+     */
+    approvalEntrySeq?: number;
     activeInteractivePrompt?: InteractivePrompt | null;
     pendingOutboundCount?: number;
     pendingOutboundMessages?: Array<{

package/src/commands/router.ts

@@ -43,6 +43,7 @@ import { handleMeshForwardEvent, drainPendingMeshCoordinatorEvents, getPendingMe
 import { getRecentUnroutableDeliveries } from '../mesh/mesh-routing.js';
 import { buildMeshHostRequiredFailure, normalizeMeshDaemonRole, resolveMeshHostStatus } from '../mesh/mesh-host-ownership.js';
 import { fastForwardMeshNode } from '../mesh/mesh-fast-forward.js';
+import { analyzeMeshRefineNodeChangeArea, orderMeshRefineBatchNodes } from '../mesh/mesh-refine-batch.js';
 import { buildPreviewFreshness } from '../mesh/preview-freshness.js';
 import { buildMeshAsyncRefineJobs } from '../mesh/mesh-refine-status.js';
 import {
@@ -4126,6 +4127,251 @@ export class DaemonCommandRouter {
         }
     }
 
+    /**
+     * Batch refinery: converge multiple sibling worktree nodes onto the base branch
+     * in one sequential pipeline, absorbing the rebase + patch-equivalence churn that
+     * arises when several siblings touch the same submodule.
+     *
+     * Reuses executeMeshRefineNodeSynchronously per node — every node goes through the
+     * exact same validation / patch-equivalence / submodule-reachability / merge / cleanup
+     * gates, including its built-in auto-rebase onto fresh origin/<base>. Because each
+     * node fetches origin/<base> at the start of its own refine, a node merged earlier in
+     * the batch advances the base, and the next node's refine auto-rebases onto it before
+     * re-running patch-equivalence. No force-push, no reset — conflicting nodes are
+     * isolated as blocked_review while the rest of the batch proceeds.
+     */
+    private async batchRefineMeshNodes(meshId: string, requestedNodeIds: string[] | undefined, args: any): Promise<CommandRouterResult> {
+        // preferInline: same membership authority as refine_mesh_node — inline-cache-only
+        // clone nodes (created in this MCP session) must resolve.
+        const meshRecord = await this.getMeshForCommand(meshId, args?.inlineMesh, { preferInline: true });
+        const mesh = meshRecord?.mesh;
+        if (!mesh) return { success: false, error: `Mesh '${meshId}' not found` };
+
+        const allNodes: any[] = Array.isArray(mesh.nodes) ? mesh.nodes : [];
+        const isConvergeable = (n: any) => n?.isLocalWorktree && typeof n.workspace === 'string' && n.workspace;
+
+        let targetNodes: any[];
+        if (Array.isArray(requestedNodeIds) && requestedNodeIds.length > 0) {
+            targetNodes = [];
+            const missing: string[] = [];
+            const nonWorktree: string[] = [];
+            for (const nodeId of requestedNodeIds) {
+                const node = allNodes.find(n => n.id === nodeId || n.nodeId === nodeId);
+                if (!node) { missing.push(nodeId); continue; }
+                if (!isConvergeable(node)) { nonWorktree.push(nodeId); continue; }
+                targetNodes.push(node);
+            }
+            if (missing.length || nonWorktree.length) {
+                return {
+                    success: false,
+                    error: 'One or more requested nodes are not convergeable local worktree nodes.',
+                    ...(missing.length ? { missingNodeIds: missing } : {}),
+                    ...(nonWorktree.length ? { nonWorktreeNodeIds: nonWorktree } : {}),
+                };
+            }
+        } else {
+            // Auto-collect: every local worktree node is a convergence candidate.
+            targetNodes = allNodes.filter(isConvergeable);
+        }
+
+        if (targetNodes.length === 0) {
+            return { success: true, batch: true, dryRun: args?.dryRun !== false, nodeCount: 0, order: [], results: [], note: 'No convergeable local worktree nodes found.' };
+        }
+
+        const { execFile } = await import('node:child_process');
+        const { promisify } = await import('node:util');
+        const execFileAsync = promisify(execFile);
+
+        // Resolve the base repo root and a base ref to analyze change areas against.
+        const resolveRepoRootFor = (node: any): string | undefined => {
+            const sourceNode = node.clonedFromNodeId
+                ? allNodes.find(n => n.id === node.clonedFromNodeId || n.nodeId === node.clonedFromNodeId)
+                : allNodes.find(n => !n.isLocalWorktree);
+            return sourceNode?.repoRoot || sourceNode?.workspace;
+        };
+
+        // Analyze change areas for ordering. The repoRoot is shared across siblings of
+        // the same source; resolve a base ref (origin/<base> preferred) once per repoRoot.
+        const repoRootBaseRef = new Map<string, string>();
+        const submodulePathsByRepoRoot = new Map<string, Set<string>>();
+        const resolveBaseRef = async (repoRoot: string): Promise<string> => {
+            const cached = repoRootBaseRef.get(repoRoot);
+            if (cached) return cached;
+            let baseBranch = 'main';
+            try {
+                const { stdout } = await execFileAsync('git', ['branch', '--show-current'], { cwd: repoRoot, encoding: 'utf8' });
+                if (stdout.trim()) baseBranch = stdout.trim();
+            } catch { /* fall back to main */ }
+            let baseRef = 'HEAD';
+            try {
+                await execFileAsync('git', ['fetch', 'origin', baseBranch], { cwd: repoRoot, encoding: 'utf8' });
+            } catch { /* offline / no remote — fall through to local refs */ }
+            try {
+                const { stdout } = await execFileAsync('git', ['rev-parse', `origin/${baseBranch}`], { cwd: repoRoot, encoding: 'utf8' });
+                baseRef = stdout.trim();
+            } catch {
+                try {
+                    const { stdout } = await execFileAsync('git', ['rev-parse', 'HEAD'], { cwd: repoRoot, encoding: 'utf8' });
+                    baseRef = stdout.trim();
+                } catch { /* leave HEAD */ }
+            }
+            repoRootBaseRef.set(repoRoot, baseRef);
+            return baseRef;
+        };
+
+        const changeAreas: Array<Awaited<ReturnType<typeof analyzeMeshRefineNodeChangeArea>>> = [];
+        for (const node of targetNodes) {
+            const repoRoot = resolveRepoRootFor(node);
+            let branch = typeof node.worktreeBranch === 'string' ? node.worktreeBranch : '';
+            try {
+                const { stdout } = await execFileAsync('git', ['branch', '--show-current'], { cwd: node.workspace, encoding: 'utf8' });
+                if (stdout.trim()) branch = stdout.trim();
+            } catch { /* use stored worktreeBranch */ }
+
+            if (!repoRoot || !branch) {
+                changeAreas.push({
+                    nodeId: node.id, workspace: node.workspace, branch: branch || '(unknown)',
+                    changedTopLevelPaths: [], changedFiles: [], touchedSubmodulePaths: [],
+                    touchesSubmodule: false, aheadCount: 0,
+                    error: !repoRoot ? 'source repoRoot not found' : 'branch not resolved',
+                });
+                continue;
+            }
+            if (!submodulePathsByRepoRoot.has(repoRoot)) {
+                // Resolve declared submodule paths once per repo root.
+                let subPaths = new Set<string>();
+                try {
+                    const { stdout } = await execFileAsync('git', ['config', '--file', '.gitmodules', '--get-regexp', 'path'], { cwd: repoRoot, encoding: 'utf8' });
+                    for (const line of stdout.split('\n')) {
+                        const trimmed = line.trim();
+                        const spaceIdx = trimmed.indexOf(' ');
+                        if (spaceIdx === -1) continue;
+                        const value = trimmed.slice(spaceIdx + 1).trim();
+                        if (value) subPaths.add(value);
+                    }
+                } catch { subPaths = new Set(); }
+                submodulePathsByRepoRoot.set(repoRoot, subPaths);
+            }
+            const baseRef = await resolveBaseRef(repoRoot);
+            let branchRef = branch;
+            try {
+                const { stdout } = await execFileAsync('git', ['rev-parse', branch], { cwd: node.workspace, encoding: 'utf8' });
+                branchRef = stdout.trim() || branch;
+            } catch { /* use branch name */ }
+            changeAreas.push(await analyzeMeshRefineNodeChangeArea({
+                nodeId: node.id,
+                workspace: node.workspace,
+                branch,
+                baseRef,
+                branchRef,
+                diffCwd: node.workspace,
+                submodulePaths: submodulePathsByRepoRoot.get(repoRoot)!,
+            }));
+        }
+
+        const ordering = orderMeshRefineBatchNodes(changeAreas);
+        const orderedNodes = ordering.order
+            .map(nodeId => targetNodes.find(n => n.id === nodeId || n.nodeId === nodeId))
+            .filter((n): n is any => !!n);
+
+        const dryRun = args?.dryRun !== false && args?.execute !== true;
+        if (dryRun) {
+            return {
+                success: true,
+                batch: true,
+                dryRun: true,
+                nodeCount: orderedNodes.length,
+                order: ordering.order,
+                orderingRationale: ordering.rationale,
+                changeAreas: ordering.changeAreas,
+                plan: orderedNodes.map(node => ({
+                    nodeId: node.id,
+                    workspace: node.workspace,
+                    validationPlan: buildMeshRefineValidationPlan(mesh, node.workspace),
+                    mergeWillRun: false,
+                })),
+                note: 'Dry-run: no validation, rebase, or merge was executed. Re-run with execute=true to converge nodes in this order.',
+            };
+        }
+
+        // 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.
+        type BatchNodeOutcome = {
+            nodeId: string;
+            workspace: string;
+            convergence: 'merged_to_main' | 'blocked_review' | 'skipped_patch_equivalent' | 'not_mergeable';
+            code?: string;
+            reason?: string;
+            stage?: string;
+            error?: string;
+            finalBranchConvergenceState?: Record<string, unknown>;
+        };
+        const results: BatchNodeOutcome[] = [];
+        for (const node of orderedNodes) {
+            let result: Record<string, unknown>;
+            try {
+                result = await this.executeMeshRefineNodeSynchronously(meshId, node.id, args) as Record<string, unknown>;
+            } catch (e: any) {
+                result = { success: false, error: e?.message || String(e) };
+            }
+            const code = typeof result.code === 'string' ? result.code : '';
+            // already_merged (branch content already on base via another path) is a
+            // non-error skip regardless of success flag — the worktree converges with
+            // no new merge. A real `git merge` conflict surfaces as merge_failed →
+            // not_mergeable. Everything else that failed is isolated as blocked_review.
+            let convergence: BatchNodeOutcome['convergence'];
+            if (code === 'already_merged' && result.alreadyMergedViaOtherPath) {
+                convergence = 'skipped_patch_equivalent';
+            } else if (result.success === true) {
+                convergence = 'merged_to_main';
+            } else if (code === 'merge_failed') {
+                convergence = 'not_mergeable';
+            } else {
+                convergence = 'blocked_review';
+            }
+            const fbcs = (result.finalBranchConvergenceState && typeof result.finalBranchConvergenceState === 'object')
+                ? result.finalBranchConvergenceState as Record<string, unknown>
+                : undefined;
+            const stage = Array.isArray(result.refineStages)
+                ? (result.refineStages as Array<Record<string, unknown>>).filter(s => s.status === 'failed').map(s => s.stage).filter(Boolean).pop() as string | undefined
+                : undefined;
+            results.push({
+                nodeId: node.id,
+                workspace: node.workspace,
+                convergence,
+                ...(code ? { code } : {}),
+                ...(typeof result.blockedReason === 'string' ? { reason: result.blockedReason } : {}),
+                ...(stage ? { stage } : {}),
+                ...(typeof result.error === 'string' ? { error: result.error } : {}),
+                ...(fbcs ? { finalBranchConvergenceState: fbcs } : {}),
+            });
+        }
+
+        const summary = {
+            merged: results.filter(r => r.convergence === 'merged_to_main').length,
+            skipped: results.filter(r => r.convergence === 'skipped_patch_equivalent').length,
+            blocked: results.filter(r => r.convergence === 'blocked_review').length,
+            notMergeable: results.filter(r => r.convergence === 'not_mergeable').length,
+        };
+        const allConverged = summary.blocked === 0 && summary.notMergeable === 0;
+        return {
+            success: true,
+            batch: true,
+            dryRun: false,
+            nodeCount: orderedNodes.length,
+            order: ordering.order,
+            orderingRationale: ordering.rationale,
+            summary,
+            allConverged,
+            results,
+            ...(allConverged ? {} : {
+                nextStep: 'Resolve blocked_review / not_mergeable nodes manually (see per-node code/stage/error), then re-run mesh_refine_batch for the remaining nodes.',
+            }),
+        };
+    }
+
     private async finishMeshRefineJob(handle: MeshRefineJobHandle, args: any): Promise<void> {
         const key = this.buildRefineJobKey(handle.meshId, handle.targetNodeId);
         let result: Record<string, unknown>;
@@ -5944,6 +6190,15 @@ export class DaemonCommandRouter {
                 return this.startMeshRefineJob(meshId, nodeId, args);
             }
 
+            case 'batch_refine_mesh_nodes': {
+                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 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);
+            }
+
             case 'remove_mesh_node': {
                 const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
                 const nodeId = typeof args?.nodeId === 'string' ? args.nodeId.trim() : '';

package/src/index.ts

@@ -217,12 +217,12 @@ export { buildMeshLedgerReconciliationEvidence, buildMeshLedgerReplicaEvidence }
 export type { AnyLedgerSlice, MeshLedgerReconciliationEvidence, MeshLedgerReplicaEvidence, MeshLedgerReplicaStatus } from './mesh/mesh-ledger-reconciliation.js';
 
 // ── Mesh Work Queue (GUPP) ──
-export { enqueueTask, getQueue, claimNextTask, updateTaskStatus, updateSessionTaskStatus, cancelTask, requeueTask, getMeshQueueStats, getMeshQueueRevision, normalizeMeshTaskMode, validateMeshTaskModeRequest, buildMeshNodeCapabilityTags, nodeSatisfiesRequiredTags, normalizeMeshCapabilityTags, insertDirectDispatch, getActiveDirectDispatches, updateDirectDispatchStatus, cleanupTerminalDirectDispatches, markStaleDirectDispatches, recordMeshToolCall, assertNoDependencyCycle, hasPendingDependents, describeTaskDependencyState } from './mesh/mesh-work-queue.js';
+export { enqueueTask, recordDirectDispatchTask, getQueue, claimNextTask, updateTaskStatus, updateSessionTaskStatus, cancelTask, requeueTask, getMeshQueueStats, getMeshQueueRevision, normalizeMeshTaskMode, validateMeshTaskModeRequest, buildMeshNodeCapabilityTags, nodeSatisfiesRequiredTags, normalizeMeshCapabilityTags, insertDirectDispatch, getActiveDirectDispatches, updateDirectDispatchStatus, cleanupTerminalDirectDispatches, markStaleDirectDispatches, recordMeshToolCall, assertNoDependencyCycle, hasPendingDependents, describeTaskDependencyState } from './mesh/mesh-work-queue.js';
 export type { MeshWorkQueueEntry, MeshTaskStatus, MeshTaskMode, MeshWorkQueueStats, MeshQueueMutationOptions, MeshTaskModeValidationResult, DirectDispatchRecord, MeshToolCallRateResult } from './mesh/mesh-work-queue.js';
 export { buildCompactStaleDirectWorkSummary, buildMeshActiveWork, buildMeshActiveWorkSummary } from './mesh/mesh-active-work.js';
 export type { MeshActiveWorkRecord, MeshActiveWorkStatus, MeshActiveWorkSummary, MeshActiveWorkSource, MeshStaleDirectWorkSummary } from './mesh/mesh-active-work.js';
-export { buildMeshAsyncRefineJobs } from './mesh/mesh-refine-status.js';
-export type { MeshAsyncRefineJobStatus, MeshAsyncRefineJobSummary } from './mesh/mesh-refine-status.js';
+export { buildMeshAsyncRefineJobs, summarizeMeshAsyncRefineJobs, STALE_TERMINAL_REFINE_WINDOW_MS, RECENT_TERMINAL_REFINE_CAP } from './mesh/mesh-refine-status.js';
+export type { MeshAsyncRefineJobStatus, MeshAsyncRefineJobSummary, MeshAsyncRefineJobsSummary } from './mesh/mesh-refine-status.js';
 
 // ── Mesh Host Ownership ──
 export { buildMeshHostRequiredFailure, createDefaultMeshHostMetadata, isMeshHostOwner, normalizeMeshDaemonRole, requireMeshHostQueueOwner, resolveMeshHostStatus } from './mesh/mesh-host-ownership.js';