@adhdev/daemon-core 0.9.82-rc.186 → 0.9.82-rc.188

package/src/commands/mesh-coordinator.ts

@@ -1,7 +1,7 @@
 import { createHash } from 'node:crypto'
 import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import * as os from 'node:os'
-import { isAbsolute, join, resolve } from 'node:path'
+import { basename, isAbsolute, join, resolve } from 'node:path'
 import { LOG } from '../logging/logger.js'
 import type {
   MeshCoordinatorMcpConfigFormat,
@@ -39,6 +39,7 @@ export type MeshCoordinatorSetup =
       command: string
       requiresRestart: boolean
       instructions: string
+      mcpServer: MeshCoordinatorMcpServerLaunch
     }
   | {
       kind: 'unsupported'
@@ -71,6 +72,8 @@ function resolveHermesMeshCoordinatorSetup(options: ResolveMeshCoordinatorSetupO
   const mcpServer = resolveAdhdevMcpServerLaunch({
     meshId: options.meshId,
     adhdevMcpCommand: options.adhdevMcpCommand,
+    adhdevMcpEntryPath: options.adhdevMcpEntryPath,
+    nodeExecutable: options.nodeExecutable,
     adhdevMcpTransport: options.adhdevMcpTransport,
     adhdevMcpPort: options.adhdevMcpPort,
   })
@@ -144,6 +147,8 @@ export function resolveMeshCoordinatorSetup(options: ResolveMeshCoordinatorSetup
     const mcpServer = resolveAdhdevMcpServerLaunch({
       meshId,
       adhdevMcpCommand: options.adhdevMcpCommand,
+      adhdevMcpEntryPath: options.adhdevMcpEntryPath,
+      nodeExecutable: options.nodeExecutable,
       adhdevMcpTransport: options.adhdevMcpTransport,
       adhdevMcpPort: options.adhdevMcpPort,
     })
@@ -168,22 +173,41 @@ export function resolveMeshCoordinatorSetup(options: ResolveMeshCoordinatorSetup
     if (!instructions || !template?.trim()) {
       return { kind: 'unsupported', reason: 'Provider manual MCP setup is missing instructions or template' }
     }
-    const renderedTemplate = renderMeshCoordinatorTemplate(template, {
+    const mcpServer = resolveAdhdevMcpServerLaunch({
+      meshId,
+      adhdevMcpCommand: options.adhdevMcpCommand,
+      adhdevMcpEntryPath: options.adhdevMcpEntryPath,
+      nodeExecutable: options.nodeExecutable,
+      adhdevMcpTransport: options.adhdevMcpTransport,
+      adhdevMcpPort: options.adhdevMcpPort,
+    })
+    if (!mcpServer) {
+      return {
+        kind: 'unsupported',
+        reason: 'Could not resolve the ADHDev MCP server entrypoint and transport arguments',
+      }
+    }
+    let renderedTemplate = renderMeshCoordinatorTemplate(template, {
       meshId,
       workspace,
       serverName,
-      adhdevMcpCommand: options.adhdevMcpCommand || DEFAULT_ADHDEV_MCP_COMMAND,
+      adhdevMcpCommand: mcpServer.command,
+      adhdevMcpArgs: mcpServer.args.join(' '),
     })
     // Detect if the template is a runnable CLI command (single line, no YAML/JSON structure).
     // If so, use cli_command kind so the daemon can execute it automatically.
     const isCliCommand = !renderedTemplate.trim().includes('\n') && !renderedTemplate.trim().startsWith('{')
     if (isCliCommand) {
+      if (!/\{\{\s*adhdevMcpArgs\s*\}\}/.test(template)) {
+        renderedTemplate = replaceLegacyCliCommandMcpArgs(renderedTemplate, mcpServer.args)
+      }
       return {
         kind: 'cli_command',
         serverName,
         command: renderedTemplate.trim(),
         requiresRestart: mcpConfig.requiresRestart === true,
         instructions: instructions,
+        mcpServer,
       }
     }
     return {
@@ -204,7 +228,14 @@ export function resolveMeshCoordinatorSetup(options: ResolveMeshCoordinatorSetup
 }
 
 function renderMeshCoordinatorTemplate(template: string, values: Record<string, string>): string {
-  return template.replace(/\{\{\s*(meshId|workspace|serverName|adhdevMcpCommand)\s*\}\}/g, (_, key: string) => values[key] || '')
+  return template.replace(/\{\{\s*(meshId|workspace|serverName|adhdevMcpCommand|adhdevMcpArgs)\s*\}\}/g, (_, key: string) => values[key] || '')
+}
+
+function replaceLegacyCliCommandMcpArgs(command: string, args: string[]): string {
+  return command.replace(
+    /\bmcp\s+--mode\s+(?:ipc|local)\s+--repo-mesh\s+\S+(?:\s+--port\s+\d+)?\s*$/,
+    args.join(' '),
+  )
 }
 
 function resolveHermesCoordinatorHome(meshId: string, workspace: string): string {
@@ -224,12 +255,29 @@ function resolveMcpConfigPath(configPath: string, workspace: string): string {
 function resolveAdhdevMcpServerLaunch(options: {
   meshId: string
   adhdevMcpCommand?: string
+  adhdevMcpEntryPath?: string
+  nodeExecutable?: string
   adhdevMcpTransport?: 'local' | 'ipc'
   adhdevMcpPort?: number
 }): MeshCoordinatorMcpServerLaunch | null {
+  const directEntryPath = resolveAdhdevMcpEntryPath(options.adhdevMcpEntryPath)
+  if (directEntryPath) {
+    const transport = resolveMcpTransport(options.adhdevMcpTransport)
+    const args = [directEntryPath, '--mode', transport, '--repo-mesh', options.meshId]
+    const port = resolveMcpPort(options.adhdevMcpPort)
+    if (port !== undefined) args.push('--port', String(port))
+    return {
+      command: resolveNodeExecutable(options.nodeExecutable),
+      args,
+    }
+  }
+
   const command = resolveAdhdevCommand(options.adhdevMcpCommand)
   const transport = resolveMcpTransport(options.adhdevMcpTransport)
-  const args = ['mcp', '--mode', transport, '--repo-mesh', options.meshId]
+  const directMcpEntrypoint = basename(command).startsWith('adhdev-mcp')
+    || command.includes('/vendor/mcp-server/')
+    || command.includes('\\vendor\\mcp-server\\')
+  const args = [...(directMcpEntrypoint ? [] : ['mcp']), '--mode', transport, '--repo-mesh', options.meshId]
   const port = resolveMcpPort(options.adhdevMcpPort)
   if (port !== undefined) args.push('--port', String(port))
   return {
@@ -242,6 +290,17 @@ function resolveAdhdevCommand(explicitCommand?: string): string {
   return explicitCommand?.trim() || process.env.ADHDEV_COORDINATOR_MCP_COMMAND?.trim() || DEFAULT_ADHDEV_MCP_COMMAND
 }
 
+function resolveAdhdevMcpEntryPath(explicitEntryPath?: string): string | null {
+  const entryPath = explicitEntryPath?.trim() || process.env.ADHDEV_COORDINATOR_MCP_ENTRY_PATH?.trim()
+  return entryPath || null
+}
+
+function resolveNodeExecutable(explicitNodeExecutable?: string): string {
+  return explicitNodeExecutable?.trim()
+    || process.env.ADHDEV_COORDINATOR_NODE_EXECUTABLE?.trim()
+    || process.execPath
+}
+
 function resolveMcpTransport(explicitTransport?: 'local' | 'ipc'): 'local' | 'ipc' {
   if (explicitTransport === 'local' || explicitTransport === 'ipc') return explicitTransport
   const envTransport = process.env.ADHDEV_COORDINATOR_MCP_TRANSPORT?.trim()
@@ -418,6 +477,52 @@ export interface PtyExecResult {
   timedOut: boolean
 }
 
+export interface MeshCoordinatorRegistrationStep {
+  command: string
+  args: string[]
+  required: boolean
+  label: 'remove_existing' | 'register'
+}
+
+/**
+ * Codex rejects `mcp add` when a server with the same name already exists.
+ * Replace that entry before registering so transport/mesh changes do not leave
+ * a fresh coordinator attached to stale MCP launch arguments.
+ */
+export function buildMeshCoordinatorRegistrationPlan(
+  cliType: string,
+  serverName: string,
+  registrationCommand: string,
+): MeshCoordinatorRegistrationStep[] {
+  const commandParts = registrationCommand.trim().split(/\s+/).filter(Boolean)
+  const [command, ...args] = commandParts
+  if (!command) return []
+
+  const register: MeshCoordinatorRegistrationStep = {
+    command,
+    args,
+    required: true,
+    label: 'register',
+  }
+  if (
+    cliType === 'codex-cli'
+    && basename(command) === 'codex'
+    && args[0] === 'mcp'
+    && args[1] === 'add'
+  ) {
+    return [
+      {
+        command,
+        args: ['mcp', 'remove', serverName],
+        required: false,
+        label: 'remove_existing',
+      },
+      register,
+    ]
+  }
+  return [register]
+}
+
 /**
  * Run a one-shot CLI command under a real PTY and collect its output.
  *

package/src/commands/router.ts

@@ -849,7 +849,7 @@ function readCachedInlineMeshActiveSessions(node: any): string[] {
     return sessionId ? [sessionId] : [];
 }
 
-function readCachedInlineMeshActiveSessionDetails(node: any): Array<Record<string, unknown>> {
+export function readCachedInlineMeshActiveSessionDetails(node: any): Array<Record<string, unknown>> {
     const cachedStatus = readObjectRecord(node?.cachedStatus);
     const activeSession = readObjectRecord(cachedStatus.activeSession);
     const fallbackSession = Object.keys(activeSession).length
@@ -877,9 +877,14 @@ function readCachedInlineMeshActiveSessionDetails(node: any): Array<Record<strin
             node?.provider_type,
         ),
         state: readStringValue(fallbackSession.status, fallbackSession.state, fallbackSession.lifecycle),
+        chatStatus: readStringValue(fallbackSession.chatStatus, fallbackSession.chat_status),
         lifecycle: readStringValue(fallbackSession.lifecycle),
         title: readStringValue(fallbackSession.title, fallbackSession.displayName, fallbackSession.display_name) ?? null,
         workspace: readStringValue(fallbackSession.workspace, node?.workspace) ?? null,
+        role: readStringValue(fallbackSession.role) ?? null,
+        isSelfCoordinator: fallbackSession.isSelfCoordinator === true || fallbackSession.is_self_coordinator === true,
+        createdAt: readStringValue(fallbackSession.createdAt, fallbackSession.created_at) ?? null,
+        startedAt: readStringValue(fallbackSession.startedAt, fallbackSession.started_at) ?? null,
         lastActivityAt: readStringValue(fallbackSession.lastActivityAt, fallbackSession.last_activity_at) ?? null,
         recoveryState: readStringValue(fallbackSession.recoveryState, fallbackSession.recovery_state) ?? null,
         isCached: true,
@@ -1067,15 +1072,28 @@ async function hydrateInlineMeshDirectTruth(args: {
 }
 
 function summarizeMeshSessionRecord(record: any): Record<string, unknown> {
+    const meta = readObjectRecord(record?.meta);
+    const isSelfCoordinator = Boolean(readStringValue(meta.meshCoordinatorFor));
+    const chatStatus = readStringValue(record?.chatStatus, record?.activeChat?.status, meta.chatStatus, meta.sessionStatus);
+    const state = readLiveMeshSessionState(record);
+    const statusNote = isSelfCoordinator && (!chatStatus || chatStatus === 'idle' || state === 'idle')
+        ? 'Coordinator self status is sampled from the session host and may read idle while the coordinator is generating this response.'
+        : null;
     return {
         sessionId: readStringValue(record?.sessionId) || 'unknown',
         providerType: readStringValue(record?.providerType),
-        state: readLiveMeshSessionState(record),
+        state,
+        chatStatus,
         lifecycle: readStringValue(record?.lifecycle),
         surfaceKind: getSessionHostSurfaceKind(record as any),
-        recoveryState: readStringValue(record?.meta?.runtimeRecoveryState) ?? null,
+        recoveryState: readStringValue(meta.runtimeRecoveryState) ?? null,
         workspace: readStringValue(record?.workspace) ?? null,
         title: readStringValue(record?.displayName, record?.workspaceLabel) ?? null,
+        role: isSelfCoordinator ? 'coordinator' : readStringValue(meta.meshRole, meta.role) ?? null,
+        isSelfCoordinator,
+        statusNote,
+        createdAt: toIsoTimestamp(record?.createdAt ?? record?.created_at),
+        startedAt: toIsoTimestamp(record?.startedAt ?? record?.started_at ?? record?.spawnedAtMs ?? record?.spawned_at_ms),
         lastActivityAt: toIsoTimestamp(record?.updatedAt ?? record?.lastActivityAt ?? record?.last_activity_at),
         isCached: false,
     };
@@ -2130,12 +2148,14 @@ export interface CommandRouterDeps {
     /** Reference to detected IDEs array (mutable — router updates it) */
     detectedIdes: { value: any[] };
     sessionRegistry: SessionRegistry;
-    /** Callback for CDP manager creation after launch_ide */
+    /** Callback after CDP manager created (transport-specific extras) */
     onCdpManagerCreated?: (ideType: string, manager: DaemonCdpManager) => void;
     /** Callback after IDE connected (e.g., startAgentStreamPolling) */
     onIdeConnected?: () => void;
     /** Callback after status change (stop_ide, restart) */
     onStatusChange?: () => void;
+    /** Callback when a mesh state is invalidated */
+    onMeshStateChange?: (meshId: string) => void;
     /** Callback after chat-related commands */
     onPostChatCommand?: () => void;
     /** Get a connected CDP manager (for agent stream reset check) */
@@ -2456,6 +2476,16 @@ export class DaemonCommandRouter {
         return next;
     }
 
+    public getCachedInlineMeshNodes(): any[] {
+        const nodes: any[] = [];
+        for (const mesh of this.inlineMeshCache.values()) {
+            if (Array.isArray(mesh?.nodes)) {
+                nodes.push(...mesh.nodes);
+            }
+        }
+        return nodes;
+    }
+
     public getCachedInlineMesh(meshId: string, inlineMesh?: unknown): any | undefined {
         if (inlineMesh && typeof inlineMesh === 'object') {
             return this.warmInlineMeshCache(meshId, inlineMesh);
@@ -2510,6 +2540,7 @@ export class DaemonCommandRouter {
 
     private invalidateAggregateMeshStatus(meshId: string): void {
         this.aggregateMeshStatusCache.delete(meshId);
+        this.deps.onMeshStateChange?.(meshId);
     }
 
 
@@ -4852,6 +4883,13 @@ export class DaemonCommandRouter {
                         ...(role ? { role } : {}),
                     });
                     if (!node) return { success: false, error: 'Mesh not found' };
+                    // mesh_status hands back a coordinator-memory aggregate
+                    // snapshot keyed on (meshId, queueRevision). Adding a
+                    // node touches neither, so without an explicit cache
+                    // bust the dashboard graph keeps rendering the pre-add
+                    // node list (empty for a fresh mesh) even after the
+                    // user clicks Refresh.
+                    this.invalidateAggregateMeshStatus(meshId);
                     return { success: true, node };
                 } catch (e: any) {
                     return { success: false, error: e.message };
@@ -4889,6 +4927,11 @@ export class DaemonCommandRouter {
                     }
                     const node = updateNode(meshId, nodeId, patch as any);
                     if (!node) return { success: false, error: 'Mesh node not found' };
+                    // Provider priority / systemPrompt changes don't touch
+                    // the queue revision, so without a manual bust the
+                    // cached aggregate keeps surfacing pre-update values
+                    // (priority chip, coordinator prompt preview, etc.).
+                    this.invalidateAggregateMeshStatus(meshId);
                     return { success: true, node };
                 } catch (e: any) {
                     return { success: false, error: e.message };
@@ -5057,6 +5100,11 @@ export class DaemonCommandRouter {
                     let removed = false;
                     if (meshRecord?.inline) {
                         removed = this.removeInlineMeshNode(meshId, mesh, nodeId);
+                        // Inline meshes share the same aggregate snapshot cache as
+                        // local-config meshes; without this bust the removed node
+                        // keeps showing up in the dashboard graph until the cache
+                        // ages out on its own.
+                        if (removed) this.invalidateAggregateMeshStatus(meshId);
                     } else {
                         const { removeNode } = await import('../config/mesh-config.js');
                         removed = removeNode(meshId, nodeId);
@@ -5278,10 +5326,8 @@ export class DaemonCommandRouter {
                 if (ownerFailure) return ownerFailure;
                 try {
                     const { triggerMeshQueue } = await import('../mesh/mesh-events.js');
-                    if (meshId) {
-                        triggerMeshQueue(this.deps as any, meshId);
-                    }
-                    return { success: true };
+                    const trigger = await triggerMeshQueue(this.deps as any, meshId);
+                    return { success: true, trigger };
                 } catch (e: any) {
                     return { success: false, error: e.message };
                 }
@@ -5434,23 +5480,102 @@ export class DaemonCommandRouter {
                         // a real PTY the registration goes through and the
                         // exit code tells us whether it actually persisted.
                         let mcpRegistrationOk = false;
+                        let mcpRegistrationFailure: {
+                            command: string;
+                            output: string;
+                            exitCode: number | null;
+                            signal: number | null;
+                            timedOut: boolean;
+                        } | null = null;
                         try {
-                            const { execUnderPty } = await import('./mesh-coordinator.js');
-                            const cmdParts = coordinatorSetup.command.trim().split(/\s+/);
-                            const [regCmd, ...regArgs] = cmdParts;
-                            LOG.info('MeshCoordinator', `Running MCP registration (pty): ${coordinatorSetup.command}`);
-                            const ptyResult = await execUnderPty(regCmd, regArgs, { cwd: workspace, timeoutMs: 20_000 });
-                            if (ptyResult.timedOut) {
-                                LOG.warn('MeshCoordinator', `MCP registration timed out — last output:\n${ptyResult.output.slice(-2000)}`);
-                            } else if (ptyResult.exitCode === 0) {
-                                mcpRegistrationOk = true;
-                                LOG.info('MeshCoordinator', `MCP registration succeeded (exit=0)`);
-                            } else {
-                                // Non-fatal — many providers return non-zero on duplicate registration.
-                                LOG.warn('MeshCoordinator', `MCP registration exit=${ptyResult.exitCode} signal=${ptyResult.signal} — output:\n${ptyResult.output.slice(-2000)}`);
+                            const { buildMeshCoordinatorRegistrationPlan, execUnderPty } = await import('./mesh-coordinator.js');
+                            const registrationPlan = buildMeshCoordinatorRegistrationPlan(
+                                cliType,
+                                coordinatorSetup.serverName,
+                                coordinatorSetup.command,
+                            );
+                            for (const step of registrationPlan) {
+                                const renderedCommand = [step.command, ...step.args].join(' ');
+                                LOG.info('MeshCoordinator', `Running MCP ${step.label} (pty): ${renderedCommand}`);
+                                const ptyResult = await execUnderPty(step.command, step.args, { cwd: workspace, timeoutMs: 20_000 });
+                                if (ptyResult.exitCode === 0 && !ptyResult.timedOut) {
+                                    if (step.required) mcpRegistrationOk = true;
+                                    continue;
+                                }
+                                LOG.warn('MeshCoordinator', `MCP ${step.label} failed exit=${ptyResult.exitCode} signal=${ptyResult.signal} timedOut=${ptyResult.timedOut} — output:\n${ptyResult.output.slice(-2000)}`);
+                                if (step.required) {
+                                    mcpRegistrationFailure = {
+                                        command: renderedCommand,
+                                        output: ptyResult.output.slice(-2000),
+                                        exitCode: ptyResult.exitCode,
+                                        signal: ptyResult.signal,
+                                        timedOut: ptyResult.timedOut,
+                                    };
+                                    break;
+                                }
                             }
                         } catch (error: any) {
                             LOG.warn('MeshCoordinator', `MCP registration command failed: ${error?.message || error}`);
+                            mcpRegistrationFailure = {
+                                command: coordinatorSetup.command,
+                                output: error?.message || String(error),
+                                exitCode: null,
+                                signal: null,
+                                timedOut: false,
+                            };
+                        }
+
+                        if (!mcpRegistrationOk) {
+                            return {
+                                success: false,
+                                code: 'mesh_coordinator_mcp_registration_failed',
+                                error: `Could not register ${coordinatorSetup.serverName}; coordinator session was not launched`,
+                                meshId,
+                                cliType,
+                                workspace,
+                                registration: mcpRegistrationFailure,
+                            };
+                        }
+
+                        // Codex gives repo-local .mcp.json precedence over its
+                        // global `codex mcp add` registration. Refresh an
+                        // existing ADHDev entry so a stale workspace command
+                        // cannot shadow the registration we just verified.
+                        if (cliType === 'codex-cli') {
+                            const repoMcpConfigPath = pathJoin(workspace, '.mcp.json');
+                            if (fs.existsSync(repoMcpConfigPath)) {
+                                try {
+                                    const repoMcpConfig = parseMeshCoordinatorMcpConfig(
+                                        fs.readFileSync(repoMcpConfigPath, 'utf-8'),
+                                        'claude_mcp_json',
+                                    );
+                                    const existingServers = repoMcpConfig.mcpServers;
+                                    if (
+                                        existingServers
+                                        && typeof existingServers === 'object'
+                                        && !Array.isArray(existingServers)
+                                        && existingServers[coordinatorSetup.serverName]
+                                    ) {
+                                        fs.writeFileSync(repoMcpConfigPath, serializeMeshCoordinatorMcpConfig({
+                                            ...repoMcpConfig,
+                                            mcpServers: {
+                                                ...existingServers,
+                                                [coordinatorSetup.serverName]: coordinatorSetup.mcpServer,
+                                            },
+                                        }, 'claude_mcp_json'), 'utf-8');
+                                        LOG.info('MeshCoordinator', `Refreshed repo-local ${repoMcpConfigPath} entry for ${coordinatorSetup.serverName}`);
+                                    }
+                                } catch (error: any) {
+                                    return {
+                                        success: false,
+                                        code: 'mesh_coordinator_config_write_failed',
+                                        error: `Could not refresh repo-local MCP config: ${error?.message || error}`,
+                                        meshId,
+                                        cliType,
+                                        workspace,
+                                    };
+                                }
+                            }
                         }
 
                         // Inject system prompt declaratively from provider.v1.json.

package/src/config/chat-history.ts

@@ -1350,6 +1350,7 @@ type ProviderNativeHistoryReadResult = {
     sourcePath: string;
     sourceMtimeMs: number;
     providerSessionId?: string;
+    workspace?: string;
     nativeHistoryCoverage?: string;
     partialReason?: string;
     unavailableReason?: string;
@@ -1449,6 +1450,7 @@ function callProviderNativeHistoryRead(
         sourcePath: typeof (result as any).sourcePath === 'string' ? (result as any).sourcePath : '',
         sourceMtimeMs: Number((result as any).sourceMtimeMs) || 0,
         providerSessionId: typeof (result as any).providerSessionId === 'string' ? (result as any).providerSessionId.trim() : undefined,
+        workspace: typeof (result as any).workspace === 'string' ? (result as any).workspace.trim() : undefined,
         nativeHistoryCoverage: typeof (result as any).nativeHistoryCoverage === 'string' ? (result as any).nativeHistoryCoverage.trim() : undefined,
         partialReason: typeof (result as any).partialReason === 'string' ? (result as any).partialReason.trim() : undefined,
         unavailableReason: typeof (result as any).unavailableReason === 'string' ? (result as any).unavailableReason.trim() : undefined,
@@ -1537,6 +1539,7 @@ export function readProviderChatHistory(
     sourcePath?: string;
     sourceMtimeMs?: number;
     providerSessionId?: string;
+    workspace?: string;
     nativeHistoryCoverage?: string;
     partialReason?: string;
     unavailableReason?: string;
@@ -1550,6 +1553,7 @@ export function readProviderChatHistory(
             sourcePath: nativeResult.sourcePath,
             sourceMtimeMs: nativeResult.sourceMtimeMs,
             providerSessionId: nativeResult.providerSessionId,
+            workspace: nativeResult.workspace,
             nativeHistoryCoverage: nativeResult.nativeHistoryCoverage,
             partialReason: nativeResult.partialReason,
             unavailableReason: nativeResult.unavailableReason,

package/src/git/git-commands.ts

@@ -66,7 +66,7 @@ export interface GitPushResult extends GitRepoIdentity {
 }
 
 export interface GitCommandServices {
-  getStatus?: (params: { workspace: string; refreshUpstream?: boolean }) => Promise<GitRepoStatus> | GitRepoStatus;
+  getStatus?: (params: { workspace: string; refreshUpstream?: boolean; includeSubmodules?: boolean; submoduleIgnorePaths?: string[] }) => Promise<GitRepoStatus> | GitRepoStatus;
   getDiffSummary?: (params: { workspace: string; staged?: boolean }) => Promise<GitDiffSummary> | GitDiffSummary;
   getDiffFile?: (params: { workspace: string; path: string; staged?: boolean }) => Promise<GitFileDiff> | GitFileDiff;
   createSnapshot?: (params: {
@@ -294,7 +294,16 @@ export async function handleGitCommand(
   switch (command) {
     case 'git_status': {
       if (!services.getStatus) return serviceNotImplemented(command);
-      const status = await runService(() => services.getStatus!({ workspace, refreshUpstream: optionalBoolean(args?.refreshUpstream) }));
+      const submoduleIgnorePaths = Array.isArray(args?.submoduleIgnorePaths)
+        ? args.submoduleIgnorePaths.filter((value: unknown): value is string => typeof value === 'string' && value.trim().length > 0)
+        : undefined;
+      const statusParams: { workspace: string; refreshUpstream?: boolean; includeSubmodules?: boolean; submoduleIgnorePaths?: string[] } = { workspace };
+      const refreshUpstream = optionalBoolean(args?.refreshUpstream);
+      const includeSubmodules = optionalBoolean(args?.includeSubmodules);
+      if (refreshUpstream !== undefined) statusParams.refreshUpstream = refreshUpstream;
+      if (includeSubmodules !== undefined) statusParams.includeSubmodules = includeSubmodules;
+      if (submoduleIgnorePaths && submoduleIgnorePaths.length > 0) statusParams.submoduleIgnorePaths = submoduleIgnorePaths;
+      const status = await runService(() => services.getStatus!(statusParams));
       return 'success' in status ? status : { success: true, status };
     }
 
@@ -446,6 +455,15 @@ async function gitCheckpoint(
   if (statusResult.hasConflicts) {
     throw new GitCommandError('conflict', 'Repository has conflicts — resolve before checkpointing');
   }
+  const dirtySubmodules = (statusResult.submodules || []).filter(submodule => submodule.dirty);
+  if (dirtySubmodules.length > 0) {
+    const paths = dirtySubmodules.map(submodule => submodule.path).join(', ');
+    throw new GitCommandError(
+      'dirty_index_required',
+      `Repository has dirty submodules that must be checkpointed first: ${paths}. ` +
+      'Checkpoint or commit each dirty submodule, then checkpoint this repository to record gitlink changes.',
+    );
+  }
 
   const addArgs = includeUntracked ? ['-A'] : ['-u'];
   await runGit(repo, ['add', ...addArgs], { cwd: repoRoot });

package/src/git/git-status.ts

@@ -48,6 +48,11 @@ export async function getGitRepoStatus(
     if (includeSubmodules) {
       submodules = await getSubmoduleStatuses(repo, options);
     }
+    const submoduleDirty = (submodules || []).some(submodule => submodule.dirty || submodule.outOfSync || !!submodule.error);
+    const dirty = parsed.staged + parsed.modified + parsed.untracked + parsed.deleted + parsed.renamed > 0
+      || parsed.conflictFiles.length > 0
+      || stashCount > 0
+      || submoduleDirty;
 
     return {
       workspace: repo.workspace,
@@ -67,6 +72,7 @@ export async function getGitRepoStatus(
       untracked: parsed.untracked,
       deleted: parsed.deleted,
       renamed: parsed.renamed,
+      dirty,
       hasConflicts: parsed.conflictFiles.length > 0,
       conflictFiles: parsed.conflictFiles,
       stashCount,
@@ -285,6 +291,7 @@ function emptyStatus(workspace: string, lastCheckedAt: number, error: GitCommand
     untracked: 0,
     deleted: 0,
     renamed: 0,
+    dirty: false,
     hasConflicts: false,
     conflictFiles: [],
     stashCount: 0,
@@ -304,12 +311,34 @@ async function getSubmoduleStatuses(
 
   try {
     const result = await runGit(repo, ['submodule', 'status', '--recursive'], options);
-    return parseSubmoduleStatusOutput(result.stdout, repo.repoRoot, options.submoduleIgnorePaths);
+    const submodules = parseSubmoduleStatusOutput(result.stdout, repo.repoRoot, options.submoduleIgnorePaths);
+    await Promise.all(submodules.map(submodule => enrichSubmoduleWorktreeStatus(repo, submodule, options)));
+    return submodules;
   } catch {
     return [];
   }
 }
 
+async function enrichSubmoduleWorktreeStatus(
+  repo: ResolvedGitRepo,
+  submodule: GitSubmoduleStatus,
+  options: GitStatusOptions,
+): Promise<void> {
+  try {
+    const result = await runGit(repo, ['status', '--porcelain=v2', '--branch'], {
+      ...options,
+      cwd: submodule.repoPath,
+    });
+    const parsed = parsePorcelainV2Status(result.stdout);
+    const dirty = parsed.staged + parsed.modified + parsed.untracked + parsed.deleted + parsed.renamed > 0
+      || parsed.conflictFiles.length > 0;
+    submodule.dirty = submodule.dirty || dirty;
+  } catch (error) {
+    submodule.dirty = true;
+    submodule.error = formatGitError(error);
+  }
+}
+
 function parseSubmoduleStatusOutput(
   output: string,
   repoRoot: string,
@@ -321,9 +350,9 @@ function parseSubmoduleStatusOutput(
   for (const line of output.split('\n')) {
     if (!line.trim()) continue;
 
-    // Format: [+- ]<commit> <path> (<branch>)
-    // - = out of sync, + = dirty, ' ' = clean
-    const match = line.match(/^([\-+\s])([0-9a-f]{40})\s+(\S+)(?:\s+\(([^)]+)\))?/);
+    // Format: [+-U ]<commit> <path> (<branch>)
+    // - = not initialized, + = gitlink out of sync, U = conflict, ' ' = aligned.
+    const match = line.match(/^([\-+U\s])([0-9a-f]{40})\s+(\S+)(?:\s+\(([^)]+)\))?/);
     if (!match) continue;
 
     const prefix = match[1];
@@ -336,8 +365,8 @@ function parseSubmoduleStatusOutput(
       path,
       commit,
       repoPath: repoRoot + '/' + path,
-      dirty: prefix === '+',
-      outOfSync: prefix === '-',
+      dirty: prefix === 'U',
+      outOfSync: prefix === '-' || prefix === '+',
       lastCheckedAt: Date.now(),
     });
   }

package/src/git/git-types.ts

@@ -60,6 +60,8 @@ export interface GitRepoStatus extends GitRepoIdentity {
   untracked: number;
   deleted: number;
   renamed: number;
+  /** Aggregate dirty flag including root worktree changes, conflicts, stash, and submodule drift. */
+  dirty: boolean;
   hasConflicts: boolean;
   conflictFiles: string[];
   stashCount: number;

package/src/index.ts

@@ -229,7 +229,7 @@ export { buildMeshHostRequiredFailure, createDefaultMeshHostMetadata, isMeshHost
 // export type { MeshGraph, MeshGraphNode, MeshGraphEdge, MeshGraphNodeType, MeshGraphEdgeType } from './mesh/mesh-visualization.js';
 
 // ── Mesh Events ──
-export { triggerMeshQueue, drainPendingMeshCoordinatorEvents, getPendingMeshCoordinatorEvents, clearPendingMeshCoordinatorEvents, queuePendingMeshCoordinatorEvent } from './mesh/mesh-events.js';
+export { triggerMeshQueue, drainPendingMeshCoordinatorEvents, getPendingMeshCoordinatorEvents, clearPendingMeshCoordinatorEvents, queuePendingMeshCoordinatorEvent, reconcileDirectDispatchCompletionFromTranscript } from './mesh/mesh-events.js';
 export type { PendingMeshCoordinatorEvent } from './mesh/mesh-events.js';
 
 // ── Mesh P2P Relay Failure Classification ──
@@ -275,7 +275,7 @@ export type { CdpInitializerConfig } from './cdp/initializer.js';
 // ── Commands ──
 export { DaemonCommandHandler } from './commands/handler.js';
 export type { CommandResult, CommandContext } from './commands/handler.js';
-export { DaemonCommandRouter } from './commands/router.js';
+export { DaemonCommandRouter, readCachedInlineMeshActiveSessionDetails } from './commands/router.js';
 export type { CommandRouterDeps, CommandRouterResult } from './commands/router.js';
 export {
   maybeRunDaemonUpgradeHelperFromEnv,

package/src/mesh/beads-db.ts

@@ -474,6 +474,10 @@ export class BeadsDB {
         `).run(cutoff);
     }
 
+    deleteDirectDispatches(meshId: string): void {
+        this.db.prepare(`DELETE FROM mesh_direct_dispatches WHERE mesh_id = ?`).run(meshId);
+    }
+
     markStaleDirectDispatches(meshId: string, olderThanMs: number): void {
         const cutoff = new Date(Date.now() - olderThanMs).toISOString();
         const now = new Date().toISOString();