@adhdev/daemon-core 0.9.82-rc.209 → 0.9.82-rc.210

package/src/commands/router.ts

@@ -56,6 +56,7 @@ import {
 import {
     MESH_WORKTREE_BOOTSTRAP_CONFIG_LOCATIONS,
     MESH_WORKTREE_BOOTSTRAP_CONFIG_SCHEMA,
+    evaluateWorktreeBootstrapState,
     loadMeshWorktreeBootstrapConfig,
     runMeshWorktreeBootstrap,
     type WorktreeBootstrapState,
@@ -940,6 +941,7 @@ function finalizeMeshNodeStatus(args: {
             status.launchBlockedReason = 'worktree_bootstrap_failed';
             status.launchBlockedMessage = readStringValue(bootstrap.error)
                 || 'Required worktree bootstrap failed; resolve it before launching an agent into this node.';
+            status.recoveryHint = 'Run retry_mesh_node_bootstrap to retry';
             return;
         }
         if (bootstrap.status === 'running' && bootstrap.required !== false) {
@@ -1306,6 +1308,27 @@ type MeshRefineValidationSummary = {
     configSourceType?: string;
     suggestions?: unknown[];
     suggestedConfig?: unknown;
+    /**
+     * M2-3: the bootstrap stage recorded separately from validation so review
+     * surfaces can distinguish environment failures from validation failures.
+     *   cached — worktree_bootstrap was 'ready' (staleInputs unchanged), skipped
+     *   ran    — worktree_bootstrap was stale/never-ran and re-ran successfully
+     *   failed — bootstrap run failed (refine stops before validation)
+     *   skipped — refine config validation.bootstrap === 'skip'
+     *   legacy — deprecated validation.bootstrapCommands path was used
+     *   not_configured — no bootstrap definition anywhere
+     */
+    bootstrap?: {
+        stage: 'cached' | 'ran' | 'failed' | 'skipped' | 'legacy' | 'not_configured';
+        status?: string;
+        skipped?: boolean;
+        configSource?: string;
+        staleReason?: string;
+        error?: string;
+        commandsRun?: Array<Record<string, unknown>>;
+    };
+    /** M2-2: deprecation notices from the refine config (e.g. bootstrapCommands). */
+    deprecationWarnings?: string[];
 };
 
 type MeshRefineStageStatus = 'passed' | 'failed' | 'skipped';
@@ -1404,6 +1427,12 @@ type MeshRefineJobHandle = {
     completedAt?: string;
     duplicate?: boolean;
     retryOfJobId?: string;
+    /**
+     * The coordinator daemon ID that initiated this refine job.
+     * When set, events for this job are scoped to that coordinator's
+     * pending-events queue instead of the shared broadcast queue.
+     */
+    targetCoordinatorDaemonId?: string;
     eventDelivery: {
         pendingEvents: true;
         ledger: true;
@@ -1919,7 +1948,16 @@ function buildMeshRefineValidationPlan(mesh: any, workspace: string): Record<str
     };
 }
 
-async function runMeshRefineValidationGate(mesh: any, workspace: string): Promise<MeshRefineValidationSummary> {
+async function runMeshRefineValidationGate(
+    mesh: any,
+    workspace: string,
+    opts?: {
+        /** M2-2: persisted node bootstrap state for staleness evaluation. */
+        persistedBootstrapState?: WorktreeBootstrapState | null;
+        /** M2-2: called after an inherit-mode bootstrap run so the caller can persist the new state. */
+        onBootstrapStateChange?: (state: WorktreeBootstrapState) => void;
+    },
+): Promise<MeshRefineValidationSummary> {
     const { execFile } = await import('node:child_process');
     const { promisify } = await import('node:util');
     const execFileAsync = promisify(execFile);
@@ -1937,6 +1975,7 @@ async function runMeshRefineValidationGate(mesh: any, workspace: string): Promis
         configSourceType: selection.sourceType,
         suggestions: selection.suggestions,
         suggestedConfig: selection.suggestedConfig,
+        ...(selection.deprecationWarnings.length > 0 ? { deprecationWarnings: selection.deprecationWarnings } : {}),
     };
 
     if (!selection.commands.length) {
@@ -1944,6 +1983,52 @@ async function runMeshRefineValidationGate(mesh: any, workspace: string): Promis
         return summary;
     }
 
+    // ── M2-2: Bootstrap stage — refine consumes the worktree_bootstrap config
+    //    instead of defining its own. Legacy validation.bootstrapCommands run
+    //    only when no worktree_bootstrap config exists (deprecation path).
+    let runLegacyBootstrapCommands = selection.bootstrapCommands.length > 0;
+    if (selection.bootstrapMode === 'skip') {
+        summary.bootstrap = { stage: 'skipped', skipped: true };
+        runLegacyBootstrapCommands = false;
+    } else {
+        const wbLoad = loadMeshWorktreeBootstrapConfig(mesh, workspace);
+        const wbUsable = !!wbLoad.config && wbLoad.sourceType !== 'invalid'
+            && wbLoad.config.enabled !== false && wbLoad.config.runOnClone !== false;
+        if (wbUsable) {
+            runLegacyBootstrapCommands = false; // worktree_bootstrap wins over deprecated bootstrapCommands
+            const evaluated = evaluateWorktreeBootstrapState(mesh, workspace, opts?.persistedBootstrapState);
+            if (evaluated.status === 'ready') {
+                summary.bootstrap = { stage: 'cached', status: 'ready', skipped: true, configSource: evaluated.configSource };
+            } else {
+                const ran = await runMeshWorktreeBootstrap(mesh, workspace);
+                try { opts?.onBootstrapStateChange?.(ran); } catch { /* persistence is best-effort */ }
+                if (ran.status === 'ready') {
+                    summary.bootstrap = {
+                        stage: 'ran',
+                        status: 'ready',
+                        configSource: ran.configSource,
+                        ...(evaluated.staleReason ? { staleReason: evaluated.staleReason } : {}),
+                        commandsRun: ran.commandsRun,
+                    };
+                } else {
+                    summary.bootstrap = {
+                        stage: 'failed',
+                        status: ran.status,
+                        configSource: ran.configSource,
+                        error: ran.error,
+                        commandsRun: ran.commandsRun,
+                    };
+                    summary.status = 'failed';
+                    summary.failureKind = 'dependency_bootstrap_failed';
+                    summary.failureCode = 'dependency_bootstrap_failed';
+                    return summary;
+                }
+            }
+        } else if (!runLegacyBootstrapCommands) {
+            summary.bootstrap = { stage: 'not_configured' };
+        }
+    }
+
     const commandRecord = (candidate: MeshRefineValidationCommand, cwd: string, startedAt: number, result: any, passed: boolean, extras: Record<string, unknown> = {}) => ({
         command: candidate.command,
         args: candidate.args,
@@ -1969,30 +2054,34 @@ async function runMeshRefineValidationGate(mesh: any, workspace: string): Promis
             .some(lock => fs.existsSync(pathJoin(cwd, lock)));
     };
 
-    for (const candidate of selection.bootstrapCommands) {
-        const startedAt = Date.now();
-        const cwd = candidate.cwd ? pathResolve(workspace, candidate.cwd) : workspace;
-        const timeout = candidate.timeoutMs || REFINE_VALIDATION_TIMEOUT_MS;
-        try {
-            const result = await execFileAsync(candidate.command, candidate.args, {
-                cwd,
-                encoding: 'utf8',
-                timeout,
-                maxBuffer: candidate.outputLimitBytes || REFINE_VALIDATION_OUTPUT_LIMIT_BYTES,
-                env: { ...process.env, CI: process.env.CI || '1', ...(candidate.env || {}) },
-            });
-            summary.bootstrapCommandsRun.push(commandRecord(candidate, cwd, startedAt, result, true, { exitCode: 0 }));
-        } catch (error: any) {
-            summary.bootstrapCommandsRun.push(commandRecord(candidate, cwd, startedAt, error, false, {
-                exitCode: typeof error?.code === 'number' ? error.code : null,
-                signal: typeof error?.signal === 'string' ? error.signal : null,
-                timedOut: error?.killed === true || /timed out/i.test(String(error?.message || '')),
-                failureKind: 'dependency_bootstrap_failed',
-            }));
-            summary.status = 'failed';
-            summary.failureKind = 'dependency_bootstrap_failed';
-            summary.failureCode = 'dependency_bootstrap_failed';
-            return summary;
+    if (runLegacyBootstrapCommands) {
+        summary.bootstrap = { stage: 'legacy' };
+        for (const candidate of selection.bootstrapCommands) {
+            const startedAt = Date.now();
+            const cwd = candidate.cwd ? pathResolve(workspace, candidate.cwd) : workspace;
+            const timeout = candidate.timeoutMs || REFINE_VALIDATION_TIMEOUT_MS;
+            try {
+                const result = await execFileAsync(candidate.command, candidate.args, {
+                    cwd,
+                    encoding: 'utf8',
+                    timeout,
+                    maxBuffer: candidate.outputLimitBytes || REFINE_VALIDATION_OUTPUT_LIMIT_BYTES,
+                    env: { ...process.env, CI: process.env.CI || '1', ...(candidate.env || {}) },
+                });
+                summary.bootstrapCommandsRun.push(commandRecord(candidate, cwd, startedAt, result, true, { exitCode: 0 }));
+            } catch (error: any) {
+                summary.bootstrapCommandsRun.push(commandRecord(candidate, cwd, startedAt, error, false, {
+                    exitCode: typeof error?.code === 'number' ? error.code : null,
+                    signal: typeof error?.signal === 'string' ? error.signal : null,
+                    timedOut: error?.killed === true || /timed out/i.test(String(error?.message || '')),
+                    failureKind: 'dependency_bootstrap_failed',
+                }));
+                summary.bootstrap = { stage: 'failed', error: String(error?.message || error) };
+                summary.status = 'failed';
+                summary.failureKind = 'dependency_bootstrap_failed';
+                summary.failureCode = 'dependency_bootstrap_failed';
+                return summary;
+            }
         }
     }
 
@@ -2000,7 +2089,8 @@ async function runMeshRefineValidationGate(mesh: any, workspace: string): Promis
         const startedAt = Date.now();
         const cwd = candidate.cwd ? pathResolve(workspace, candidate.cwd) : workspace;
         const timeout = candidate.timeoutMs || REFINE_VALIDATION_TIMEOUT_MS;
-        if (selection.bootstrapCommands.length === 0 && isPackageManagerValidation(candidate) && dependenciesLikelyMissing(cwd)) {
+        const bootstrapProvidedDependencies = summary.bootstrap?.stage === 'cached' || summary.bootstrap?.stage === 'ran' || summary.bootstrap?.stage === 'legacy';
+        if (!bootstrapProvidedDependencies && isPackageManagerValidation(candidate) && dependenciesLikelyMissing(cwd)) {
             summary.commandsRun.push(commandRecord(candidate, cwd, startedAt, {
                 stderr: 'Dependencies appear to be missing: package.json and a lockfile are present, but node_modules is absent. Configure validation.bootstrapCommands in repo mesh/refine config if Refinery should install/bootstrap before validation.',
             }, false, {
@@ -2599,6 +2689,7 @@ export class DaemonCommandRouter {
         mesh: any;
         node: any;
         nodeId: string;
+        force?: boolean;
     }): Promise<{ success: true; skipped?: boolean; removedPath?: string; repoRoot?: string; reason?: string; fallback?: string; forced?: boolean; convergence?: Record<string, unknown> } | { success: false; code: string; error: string; recoveryHint: string; convergence?: Record<string, unknown> }> {
         const workspace = typeof args.node?.workspace === 'string' ? args.node.workspace.trim() : '';
         if (!workspace) {
@@ -2675,15 +2766,13 @@ export class DaemonCommandRouter {
             };
         }
 
-        const forceFallbackConvergence = await this.getWorktreeForceCleanupConvergence({
-            repoRoot,
-            workspace,
-            node: args.node,
-        });
+        const forceFallbackConvergence = args.force
+            ? { allow: true, status: 'force_override', source: 'caller_force_flag' }
+            : await this.getWorktreeForceCleanupConvergence({ repoRoot, workspace, node: args.node });
 
         try {
             const result = await removeWorktree(repoRoot, workspace, {
-                requireClean: true,
+                requireClean: !args.force,
                 allowSubmoduleForceFallback: forceFallbackConvergence.allow,
             });
             return {
@@ -2714,7 +2803,7 @@ export class DaemonCommandRouter {
                 recoveryHint: dirty
                     ? 'Commit, stash, or intentionally discard the worktree changes before retrying mesh_remove_node. The mesh registry entry is preserved until cleanup is safe.'
                     : submoduleForceBlocked
-                        ? 'Verify the worktree branch is merged/contained in the source default branch (for example origin/main) or mark the node with a safe branchConvergence final state before retrying. The mesh registry entry is preserved.'
+                        ? 'Verify the worktree branch is merged/contained in the source default branch (for example origin/main) or mark the node with a safe branchConvergence final state, or pass force:true if content is confirmed already in main.'
                         : 'Inspect git worktree status/list from the source repo and retry after resolving the reported cleanup failure.',
                 ...(submoduleForceBlocked ? { convergence: forceFallbackConvergence } : {}),
             };
@@ -3117,6 +3206,7 @@ export class DaemonCommandRouter {
         jobId?: string;
         interactionId?: string;
         retryOfJobId?: string;
+        coordinatorDaemonId?: string;
     }): MeshRefineJobHandle {
         return {
             success: true,
@@ -3132,6 +3222,7 @@ export class DaemonCommandRouter {
             startedAt: args.startedAt || new Date().toISOString(),
             ...(args.completedAt ? { completedAt: args.completedAt } : {}),
             ...(args.retryOfJobId ? { retryOfJobId: args.retryOfJobId } : {}),
+            ...(args.coordinatorDaemonId ? { targetCoordinatorDaemonId: args.coordinatorDaemonId } : {}),
             eventDelivery: { pendingEvents: true, ledger: true },
             evidence: {
                 pendingEventsCommand: 'get_pending_mesh_events',
@@ -3164,6 +3255,7 @@ export class DaemonCommandRouter {
             workspace: handle.workspace,
             metadataEvent,
             queuedAt: Date.now(),
+            ...(handle.targetCoordinatorDaemonId ? { targetCoordinatorDaemonId: handle.targetCoordinatorDaemonId } : {}),
         };
         if (typeof this.deps.instanceManager?.getByCategory === 'function') {
             const forwarded = handleMeshForwardEvent(
@@ -3204,6 +3296,7 @@ export class DaemonCommandRouter {
                         meshId: handle.meshId,
                         nodeId: handle.targetNodeId,
                         targetDaemonId: handle.targetDaemonId,
+                        targetCoordinatorDaemonId: handle.targetCoordinatorDaemonId,
                         workspace: handle.workspace,
                         startedAt: handle.startedAt,
                         completedAt: handle.completedAt,
@@ -3223,6 +3316,47 @@ export class DaemonCommandRouter {
         }
     }
 
+    /**
+     * On daemon restart, scan all mesh ledgers for refine jobs that were dispatched
+     * but never completed/failed (i.e. the daemon died mid-job).  Re-queue each one
+     * so the job runs to completion automatically without coordinator intervention.
+     */
+    async resumePendingRefineJobsOnStartup(): Promise<void> {
+        try {
+            const { listMeshes } = await import('../config/mesh-config.js');
+            const { readLedgerEntries } = await import('../mesh/mesh-ledger.js');
+            const meshIds: string[] = listMeshes().map(m => m.id).filter(Boolean) as string[];
+            for (const meshId of meshIds) {
+                const entries = readLedgerEntries(meshId, { kind: ['task_dispatched', 'task_completed', 'task_failed'] });
+                // Build set of nodeIds that already have a terminal entry.
+                const terminal = new Set<string>();
+                for (const e of entries) {
+                    if ((e.kind === 'task_completed' || e.kind === 'task_failed') && e.nodeId) {
+                        const jobId = (e.payload as any)?.refineJob?.jobId;
+                        if (jobId) terminal.add(`${e.nodeId}:${jobId}`);
+                    }
+                }
+                // Re-dispatch dispatched jobs with no matching terminal entry.
+                for (const e of entries) {
+                    if (e.kind !== 'task_dispatched' || !e.nodeId) continue;
+                    const source = (e.payload as any)?.source;
+                    if (source !== 'refine_mesh_node_async_job') continue;
+                    const jobId = (e.payload as any)?.refineJob?.jobId;
+                    if (!jobId || terminal.has(`${e.nodeId}:${jobId}`)) continue;
+                    const key = this.buildRefineJobKey(meshId, e.nodeId);
+                    if (this.runningRefineJobs.has(key)) continue;
+                    const coordinatorDaemonId = (e.payload as any)?.refineJob?.targetCoordinatorDaemonId;
+                    LOG.info('Mesh', `[Refinery] Auto-resuming interrupted refine job for node ${e.nodeId} (jobId=${jobId})`);
+                    void this.startMeshRefineJob(meshId, e.nodeId, {
+                        coordinatorDaemonId,
+                    });
+                }
+            }
+        } catch (e: any) {
+            LOG.warn('Mesh', `[Refinery] resumePendingRefineJobsOnStartup failed: ${e?.message || e}`);
+        }
+    }
+
     private async executeMeshRefineNodeSynchronously(meshId: string, nodeId: string, args: any): Promise<CommandRouterResult> {
         const refineStages: Array<Record<string, unknown>> = [];
         try {
@@ -3255,11 +3389,20 @@ export class DaemonCommandRouter {
             const { stdout: baseHeadStdout } = await execFileAsync('git', ['rev-parse', 'HEAD'], { cwd: repoRoot, encoding: 'utf8' });
             const { stdout: branchHeadStdout } = await execFileAsync('git', ['rev-parse', branch], { cwd: node.workspace, encoding: 'utf8' });
             const baseHead = baseHeadStdout.trim();
-            const branchHead = branchHeadStdout.trim();
+            let branchHead = branchHeadStdout.trim();
             recordMeshRefineStage(refineStages, 'resolve_refs', 'passed', resolveStarted, { branch, baseBranch, baseHead, branchHead });
 
             const validationStarted = Date.now();
-            const validationSummary = await runMeshRefineValidationGate(mesh, node.workspace);
+            const validationSummary = await runMeshRefineValidationGate(mesh, node.workspace, {
+                // M2-2: consume the node's persisted bootstrap state; persist re-runs.
+                persistedBootstrapState: (node as any).worktreeBootstrap as WorktreeBootstrapState | undefined,
+                onBootstrapStateChange: (state) => {
+                    (node as any).worktreeBootstrap = state;
+                    void import('../config/mesh-config.js')
+                        .then(({ updateNode }) => updateNode(mesh.id, node.id, { worktreeBootstrap: state } as any))
+                        .catch(() => { /* persistence is best-effort */ });
+                },
+            });
             recordMeshRefineStage(
                 refineStages,
                 'validation',
@@ -3313,7 +3456,7 @@ export class DaemonCommandRouter {
             }
 
             const patchEquivalenceStarted = Date.now();
-            const patchEquivalence = await runMeshRefinePatchEquivalenceGate(repoRoot, baseHead, branchHead);
+            let patchEquivalence = await runMeshRefinePatchEquivalenceGate(repoRoot, baseHead, branchHead);
             recordMeshRefineStage(refineStages, 'patch_equivalence', patchEquivalence.status, patchEquivalenceStarted, {
                 equivalent: patchEquivalence.equivalent,
                 expectedPatchId: patchEquivalence.expectedPatchId,
@@ -3322,26 +3465,171 @@ export class DaemonCommandRouter {
                 actionableHint: patchEquivalence.actionableHint,
             });
             if (!patchEquivalence.equivalent) {
-                return {
-                    success: false,
-                    code: 'patch_equivalence_failed',
-                    convergenceStatus: 'blocked_review',
-                    error: 'Refinery patch-equivalence preflight failed; merge/refine was not attempted.',
-                    branch,
-                    into: baseBranch,
-                    validationSummary,
-                    patchEquivalence,
-                    refineStages,
-                    finalBranchConvergenceState: {
-                branch,
-                baseBranch,
-                merged: false,
-                removed: false,
-                validation: 'passed',
-                patchEquivalence: 'failed',
-                status: 'blocked_review',
-                    },
-                };
+                // Auto-rebase: if branch is simply behind base, attempt rebase automatically before failing.
+                let didAutoRebase = false;
+                let isBehindBase = false;
+                try {
+                    execFileSync('git', ['merge-base', '--is-ancestor', branchHead, baseHead], {
+                        cwd: node.workspace,
+                        stdio: 'ignore',
+                    });
+                    isBehindBase = true;
+                } catch { /* non-zero exit means branchHead is not an ancestor of baseHead */ }
+
+                if (isBehindBase) {
+                    const autoRebaseStarted = Date.now();
+                    try {
+                        execFileSync('git', ['rebase', baseHead], {
+                            cwd: node.workspace,
+                            stdio: ['ignore', 'pipe', 'pipe'],
+                        });
+                        const { stdout: rebasedHeadStdout } = await execFileAsync('git', ['rev-parse', 'HEAD'], { cwd: node.workspace, encoding: 'utf8' });
+                        branchHead = rebasedHeadStdout.trim();
+                        const rebasedPatchEquivalence = await runMeshRefinePatchEquivalenceGate(repoRoot, baseHead, branchHead);
+                        recordMeshRefineStage(refineStages, 'patch_equivalence_after_auto_rebase', rebasedPatchEquivalence.status, autoRebaseStarted, {
+                            equivalent: rebasedPatchEquivalence.equivalent,
+                            expectedPatchId: rebasedPatchEquivalence.expectedPatchId,
+                            actualPatchId: rebasedPatchEquivalence.actualPatchId,
+                            error: rebasedPatchEquivalence.error,
+                            rebasedBranchHead: branchHead,
+                        });
+                        if (rebasedPatchEquivalence.equivalent) {
+                            patchEquivalence = rebasedPatchEquivalence;
+                            didAutoRebase = true;
+                        } else {
+                            return {
+                                success: false,
+                                code: 'needs_rebase',
+                                convergenceStatus: 'blocked_review',
+                                error: 'Branch was rebased onto base but patch equivalence still failed; manual intervention required.',
+                                branch,
+                                into: baseBranch,
+                                validationSummary,
+                                patchEquivalence: rebasedPatchEquivalence,
+                                refineStages,
+                                finalBranchConvergenceState: {
+                                    branch,
+                                    baseBranch,
+                                    merged: false,
+                                    removed: false,
+                                    validation: 'passed',
+                                    patchEquivalence: 'failed',
+                                    status: 'blocked_review',
+                                },
+                            };
+                        }
+                    } catch (rebaseErr: any) {
+                        try { execFileSync('git', ['rebase', '--abort'], { cwd: node.workspace, stdio: 'ignore' }); } catch { /* ignore */ }
+                        recordMeshRefineStage(refineStages, 'patch_equivalence_after_auto_rebase', 'failed', autoRebaseStarted, {
+                            error: rebaseErr?.message || String(rebaseErr),
+                        });
+                        return {
+                            success: false,
+                            code: 'needs_rebase_with_conflicts',
+                            convergenceStatus: 'blocked_review',
+                            error: 'Branch is behind base and auto-rebase failed due to conflicts; resolve conflicts manually and retry.',
+                            branch,
+                            into: baseBranch,
+                            validationSummary,
+                            patchEquivalence,
+                            refineStages,
+                            finalBranchConvergenceState: {
+                                branch,
+                                baseBranch,
+                                merged: false,
+                                removed: false,
+                                validation: 'passed',
+                                patchEquivalence: 'failed',
+                                status: 'blocked_review',
+                            },
+                        };
+                    }
+                }
+
+                // If the actual patch-id is empty, the merge-tree produces no diff vs base —
+                // meaning the branch content is already present in base (landed via a different
+                // path, e.g. cherry-pick or direct commit).  Treat this as "already merged":
+                // skip the merge step but still run cleanup so the worktree node is removed.
+                // "already merged via another path": the branch has real changes
+                // (expectedPatchId non-empty) but the merge-tree produces no diff
+                // against base (actualPatchId empty) — meaning every change in the
+                // branch is already present in base via a cherry-pick or direct commit.
+                // If both patch-ids are empty, the branch itself has no changes; that
+                // is a degenerate worktree case, not an "already merged" scenario.
+                const alreadyMergedViaOtherPath = !patchEquivalence.actualPatchId && !!patchEquivalence.expectedPatchId;
+                if (!didAutoRebase && !alreadyMergedViaOtherPath) {
+                    return {
+                        success: false,
+                        code: 'patch_equivalence_failed',
+                        convergenceStatus: 'blocked_review',
+                        error: 'Refinery patch-equivalence preflight failed; merge/refine was not attempted.',
+                        branch,
+                        into: baseBranch,
+                        validationSummary,
+                        patchEquivalence,
+                        refineStages,
+                        finalBranchConvergenceState: {
+                            branch,
+                            baseBranch,
+                            merged: false,
+                            removed: false,
+                            validation: 'passed',
+                            patchEquivalence: 'failed',
+                            status: 'blocked_review',
+                        },
+                    };
+                }
+
+                if (!didAutoRebase && alreadyMergedViaOtherPath) {
+                    // Content already in base — skip merge, go straight to cleanup.
+                    recordMeshRefineStage(refineStages, 'merge', 'skipped', Date.now(), {
+                        reason: 'already_merged_via_other_path',
+                        note: 'actualPatchId is empty; branch content is already present in base via a different commit path',
+                    });
+                    const cleanupStarted = Date.now();
+                    const removeResult = await this.execute('remove_mesh_node', {
+                        meshId,
+                        nodeId,
+                        sessionCleanupMode: 'preserve',
+                        inlineMesh: args?.inlineMesh,
+                    });
+                    recordMeshRefineStage(refineStages, 'cleanup', removeResult?.success === false ? 'failed' : 'passed', cleanupStarted, {
+                        removed: removeResult?.removed,
+                        code: removeResult?.code,
+                        error: removeResult?.error,
+                    });
+                    try {
+                        const { appendLedgerEntry } = await import('../mesh/mesh-ledger.js');
+                        appendLedgerEntry(meshId, {
+                            kind: 'node_removed',
+                            nodeId,
+                            payload: { alreadyMergedViaOtherPath: true, branch, into: baseBranch, validationSummary, patchEquivalence },
+                        });
+                    } catch { /* ledger append is best-effort */ }
+                    return {
+                        success: removeResult?.success !== false,
+                        code: 'already_merged',
+                        merged: false,
+                        alreadyMergedViaOtherPath: true,
+                        branch,
+                        into: baseBranch,
+                        removeResult,
+                        validationSummary,
+                        patchEquivalence,
+                        refineStages,
+                        finalBranchConvergenceState: {
+                            branch: baseBranch,
+                            mergedBranch: branch,
+                            baseBranch,
+                            merged: false,
+                            alreadyMergedViaOtherPath: true,
+                            removed: removeResult?.success !== false,
+                            validation: 'passed',
+                            patchEquivalence: 'already_merged',
+                            status: removeResult?.success === false ? 'merged_cleanup_failed' : 'merged_to_main',
+                        },
+                    };
+                }
             }
 
             const submoduleReachabilityStarted = Date.now();
@@ -3620,23 +3908,61 @@ export class DaemonCommandRouter {
             result = { success: false, error: e?.message || String(e) };
         }
         const completedAt = new Date().toISOString();
+
+        // B1: Discriminated terminal status — do not rely solely on result.success.
+        // Map known failure codes to structured terminal kinds.
+        type RefineTerminalKind = 'completed' | 'blocked_review' | 'validation_failed' | 'submodule_reachability_failed' | 'merge_failed' | 'cleanup_failed';
+        const refineCode = typeof result.code === 'string' ? result.code : '';
+        const refineTerminalKind: RefineTerminalKind = result.success === true
+            ? 'completed'
+            : refineCode === 'blocked_review'
+                ? 'blocked_review'
+                : refineCode === 'validation_failed' || refineCode === 'validation_dependencies_missing'
+                    ? 'validation_failed'
+                    : refineCode === 'submodule_reachability_failed'
+                        ? 'submodule_reachability_failed'
+                        : refineCode === 'merge_failed' || refineCode === 'patch_equivalence_failed' || refineCode === 'needs_rebase' || refineCode === 'needs_rebase_with_conflicts'
+                            ? 'merge_failed'
+                            : refineCode === 'cleanup_failed'
+                                ? 'cleanup_failed'
+                                : 'merge_failed'; // fallback for unclassified failures
+        const isTerminalSuccess = refineTerminalKind === 'completed';
+        const normalizedResult = {
+            ...result,
+            terminalKind: refineTerminalKind,
+            ...(result.nextStep === undefined && !isTerminalSuccess ? {
+                nextStep: refineTerminalKind === 'blocked_review'
+                    ? 'Request user review/approval before attempting to merge again.'
+                    : refineTerminalKind === 'validation_failed'
+                        ? 'Fix failing tests or configure validation.bootstrapCommands and retry mesh_refine_node.'
+                        : refineTerminalKind === 'submodule_reachability_failed'
+                            ? 'Push unreachable submodule commits to origin/main, then retry mesh_refine_node.'
+                            : refineTerminalKind === 'merge_failed'
+                                ? 'Resolve merge conflicts or patch equivalence issues, then retry mesh_refine_node.'
+                                : refineTerminalKind === 'cleanup_failed'
+                                    ? 'Manually remove the worktree and retry or use mesh_remove_node.'
+                                    : 'Inspect refineStages for the failing stage and retry.',
+            } : {}),
+        };
+
         const terminalHandle = this.buildRefineJobHandle({
             meshId: handle.meshId,
             nodeId: handle.targetNodeId,
-            status: result.success === true ? 'completed' : 'failed',
+            status: isTerminalSuccess ? 'completed' : 'failed',
             startedAt: handle.startedAt,
             completedAt,
             jobId: handle.jobId,
             interactionId: handle.interactionId,
             retryOfJobId: handle.retryOfJobId,
             node: { daemonId: handle.targetDaemonId, workspace: handle.workspace },
+            coordinatorDaemonId: handle.targetCoordinatorDaemonId,
         });
-        const terminal: MeshRefineTerminalJob = { ...terminalHandle, result };
+        const terminal: MeshRefineTerminalJob = { ...terminalHandle, result: normalizedResult };
         this.terminalRefineJobs.set(key, terminal);
         this.runningRefineJobs.delete(key);
         this.invalidateAggregateMeshStatus(handle.meshId);
-        await this.appendRefineJobLedger(result.success === true ? 'task_completed' : 'task_failed', terminalHandle, result);
-        this.queueRefineJobEvent(result.success === true ? 'refine:completed' : 'refine:failed', terminalHandle, result);
+        await this.appendRefineJobLedger(isTerminalSuccess ? 'task_completed' : 'task_failed', terminalHandle, normalizedResult);
+        this.queueRefineJobEvent(isTerminalSuccess ? 'refine:completed' : 'refine:failed', terminalHandle, normalizedResult);
     }
 
     private async startMeshRefineJob(meshId: string, nodeId: string, args: any): Promise<CommandRouterResult> {
@@ -3651,7 +3977,12 @@ export class DaemonCommandRouter {
         if (!node) return { success: false, error: `Node '${nodeId}' not found in mesh` };
         if (!node.isLocalWorktree || !node.workspace) return { success: false, error: `Refinery requires a local worktree node` };
 
-        const handle = this.buildRefineJobHandle({ meshId, nodeId, node, retryOfJobId: terminal?.jobId });
+        // Capture the caller's coordinator daemon ID so completed/failed events are
+        // scoped to that coordinator's pending-events queue and survive daemon restarts.
+        const coordinatorDaemonId = typeof args?.coordinatorDaemonId === 'string' && args.coordinatorDaemonId.trim()
+            ? args.coordinatorDaemonId.trim()
+            : (this.deps.statusInstanceId || undefined);
+        const handle = this.buildRefineJobHandle({ meshId, nodeId, node, retryOfJobId: terminal?.jobId, coordinatorDaemonId });
         this.runningRefineJobs.set(key, handle);
         await this.appendRefineJobLedger('task_dispatched', handle);
         this.queueRefineJobEvent('refine:accepted', handle);
@@ -4815,11 +5146,17 @@ export class DaemonCommandRouter {
                 const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
                 if (!meshId) return { success: false, error: 'meshId required' };
                 try {
-                    const { getMeshQueueStats, getQueue } = await import('../mesh/mesh-work-queue.js');
+                    const { getMeshQueueStats, getQueue, describeTaskDependencyState } = await import('../mesh/mesh-work-queue.js');
                     const status = Array.isArray(args?.status)
                         ? args.status.map((s: any) => typeof s === 'string' ? s.trim() : '').filter(Boolean)
                         : undefined;
-                    const queue = getQueue(meshId, { status: status as any });
+                    const rawQueue = getQueue(meshId, { status: status as any });
+                    // M1: annotate dependency state at view time (waitingOn / dependenciesSatisfied).
+                    const statusById = new Map(getQueue(meshId).map(task => [task.id, task.status]));
+                    const queue = rawQueue.map(task =>
+                        Array.isArray(task.dependsOn) && task.dependsOn.length > 0
+                            ? { ...task, ...describeTaskDependencyState(task, statusById) }
+                            : task);
                     const summary = getMeshQueueStats(meshId);
                     return {
                         success: true,
@@ -5105,7 +5442,7 @@ export class DaemonCommandRouter {
 
                     let worktreeCleanup: Record<string, unknown> | undefined;
                     if (node?.isLocalWorktree) {
-                        const cleanupResult = await this.cleanupLocalWorktreeNode({ mesh, node, nodeId });
+                        const cleanupResult = await this.cleanupLocalWorktreeNode({ mesh, node, nodeId, force: args?.force === true });
                         if (cleanupResult.success === false) {
                             return {
                                 success: false,
@@ -5281,6 +5618,40 @@ export class DaemonCommandRouter {
                                     { timeoutMs: 120000 },
                                 );
                                 submodulesInitialized = true;
+
+                                // Sync oss submodule to source node HEAD (best-effort)
+                                const sourceWorkspace = sourceNode.repoRoot || sourceNode.workspace;
+                                if (sourceWorkspace) {
+                                    try {
+                                        const { runGit: rg } = await import('../git/git-executor.js');
+                                        const sourceCtx = { workspace: sourceWorkspace, repoRoot: sourceWorkspace, isGitRepo: true };
+                                        const worktreeCtx = { workspace: result.worktreePath, repoRoot: result.worktreePath, isGitRepo: true };
+
+                                        // Read source node's oss submodule SHA
+                                        const sourceStatusOut = await rg(sourceCtx, ['submodule', 'status', 'oss'], { timeoutMs: 10000 });
+                                        const sourceStatusLine = (typeof sourceStatusOut === 'string' ? sourceStatusOut : (sourceStatusOut as any)?.stdout ?? '').trim();
+                                        const sourceShaMatch = sourceStatusLine.match(/^[+\- ]?([0-9a-f]{40})/);
+                                        const sourceSha = sourceShaMatch?.[1];
+
+                                        if (sourceSha) {
+                                            // Read worktree's current oss HEAD
+                                            const ossCtx = { workspace: `${result.worktreePath}/oss`, repoRoot: `${result.worktreePath}/oss`, isGitRepo: true };
+                                            const worktreeOssHeadOut = await rg(ossCtx, ['rev-parse', 'HEAD'], { timeoutMs: 10000 });
+                                            const worktreeOssSha = (typeof worktreeOssHeadOut === 'string' ? worktreeOssHeadOut : (worktreeOssHeadOut as any)?.stdout ?? '').trim();
+
+                                            if (worktreeOssSha !== sourceSha) {
+                                                // Fetch target SHA from source node's oss directory
+                                                await rg(ossCtx, ['fetch', `${sourceWorkspace}/oss`, 'HEAD'], { timeoutMs: 60000 });
+                                                await rg(ossCtx, ['checkout', sourceSha], { timeoutMs: 10000 });
+                                                await rg(worktreeCtx, ['add', 'oss'], { timeoutMs: 10000 });
+                                                await rg(worktreeCtx, ['commit', '-m', 'chore: sync oss to source node HEAD on clone'], { timeoutMs: 10000 });
+                                                console.log(`[mesh] Synced oss submodule to source HEAD ${sourceSha.slice(0, 8)} in worktree`);
+                                            }
+                                        }
+                                    } catch (ossErr: any) {
+                                        console.warn('[mesh] oss submodule sync to source HEAD failed (best-effort):', ossErr.message);
+                                    }
+                                }
                             } catch (subErr: any) {
                                 // Submodule init is best-effort; don't fail the clone
                                 console.warn('[mesh] Submodule init failed for worktree:', subErr.message);
@@ -5342,6 +5713,63 @@ export class DaemonCommandRouter {
                     return { success: false, error: e.message };
                 }
             }
+            case 'retry_mesh_node_bootstrap': {
+                const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
+                const nodeId = typeof args?.nodeId === 'string' ? args.nodeId.trim() : '';
+                if (!meshId) return { success: false, error: 'meshId required' };
+                if (!nodeId) return { success: false, error: 'nodeId required' };
+                const ownerFailure = await this.requireMeshHostMutationOwner(meshId, args?.inlineMesh, 'bootstrap retry');
+                if (ownerFailure) return ownerFailure;
+
+                try {
+                    const meshRecord = await this.getMeshForCommand(meshId, args?.inlineMesh);
+                    const mesh = meshRecord?.mesh;
+                    if (!mesh) return { success: false, error: 'Mesh not found' };
+
+                    const node = mesh.nodes?.find((n: any) => n.id === nodeId || n.nodeId === nodeId);
+                    if (!node) return { success: false, error: `Node '${nodeId}' not found in mesh` };
+                    if (!node.isLocalWorktree) return { success: false, error: 'Node is not a local worktree node' };
+
+                    const currentBootstrap = node.worktreeBootstrap as WorktreeBootstrapState | undefined;
+                    if (currentBootstrap?.status === 'running') {
+                        return { success: false, error: 'Bootstrap is already running for this node' };
+                    }
+
+                    const worktreePath: string = node.workspace || node.repoRoot;
+                    if (!worktreePath) return { success: false, error: 'Node has no workspace path' };
+
+                    const loadedBootstrap = loadMeshWorktreeBootstrapConfig(mesh, worktreePath);
+                    const runningState: WorktreeBootstrapState = {
+                        status: 'running',
+                        required: loadedBootstrap.config?.required !== false,
+                        configSource: loadedBootstrap.path || loadedBootstrap.source,
+                        configSourceType: loadedBootstrap.sourceType,
+                        startedAt: new Date().toISOString(),
+                    };
+
+                    const persistState = async (bootstrapState: WorktreeBootstrapState): Promise<void> => {
+                        node.worktreeBootstrap = bootstrapState;
+                        if (meshRecord.inline) {
+                            this.updateInlineMeshNode(meshId, mesh, node);
+                            return;
+                        }
+                        try {
+                            const { updateNode } = await import('../config/mesh-config.js');
+                            updateNode(meshId, node.id, { worktreeBootstrap: bootstrapState });
+                            this.invalidateAggregateMeshStatus(meshId);
+                        } catch { /* best-effort */ }
+                    };
+
+                    await persistState(runningState);
+                    const bootstrapState = await runMeshWorktreeBootstrap(mesh, worktreePath);
+                    await persistState(bootstrapState);
+
+                    return { success: true, bootstrapState };
+                } catch (e: any) {
+                    return { success: false, error: e.message };
+                }
+            }
+
             case 'trigger_mesh_queue': {
                 const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
                 if (!meshId) return { success: false, error: 'meshId required' };
@@ -5377,6 +5805,12 @@ export class DaemonCommandRouter {
 
                 try {
                     const { buildCoordinatorSystemPrompt } = await import('../mesh/coordinator-prompt.js');
+                    const { buildMissionPromptSection } = await import('../mesh/mesh-missions.js');
+                    // M3-3: inject the active mission summary into the coordinator prompt.
+                    // Best-effort — a store failure must not block coordinator launch.
+                    const buildMissionSectionBestEffort = (id: string): string => {
+                        try { return buildMissionPromptSection(id); } catch { return ''; }
+                    };
 
                     // Support inline mesh data from cloud (bypasses local meshes.json lookup)
                     let mesh: any;
@@ -5483,7 +5917,7 @@ export class DaemonCommandRouter {
                         // Build coordinator prompt first — fail closed on errors.
                         let cliCmdSystemPrompt = '';
                         try {
-                            cliCmdSystemPrompt = buildCoordinatorSystemPrompt({ mesh, coordinatorCliType: cliType, userInstruction: extraSystemPrompt || undefined });
+                            cliCmdSystemPrompt = buildCoordinatorSystemPrompt({ mesh, coordinatorCliType: cliType, userInstruction: extraSystemPrompt || undefined, missionSection: buildMissionSectionBestEffort(mesh.id) });
                         } catch (error: any) {
                             const message = error?.message || String(error);
                             LOG.error('MeshCoordinator', `Failed to build coordinator prompt: ${message}`);
@@ -5701,7 +6135,7 @@ export class DaemonCommandRouter {
                     // broken mesh state is visible instead of silently launching with weaker rules.
                     let systemPrompt = '';
                     try {
-                        systemPrompt = buildCoordinatorSystemPrompt({ mesh, coordinatorCliType: cliType, userInstruction: extraSystemPrompt || undefined });
+                        systemPrompt = buildCoordinatorSystemPrompt({ mesh, coordinatorCliType: cliType, userInstruction: extraSystemPrompt || undefined, missionSection: buildMissionSectionBestEffort(mesh.id) });
                     } catch (error: any) {
                         const message = error?.message || String(error);
                         LOG.error('MeshCoordinator', `Failed to build coordinator prompt: ${message}`);
@@ -6346,6 +6780,16 @@ export class DaemonCommandRouter {
                         ...(asyncRefineJobs.length > 0 ? { asyncRefineJobs } : {}),
                         ...(historicalSessions ? { historicalSessions } : {}),
                         ...(pendingCoordinatorEvents.length > 0 ? { pendingCoordinatorEvents } : {}),
+                        activeRefineJobs: Array.from(this.runningRefineJobs.values())
+                            .filter(job => job.meshId === meshId)
+                            .map(job => ({
+                                jobId: job.jobId,
+                                nodeId: job.targetNodeId,
+                                workspace: job.workspace,
+                                startedAt: job.startedAt,
+                                status: job.status,
+                                targetCoordinatorDaemonId: job.targetCoordinatorDaemonId,
+                            })),
                     };
                     const { pendingCoordinatorEvents: _pendingCoordinatorEvents, ...cacheableStatusResult } = statusResult as any;
                     const rememberedStatus = this.rememberAggregateMeshStatus(meshId, cacheableStatusResult, refreshReason);
@@ -6367,6 +6811,90 @@ export class DaemonCommandRouter {
                 }
             }
 
+            case 'get_mesh_review_inbox': {
+                const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
+                if (!meshId) return { success: false, error: 'meshId required' };
+                try {
+                    const { deriveMeshReviewInboxItems } = await import('../mesh/mesh-review-inbox.js');
+                    const { readLedgerEntries } = await import('../mesh/mesh-ledger.js');
+                    const { getGitDiffSummary } = await import('../git/git-diff.js');
+                    const { existsSync } = await import('node:fs');
+
+                    const meshRecord = await this.getMeshForCommand(meshId, args?.inlineMesh, { preferInline: true });
+                    const mesh = meshRecord?.mesh;
+                    if (!mesh) return { success: false, error: 'Mesh not found' };
+
+                    // Ensure we have a fresh aggregate status so nodeStatuses carry
+                    // computed fields (connection.state, branchConvergence, isLocalWorktree)
+                    // that the raw mesh.nodes config objects don't have.
+                    // When the caller provides an inlineMesh, prefer its nodes directly
+                    // (they already carry the computed fields from the coordinator).
+                    const inlineNodes = args?.inlineMesh && Array.isArray((args.inlineMesh as any)?.nodes)
+                        ? (args.inlineMesh as any).nodes as Record<string, unknown>[]
+                        : null;
+                    let cachedStatus = !inlineNodes ? this.getCachedAggregateMeshStatus(meshId, mesh, {}) : null;
+                    if (!cachedStatus && !inlineNodes) {
+                        const freshStatus = await this.execute('mesh_status', {
+                            meshId,
+                            inlineMesh: args?.inlineMesh,
+                            refresh: true,
+                        }, 'get_mesh_review_inbox');
+                        cachedStatus = (freshStatus?.success !== false) ? freshStatus : null;
+                    }
+                    const nodeStatuses: Record<string, unknown>[] = inlineNodes
+                        ? inlineNodes
+                        : Array.isArray(cachedStatus?.nodes)
+                            ? cachedStatus.nodes as Record<string, unknown>[]
+                            : Array.isArray(mesh.nodes)
+                                ? mesh.nodes as Record<string, unknown>[]
+                                : [];
+
+                    const ledgerEntries = readLedgerEntries(meshId, { tail: 300 });
+                    const derivation = deriveMeshReviewInboxItems({ nodes: nodeStatuses, ledgerEntries });
+
+                    for (const item of derivation.items) {
+                        const workspace = item.workspace;
+                        if (!workspace || !existsSync(workspace)) continue;
+                        const baseRef = item.defaultBranch
+                            ? `origin/${item.defaultBranch}`
+                            : 'origin/main';
+                        try {
+                            const diffResult = await getGitDiffSummary(workspace, { baseRef, maxFiles: 100 });
+                            if (diffResult.isGitRepo) {
+                                item.diffSummary = {
+                                    baseRef,
+                                    files: diffResult.files.map(f => ({
+                                        path: f.path,
+                                        status: f.status,
+                                        insertions: f.insertions,
+                                        deletions: f.deletions,
+                                        binary: f.binary,
+                                        oldPath: f.oldPath,
+                                    })),
+                                    totalFiles: diffResult.files.length,
+                                    totalInsertions: diffResult.totalInsertions,
+                                    totalDeletions: diffResult.totalDeletions,
+                                    truncated: diffResult.truncated,
+                                    ...(diffResult.error ? { error: diffResult.error } : {}),
+                                };
+                            }
+                        } catch {
+                            item.diffSummary = null;
+                        }
+                    }
+
+                    return {
+                        success: true,
+                        meshId,
+                        inbox: derivation.items,
+                        remoteNodesExcluded: derivation.remoteNodesExcluded,
+                        excludedRemoteNodeIds: derivation.excludedRemoteNodeIds,
+                    };
+                } catch (e: any) {
+                    return { success: false, error: e.message };
+                }
+            }
+
             default:
                 break;
         }