@adhdev/daemon-core 0.9.77-rc.44 → 0.9.77-rc.45

package/dist/mesh/mesh-events.d.ts

@@ -13,7 +13,7 @@ export declare function tryAssignQueueTask(components: DaemonComponents, meshId:
  * Triggers a queue check for all nodes in the mesh.
  * Called when a new task is enqueued, in case nodes are already idle.
  */
-export declare function triggerMeshQueue(components: DaemonComponents, meshId: string): void;
+export declare function triggerMeshQueue(components: DaemonComponents, meshId: string): Promise<void>;
 export declare function handleMeshForwardEvent(components: DaemonComponents, payload: Record<string, unknown>): {
     success: boolean;
     forwarded: number;

package/dist/mesh/mesh-ledger.d.ts

@@ -13,7 +13,7 @@
  * Safety:  mode 0o600, atomic append via appendFileSync
  */
 import { EventEmitter } from 'events';
-export type MeshLedgerKind = 'task_dispatched' | 'task_completed' | 'task_failed' | 'task_stalled' | 'task_approval_needed' | 'session_launched' | 'session_stopped' | 'checkpoint_created' | 'node_cloned' | 'node_removed' | 'coordinator_started' | 'recovery_attempted';
+export type MeshLedgerKind = 'task_dispatched' | 'task_completed' | 'task_failed' | 'task_stalled' | 'task_approval_needed' | 'session_launched' | 'session_auto_launch' | 'session_stopped' | 'checkpoint_created' | 'node_cloned' | 'node_removed' | 'coordinator_started' | 'recovery_attempted';
 export interface MeshLedgerEntry {
     id: string;
     meshId: string;

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

@@ -19,6 +19,15 @@ export interface MeshWorkQueueEntry {
     requeueReason?: string;
     requeuedAt?: string;
     requeueCount?: number;
+    /** Last automatic queue session spin-up attempt, for mesh_view_queue/debug visibility. */
+    autoLaunch?: {
+        status: 'skipped' | 'started' | 'failed' | 'completed';
+        reason?: string;
+        nodeId?: string;
+        providerType?: string;
+        sessionId?: string;
+        updatedAt: string;
+    };
     createdAt: string;
     updatedAt: string;
 }
@@ -44,6 +53,7 @@ export declare function claimNextTask(meshId: string, nodeId: string, sessionId:
  * Used when a session completes, fails, or stalls.
  */
 export declare function updateTaskStatus(meshId: string, taskId: string, status: MeshTaskStatus): MeshWorkQueueEntry | null;
+export declare function recordTaskAutoLaunch(meshId: string, taskId: string, autoLaunch: Omit<NonNullable<MeshWorkQueueEntry['autoLaunch']>, 'updatedAt'>): MeshWorkQueueEntry | null;
 /**
  * Mark a queue task as manually cancelled without deleting audit history.
  */

package/dist/mesh/p2p-relay-failure.d.ts

@@ -0,0 +1,35 @@
+export type P2pRelayFailureCode = 'p2p_unavailable' | 'p2p_timeout' | 'p2p_not_connected' | 'p2p_datachannel_closed' | 'p2p_no_route' | 'p2p_daemon_offline' | 'mesh_logic_or_provider_failure';
+export interface P2pRelayFailureContext {
+    command?: string;
+    targetDaemonId?: string;
+}
+export interface P2pRelayFailureClassification {
+    code: P2pRelayFailureCode;
+    reason: string;
+    transport: 'p2p' | 'unknown';
+    recoverable: boolean;
+    retryRecommended: boolean;
+    nextAction: string;
+    noFallbackReason: string;
+}
+export interface P2pRelayFailurePayload extends P2pRelayFailureClassification {
+    success: false;
+    error: string;
+    command?: string;
+    targetDaemonId?: string;
+}
+export declare function classifyP2pRelayFailure(error: unknown, _context?: P2pRelayFailureContext): P2pRelayFailureClassification;
+export declare function isP2pRelayTransportFailure(error: unknown): boolean;
+export declare function buildP2pRelayFailurePayload(error: unknown, context?: P2pRelayFailureContext): P2pRelayFailurePayload;
+export declare class P2pRelayFailureError extends Error {
+    code: P2pRelayFailureCode;
+    reason: string;
+    transport: 'p2p' | 'unknown';
+    recoverable: boolean;
+    retryRecommended: boolean;
+    nextAction: string;
+    noFallbackReason: string;
+    command?: string;
+    targetDaemonId?: string;
+    constructor(message: string, context?: P2pRelayFailureContext);
+}

package/package.json

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

package/src/commands/router.ts

@@ -43,6 +43,7 @@ import { execNpmCommandSync, resolveCurrentGlobalInstallSurface, spawnDetachedDa
 import type { RepoMeshSessionCleanupMode } from '../repo-mesh-types.js';
 import { homedir } from 'os';
 import { join as pathJoin, resolve as pathResolve } from 'path';
+import * as fs from 'fs';
 
 type ReleaseChannel = 'stable' | 'preview';
 const CHANNEL_NPM_TAG: Record<ReleaseChannel, 'latest' | 'next'> = { stable: 'latest', preview: 'next' };
@@ -114,9 +115,271 @@ async function resolveProviderTypeFromPriority(args: {
 
     return { error: `No usable provider detected for node '${args.nodeId}' from providerPriority: ${failed.join('; ')}` };
 }
-import * as fs from 'fs';
-
 type MeshCoordinatorConfigFormat = 'claude_mcp_json' | 'hermes_config_yaml';
+type MeshRefineValidationStatus = 'passed' | 'failed' | 'skipped';
+type MeshRefineValidationCommand = {
+    command: string;
+    args: string[];
+    displayCommand: string;
+    category: string;
+    source: string;
+};
+
+type MeshRefineValidationSummary = {
+    status: MeshRefineValidationStatus;
+    required: true;
+    commandsRun: Array<Record<string, unknown>>;
+    rejectedCommands: Array<Record<string, unknown>>;
+    skippedReason?: string;
+    timeoutMs: number;
+    outputLimitBytes: number;
+};
+
+const REFINE_VALIDATION_CATEGORIES = ['typecheck', 'test', 'lint', 'build'] as const;
+const REFINE_VALIDATION_TIMEOUT_MS = 120_000;
+const REFINE_VALIDATION_OUTPUT_LIMIT_BYTES = 128 * 1024;
+const REFINE_VALIDATION_SUMMARY_CHARS = 2_000;
+const REFINE_VALIDATION_MAX_COMMANDS = 4;
+
+function truncateValidationOutput(value: unknown): string {
+    const text = typeof value === 'string' ? value : value == null ? '' : String(value);
+    if (text.length <= REFINE_VALIDATION_SUMMARY_CHARS) return text;
+    return `${text.slice(0, REFINE_VALIDATION_SUMMARY_CHARS)}\n[truncated ${text.length - REFINE_VALIDATION_SUMMARY_CHARS} chars]`;
+}
+
+function readPackageScripts(workspace: string): Record<string, string> {
+    try {
+        const packageJsonPath = pathJoin(workspace, 'package.json');
+        const parsed = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+        return parsed?.scripts && typeof parsed.scripts === 'object' && !Array.isArray(parsed.scripts)
+            ? parsed.scripts as Record<string, string>
+            : {};
+    } catch {
+        return {};
+    }
+}
+
+function tokenizeValidationCommand(command: string): string[] | null {
+    const trimmed = command.trim();
+    if (!trimmed) return null;
+    // Fail closed: the gate never hands shell syntax to a shell. Package-manager
+    // scripts are invoked via execFile(binary, args), and metacharacters/quotes are
+    // rejected before tokenization so `npm run test && rm -rf` cannot be smuggled in.
+    if (/[;&|<>`$\\\n\r'\"]/.test(trimmed)) return null;
+    const tokens = trimmed.split(/\s+/).filter(Boolean);
+    if (!tokens.length) return null;
+    if (tokens.some(token => !/^[A-Za-z0-9_@./:=+-]+$/.test(token))) return null;
+    return tokens;
+}
+
+function scriptMatchesValidationCategory(scriptName: string, category: string): boolean {
+    return scriptName === category || scriptName.startsWith(`${category}:`);
+}
+
+function parsePackageManagerValidationCommand(
+    rawCommand: string,
+    category: string,
+    scripts: Record<string, string>,
+    source: string,
+): { command?: MeshRefineValidationCommand; rejected?: Record<string, unknown> } {
+    const tokens = tokenizeValidationCommand(rawCommand);
+    if (!tokens) {
+        return { rejected: { command: rawCommand, category, source, reason: 'unsafe command string is not allowlisted' } };
+    }
+
+    const [binary, second, third, ...rest] = tokens;
+    let scriptName = '';
+    let command = binary;
+    let args: string[] = [];
+
+    if ((binary === 'npm' || binary === 'pnpm' || binary === 'bun') && second === 'run' && third) {
+        scriptName = third;
+        args = ['run', scriptName, ...rest];
+    } else if (binary === 'npm' && second === 'test' && !third) {
+        scriptName = 'test';
+        args = ['test'];
+    } else if (binary === 'yarn' && second === 'run' && third) {
+        scriptName = third;
+        args = ['run', scriptName, ...rest];
+    } else if (binary === 'yarn' && second && !third) {
+        scriptName = second;
+        args = [scriptName];
+    } else {
+        return { rejected: { command: rawCommand, category, source, reason: 'command is not a supported package-manager script invocation' } };
+    }
+
+    if (!scriptName || !Object.prototype.hasOwnProperty.call(scripts, scriptName)) {
+        return { rejected: { command: rawCommand, category, source, script: scriptName, reason: 'script is not declared in package.json' } };
+    }
+    if (!scriptMatchesValidationCategory(scriptName, category)) {
+        return { rejected: { command: rawCommand, category, source, script: scriptName, reason: 'script name is outside the validation category allowlist' } };
+    }
+
+    return {
+        command: {
+            command,
+            args,
+            displayCommand: [command, ...args].join(' '),
+            category,
+            source,
+        },
+    };
+}
+
+function collectProjectContextValidationCandidates(mesh: any): Array<{ command: string; category: string; source: string; confidence?: string }> {
+    const commands = mesh?.projectContext?.commands;
+    if (!commands || typeof commands !== 'object' || Array.isArray(commands)) return [];
+    const candidates: Array<{ command: string; category: string; source: string; confidence?: string }> = [];
+    for (const category of REFINE_VALIDATION_CATEGORIES) {
+        const entries = Array.isArray(commands[category]) ? commands[category] : [];
+        for (const entry of entries) {
+            if (typeof entry?.command !== 'string') continue;
+            candidates.push({
+                command: entry.command,
+                category,
+                source: typeof entry.sourcePath === 'string' ? entry.sourcePath : 'projectContext.commands',
+                confidence: typeof entry.confidence === 'string' ? entry.confidence : undefined,
+            });
+        }
+    }
+    return candidates.sort((a, b) => {
+        const rank = (value?: string) => value === 'high' ? 0 : value === 'medium' ? 1 : 2;
+        return rank(a.confidence) - rank(b.confidence);
+    });
+}
+
+function collectPolicyValidationCandidates(mesh: any): Array<{ command: string; category: string; source: string }> {
+    const policy = mesh?.policy && typeof mesh.policy === 'object' && !Array.isArray(mesh.policy) ? mesh.policy : {};
+    const configured = Array.isArray(policy.validationCommands)
+        ? policy.validationCommands
+        : Array.isArray(policy.validationGate?.commands)
+            ? policy.validationGate.commands
+            : [];
+    return configured
+        .map((entry: any) => typeof entry === 'string' ? { command: entry, category: '', source: 'mesh.policy.validationCommands' } : entry)
+        .filter((entry: any) => entry && typeof entry.command === 'string')
+        .map((entry: any) => {
+            const commandText = entry.command.trim();
+            const category = REFINE_VALIDATION_CATEGORIES.find(cat => commandText.includes(` ${cat}`)) ?? '';
+            return { command: commandText, category, source: 'mesh.policy.validationCommands' };
+        })
+        .filter((entry: any) => !!entry.category);
+}
+
+function selectMeshRefineValidationCommands(mesh: any, workspace: string): { commands: MeshRefineValidationCommand[]; rejectedCommands: Array<Record<string, unknown>>; source: string } {
+    const scripts = readPackageScripts(workspace);
+    const rejectedCommands: Array<Record<string, unknown>> = [];
+    const selected: MeshRefineValidationCommand[] = [];
+    const seen = new Set<string>();
+    const candidates = [
+        ...collectPolicyValidationCandidates(mesh),
+        ...collectProjectContextValidationCandidates(mesh),
+    ];
+
+    for (const candidate of candidates) {
+        const parsed = parsePackageManagerValidationCommand(candidate.command, candidate.category, scripts, candidate.source);
+        if (parsed.rejected) {
+            rejectedCommands.push(parsed.rejected);
+            continue;
+        }
+        if (!parsed.command || seen.has(parsed.command.displayCommand)) continue;
+        selected.push(parsed.command);
+        seen.add(parsed.command.displayCommand);
+        if (selected.length >= REFINE_VALIDATION_MAX_COMMANDS) break;
+    }
+
+    if (!selected.length && candidates.length === 0) {
+        for (const category of REFINE_VALIDATION_CATEGORIES) {
+            if (!Object.prototype.hasOwnProperty.call(scripts, category)) continue;
+            const fallback = parsePackageManagerValidationCommand(`npm run ${category}`, category, scripts, 'package.json:scripts');
+            if (fallback.command && !seen.has(fallback.command.displayCommand)) {
+                selected.push(fallback.command);
+                seen.add(fallback.command.displayCommand);
+            } else if (fallback.rejected) {
+                rejectedCommands.push(fallback.rejected);
+            }
+            if (selected.length >= 2) break;
+        }
+    }
+
+    return {
+        commands: selected,
+        rejectedCommands,
+        source: selected.some(command => command.source === 'mesh.policy.validationCommands')
+            ? 'mesh_policy'
+            : selected.some(command => command.source !== 'package.json:scripts')
+                ? 'project_context'
+                : selected.length
+                    ? 'package_json_scripts'
+                    : 'unavailable',
+    };
+}
+
+async function runMeshRefineValidationGate(mesh: any, workspace: string): Promise<MeshRefineValidationSummary> {
+    const { execFile } = await import('node:child_process');
+    const { promisify } = await import('node:util');
+    const execFileAsync = promisify(execFile);
+    const selection = selectMeshRefineValidationCommands(mesh, workspace);
+    const summary: MeshRefineValidationSummary = {
+        status: 'skipped',
+        required: true,
+        commandsRun: [],
+        rejectedCommands: selection.rejectedCommands,
+        skippedReason: undefined,
+        timeoutMs: REFINE_VALIDATION_TIMEOUT_MS,
+        outputLimitBytes: REFINE_VALIDATION_OUTPUT_LIMIT_BYTES,
+    };
+
+    if (!selection.commands.length) {
+        summary.skippedReason = 'validation_unavailable: no allowlisted projectContext, mesh policy, or package.json build/test/typecheck/lint command was available';
+        return summary;
+    }
+
+    for (const candidate of selection.commands) {
+        const startedAt = Date.now();
+        try {
+            const result = await execFileAsync(candidate.command, candidate.args, {
+                cwd: workspace,
+                encoding: 'utf8',
+                timeout: REFINE_VALIDATION_TIMEOUT_MS,
+                maxBuffer: REFINE_VALIDATION_OUTPUT_LIMIT_BYTES,
+                env: { ...process.env, CI: process.env.CI || '1' },
+            });
+            summary.commandsRun.push({
+                command: candidate.command,
+                args: candidate.args,
+                displayCommand: candidate.displayCommand,
+                category: candidate.category,
+                source: candidate.source,
+                passed: true,
+                exitCode: 0,
+                durationMs: Date.now() - startedAt,
+                stdout: truncateValidationOutput(result.stdout),
+                stderr: truncateValidationOutput(result.stderr),
+            });
+        } catch (error: any) {
+            summary.commandsRun.push({
+                command: candidate.command,
+                args: candidate.args,
+                displayCommand: candidate.displayCommand,
+                category: candidate.category,
+                source: candidate.source,
+                passed: 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 || '')),
+                durationMs: Date.now() - startedAt,
+                stdout: truncateValidationOutput(error?.stdout),
+                stderr: truncateValidationOutput(error?.stderr || error?.message),
+            });
+            summary.status = 'failed';
+            return summary;
+        }
+    }
+
+    summary.status = 'passed';
+    return summary;
+}
 
 function loadYamlModule(): { load: (input: string) => any; dump: (input: any, options?: Record<string, any>) => string } {
     return yaml as { load: (input: string) => any; dump: (input: any, options?: Record<string, any>) => string };
@@ -421,7 +684,7 @@ export class DaemonCommandRouter {
         mesh: any;
         node: any;
         nodeId: string;
-    }): Promise<{ success: true; skipped?: boolean; removedPath?: string; repoRoot?: string; reason?: string } | { success: false; code: string; error: string; recoveryHint: string }> {
+    }): 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) {
             return {
@@ -497,23 +760,124 @@ export class DaemonCommandRouter {
             };
         }
 
+        const forceFallbackConvergence = await this.getWorktreeForceCleanupConvergence({
+            repoRoot,
+            workspace,
+            node: args.node,
+        });
+
         try {
-            const result = await removeWorktree(repoRoot, workspace, { requireClean: true });
-            return { success: true, removedPath: result.removedPath, repoRoot };
+            const result = await removeWorktree(repoRoot, workspace, {
+                requireClean: true,
+                allowSubmoduleForceFallback: forceFallbackConvergence.allow,
+            });
+            return {
+                success: true,
+                removedPath: result.removedPath,
+                repoRoot,
+                ...(result.fallback ? {
+                    fallback: result.fallback,
+                    forced: result.forced,
+                    reason: result.reason,
+                    convergence: forceFallbackConvergence,
+                } : {}),
+            };
         } catch (e: any) {
             const message = String(e?.message || e || 'worktree cleanup failed');
             const dirty = message.includes('dirty worktree') || message.includes('local changes');
+            const submoduleForceBlocked = /working trees containing submodules cannot be moved or removed/i.test(message) && !forceFallbackConvergence.allow;
             return {
                 success: false,
-                code: dirty ? 'mesh_worktree_cleanup_dirty' : 'mesh_worktree_cleanup_failed',
-                error: message,
+                code: dirty
+                    ? 'mesh_worktree_cleanup_dirty'
+                    : submoduleForceBlocked
+                        ? 'mesh_worktree_cleanup_force_fallback_blocked'
+                        : 'mesh_worktree_cleanup_failed',
+                error: submoduleForceBlocked
+                    ? `${message}; refusing --force fallback because convergence could not be verified: ${forceFallbackConvergence.error || 'unknown convergence state'}`
+                    : message,
                 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.'
-                    : 'Inspect git worktree status/list from the source repo and retry after resolving the reported cleanup failure.',
+                    : 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.'
+                        : 'Inspect git worktree status/list from the source repo and retry after resolving the reported cleanup failure.',
+                ...(submoduleForceBlocked ? { convergence: forceFallbackConvergence } : {}),
             };
         }
     }
 
+    private async getWorktreeForceCleanupConvergence(args: {
+        repoRoot: string;
+        workspace: string;
+        node: any;
+    }): Promise<{ allow: boolean; status?: string; source?: string; ref?: string; error?: string }> {
+        const metadataStatus = typeof args.node?.branchConvergence?.status === 'string'
+            ? args.node.branchConvergence.status
+            : '';
+        if (metadataStatus === 'merged_to_main' || metadataStatus === 'cleanup_candidate') {
+            return { allow: true, status: metadataStatus, source: 'node_branch_convergence' };
+        }
+
+        const { execFile } = await import('node:child_process');
+        const { promisify } = await import('node:util');
+        const execFileAsync = promisify(execFile);
+        const runGit = async (gitArgs: string[], cwd: string): Promise<string> => {
+            const { stdout } = await execFileAsync('git', gitArgs, {
+                cwd,
+                encoding: 'utf8',
+                timeout: 30_000,
+                maxBuffer: 4 * 1024 * 1024,
+                windowsHide: true,
+            });
+            return String(stdout || '').trim();
+        };
+
+        let head = '';
+        try {
+            head = await runGit(['rev-parse', 'HEAD'], args.workspace);
+        } catch (e: any) {
+            return { allow: false, error: `could not resolve worktree HEAD: ${e?.message || e}` };
+        }
+        if (!head) return { allow: false, error: 'worktree HEAD is empty' };
+
+        const candidateRefs: string[] = [];
+        try {
+            const defaultBranch = await runGit(['branch', '--show-current'], args.repoRoot);
+            if (defaultBranch) {
+                candidateRefs.push(defaultBranch, `origin/${defaultBranch}`);
+            }
+        } catch { /* fall through to common refs */ }
+        candidateRefs.push('origin/main', 'origin/master', 'main', 'master');
+
+        const seen = new Set<string>();
+        const checkedRefs: string[] = [];
+        for (const ref of candidateRefs) {
+            if (!ref || seen.has(ref)) continue;
+            seen.add(ref);
+            let commit = '';
+            try {
+                commit = await runGit(['rev-parse', '--verify', `${ref}^{commit}`], args.repoRoot);
+            } catch {
+                continue;
+            }
+            checkedRefs.push(ref);
+            try {
+                await runGit(['merge-base', '--is-ancestor', head, commit], args.repoRoot);
+                return { allow: true, status: 'merged_to_default_ref', source: 'git_merge_base', ref };
+            } catch {
+                // Not contained in this candidate ref; keep checking other safe refs.
+            }
+        }
+
+        return {
+            allow: false,
+            status: metadataStatus || undefined,
+            error: checkedRefs.length
+                ? `worktree HEAD is not contained in checked refs: ${checkedRefs.join(', ')}`
+                : 'no default/main refs were available for convergence verification',
+        };
+    }
+
     private isCompletedHostedSession(record: any): boolean {
         return record?.lifecycle === 'stopped' || record?.lifecycle === 'failed' || record?.lifecycle === 'interrupted';
     }
@@ -1617,10 +1981,62 @@ export class DaemonCommandRouter {
                     const { stdout: baseBranchStdout } = await execFileAsync('git', ['branch', '--show-current'], { cwd: repoRoot, encoding: 'utf8' });
                     const baseBranch = baseBranchStdout.trim();
 
+                    const validationSummary = await runMeshRefineValidationGate(mesh, node.workspace);
+                    if (validationSummary.status === 'failed') {
+                        return {
+                            success: false,
+                            code: 'validation_failed',
+                            convergenceStatus: 'blocked_review',
+                            error: 'Refinery validation gate failed; merge/refine was not attempted.',
+                            branch,
+                            into: baseBranch,
+                            validationSummary,
+                            finalBranchConvergenceState: {
+                                branch,
+                                baseBranch,
+                                merged: false,
+                                removed: false,
+                                validation: 'failed',
+                                status: 'blocked_review',
+                            },
+                        };
+                    }
+                    if (validationSummary.status === 'skipped') {
+                        return {
+                            success: false,
+                            code: 'validation_unavailable',
+                            convergenceStatus: 'blocked_review',
+                            error: 'Refinery validation gate is required but no allowlisted validation command was available; merge/refine was not attempted.',
+                            branch,
+                            into: baseBranch,
+                            validationSummary,
+                            finalBranchConvergenceState: {
+                                branch,
+                                baseBranch,
+                                merged: false,
+                                removed: false,
+                                validation: 'unavailable',
+                                status: 'blocked_review',
+                            },
+                        };
+                    }
+
                     try {
                         await execFileAsync('git', ['merge', '--no-ff', branch, '-m', `Auto-merge branch '${branch}' via Refinery`], { cwd: repoRoot, encoding: 'utf8' });
                     } catch (e: any) {
-                        return { success: false, error: `Merge failed (conflicts?): ${e.message}` };
+                        return {
+                            success: false,
+                            error: `Merge failed (conflicts?): ${e.message}`,
+                            validationSummary,
+                            finalBranchConvergenceState: {
+                                branch,
+                                baseBranch,
+                                merged: false,
+                                removed: false,
+                                validation: 'passed',
+                                status: 'not_mergeable',
+                            },
+                        };
                     }
 
                     const removeResult = await this.execute('remove_mesh_node', {
@@ -1635,11 +2051,27 @@ export class DaemonCommandRouter {
                         appendLedgerEntry(meshId, {
                             kind: 'node_removed',
                             nodeId,
-                            payload: { refined: true, mergedBranch: branch, into: baseBranch },
+                            payload: { refined: true, mergedBranch: branch, into: baseBranch, validationSummary },
                         });
                     } catch {}
 
-                    return { success: true, merged: true, branch, into: baseBranch, removeResult };
+                    return {
+                        success: true,
+                        merged: true,
+                        branch,
+                        into: baseBranch,
+                        removeResult,
+                        validationSummary,
+                        finalBranchConvergenceState: {
+                            branch: baseBranch,
+                            mergedBranch: branch,
+                            baseBranch,
+                            merged: true,
+                            removed: removeResult?.success !== false,
+                            validation: 'passed',
+                            status: removeResult?.success === false ? 'merged_cleanup_failed' : 'merged',
+                        },
+                    };
                 } catch (e: any) {
                     return { success: false, error: e.message };
                 }
@@ -1701,6 +2133,9 @@ export class DaemonCommandRouter {
                                     workspace: typeof node?.workspace === 'string' ? node.workspace : undefined,
                                     daemonId: typeof node?.daemonId === 'string' ? node.daemonId : undefined,
                                     worktreeBranch: typeof node?.worktreeBranch === 'string' ? node.worktreeBranch : undefined,
+                                    worktreeCleanupFallback: typeof worktreeCleanup?.fallback === 'string' ? worktreeCleanup.fallback : undefined,
+                                    forced: worktreeCleanup?.forced === true ? true : undefined,
+                                    forceFallbackReason: typeof worktreeCleanup?.reason === 'string' ? worktreeCleanup.reason : undefined,
                                 },
                             });
                         } catch { /* ledger append is best-effort */ }

package/src/git/git-worktree.ts

@@ -20,6 +20,7 @@ const execFileAsync = promisify(execFile);
 const WORKTREE_DIR_NAME = '.adhdev-worktrees';
 const GIT_TIMEOUT_MS = 30_000;
 const GIT_MAX_BUFFER = 4 * 1024 * 1024;
+const SUBMODULE_WORKTREE_REMOVE_RE = /working trees containing submodules cannot be moved or removed/i;
 
 // ─── Types ──────────────────────────────────────
 
@@ -52,11 +53,20 @@ export interface WorktreeEntry {
 export interface WorktreeRemoveOptions {
     /** Refuse to remove a worktree with uncommitted or untracked changes. */
     requireClean?: boolean;
+    /**
+     * If normal removal fails with Git's submodule-worktree guard, retry with
+     * `git worktree remove --force`. Callers must perform their own
+     * higher-level managed-path/convergence checks before enabling this.
+     */
+    allowSubmoduleForceFallback?: boolean;
 }
 
 export interface WorktreeRemoveResult {
     success: true;
     removedPath: string;
+    fallback?: 'git_worktree_remove_force_submodule';
+    forced?: boolean;
+    reason?: 'working_trees_containing_submodules';
 }
 
 // ─── Path Resolution ────────────────────────────
@@ -157,7 +167,31 @@ export async function removeWorktree(repoRoot: string, worktreePath: string, opt
         });
     } catch (error: any) {
         const stderr = typeof error.stderr === 'string' ? error.stderr : '';
-        throw new Error(`git worktree remove failed: ${stderr.trim() || error.message}`);
+        const stdout = typeof error.stdout === 'string' ? error.stdout : '';
+        const detail = `${stderr}\n${stdout}\n${error.message || ''}`;
+        if (opts.allowSubmoduleForceFallback && SUBMODULE_WORKTREE_REMOVE_RE.test(detail)) {
+            try {
+                await execFileAsync('git', ['worktree', 'remove', '--force', worktreePath], {
+                    cwd: repoRoot,
+                    encoding: 'utf8',
+                    timeout: GIT_TIMEOUT_MS,
+                    maxBuffer: GIT_MAX_BUFFER,
+                    windowsHide: true,
+                });
+            } catch (forceError: any) {
+                const forceStderr = typeof forceError.stderr === 'string' ? forceError.stderr : '';
+                const forceStdout = typeof forceError.stdout === 'string' ? forceError.stdout : '';
+                throw new Error(`git worktree remove --force fallback failed: ${forceStderr.trim() || forceStdout.trim() || forceError.message}`);
+            }
+            return {
+                success: true,
+                removedPath: worktreePath,
+                fallback: 'git_worktree_remove_force_submodule',
+                forced: true,
+                reason: 'working_trees_containing_submodules',
+            };
+        }
+        throw new Error(`git worktree remove failed: ${stderr.trim() || stdout.trim() || error.message}`);
     }
 
     return { success: true, removedPath: worktreePath };