@adhdev/daemon-core 0.9.82-rc.31 → 0.9.82-rc.311

package/src/git/git-types.ts

@@ -6,69 +6,21 @@
  * infer these values from agent transcripts in frontend code.
  */
 
-export type GitFailureReason =
-  | 'not_git_repo'
-  | 'git_not_installed'
-  | 'timeout'
-  | 'path_outside_repo'
-  | 'dirty_index_required'
-  | 'conflict'
-  | 'invalid_args'
-  | 'nothing_to_commit'
-  | 'git_command_failed';
+// Pure shape types now live in @adhdev/mesh-shared so the cloud (web-core) and
+// standalone (daemon-core) transports share ONE definition instead of hand-syncing
+// two. Re-exported here so existing `from './git-types'` / package imports keep
+// working unchanged. Daemon-specific types (GitSnapshot, GitCommandName, …) stay
+// local below and consume these re-exports.
+export type {
+  GitFailureReason,
+  GitRepoIdentity,
+  GitSubmoduleStatus,
+  GitUpstreamFreshness,
+  GitRepoStatus,
+  DaemonBuildBehind,
+} from '@adhdev/mesh-shared';
 
-export interface GitRepoIdentity {
-  workspace: string;
-  repoRoot: string | null;
-  isGitRepo: boolean;
-}
-
-export interface GitSubmoduleStatus {
-  /** Submodule path relative to repo root */
-  path: string;
-  /** Current commit SHA the submodule is at */
-  commit: string;
-  /** Path to the submodule repo (absolute) */
-  repoPath: string;
-  /** Whether the submodule has uncommitted changes */
-  dirty: boolean;
-  /** Whether the submodule commit differs from what the parent repo expects */
-  outOfSync: boolean;
-  /** Last checked timestamp */
-  lastCheckedAt: number;
-  /** Error message if submodule status could not be read */
-  error?: string;
-}
-
-export type GitUpstreamFreshness = 'fresh' | 'unchecked' | 'stale' | 'no_upstream' | 'unavailable';
-
-export interface GitRepoStatus extends GitRepoIdentity {
-  branch: string | null;
-  headCommit: string | null;
-  headMessage: string | null;
-  upstream: string | null;
-  /** Whether ahead/behind was verified against a freshly fetched upstream ref. */
-  upstreamStatus: GitUpstreamFreshness;
-  /** Timestamp for the fetch that refreshed upstream refs when upstreamStatus === 'fresh'. */
-  upstreamFetchedAt?: number;
-  /** Error from the last refresh attempt when upstreamStatus === 'stale'. */
-  upstreamFetchError?: string;
-  ahead: number;
-  behind: number;
-  staged: number;
-  modified: number;
-  untracked: number;
-  deleted: number;
-  renamed: number;
-  hasConflicts: boolean;
-  conflictFiles: string[];
-  stashCount: number;
-  lastCheckedAt: number;
-  /** Submodule statuses when auto-discover is enabled */
-  submodules?: GitSubmoduleStatus[];
-  error?: string;
-  reason?: GitFailureReason;
-}
+import type { GitRepoIdentity, GitRepoStatus, GitFailureReason, GitUpstreamFreshness } from '@adhdev/mesh-shared';
 
 export type GitFileChangeStatus =
   | 'added'

package/src/git/git-worktree.ts

@@ -116,8 +116,11 @@ export async function createWorktree(opts: WorktreeCreateOptions): Promise<Workt
         });
     } catch (error: any) {
         const stderr = typeof error.stderr === 'string' ? error.stderr : '';
-        // Clean error messages for common failures
         if (/already exists/i.test(stderr)) {
+            // Distinguish directory-collision (TOCTOU race) from branch-already-exists
+            if (existsSync(targetDir)) {
+                throw new Error(`Worktree target directory was created concurrently: ${targetDir}`);
+            }
             throw new Error(`Branch '${branch}' already exists or is checked out in another worktree`);
         }
         throw new Error(`git worktree add failed: ${stderr.trim() || error.message}`);
@@ -170,6 +173,10 @@ export async function removeWorktree(repoRoot: string, worktreePath: string, opt
         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)) {
+            process.stderr.write(
+                `[adhdev-mesh] WARNING: git worktree remove --force fallback for submodule worktree '${worktreePath}'. `
+                + `Any uncommitted changes inside submodules will be lost.\n`,
+            );
             try {
                 await execFileAsync('git', ['worktree', 'remove', '--force', worktreePath], {
                     cwd: repoRoot,

package/src/index.ts

@@ -85,9 +85,28 @@ export type {
   InputMediaType,
 } from './shared-types.js';
 
+export type {
+  InteractivePrompt,
+  InteractiveQuestion,
+  InteractiveOption,
+  InteractivePromptResponse,
+  InteractiveAnswer,
+} from './providers/types/interactive-prompt.js';
+export {
+  normalizeInteractivePrompt,
+  normalizeInteractivePromptResponse,
+  buildClaudeInteractiveToolResult,
+  interactivePromptFromClaudeAskUserQuestion,
+  detectClaudeAskUserQuestionPromptFromJson,
+} from './providers/types/interactive-prompt.js';
+
 // ── Repo Mesh Types (cross-package) ──
 export type {
   RepoMesh,
+  RepoMeshDaemonRole,
+  RepoMeshHostMetadata,
+  RepoMeshHostPairingMetadata,
+  RepoMeshHostStatus,
   RepoMeshNode,
   RepoMeshNodeHealth,
   RepoMeshPolicy,
@@ -111,8 +130,20 @@ export type {
   RepoMeshLedgerEntryStatus,
   RepoMeshLedgerSummaryStatus,
   RepoMeshLedgerStatus,
+  MeshAsyncJobLifecycle,
+  RepoMeshSchedulingStrategy,
+} from './repo-mesh-types.js';
+export {
+  DEFAULT_MESH_POLICY,
+  resolveDelegatedWorkerAutoApprove,
+  MESH_SCHEDULING_STRATEGIES,
+  DEFAULT_MESH_SCHEDULING_STRATEGY,
+  normalizeMeshSchedulingStrategy,
+  resolveNodeSchedulingPriority,
+  MESH_CONVERGE_REFINE_TAG,
+  MESH_CONVERGE_FAST_FORWARD_TAG,
+  resolveAutoConvergeCodeChange,
 } from './repo-mesh-types.js';
-export { DEFAULT_MESH_POLICY } from './repo-mesh-types.js';
 
 // ── Git Surface ──
 export * from './git/index.js';
@@ -138,7 +169,7 @@ export type RecentSessionBucket = 'needs_attention' | 'working' | 'task_complete
 export type { IDaemonCore, DaemonCoreOptions } from './daemon-core.js';
 
 // ── Config ──
-export { loadConfig, saveConfig, resetConfig, isSetupComplete, markSetupComplete, updateConfig } from './config/config.js';
+export { loadConfig, saveConfig, resetConfig, isSetupComplete, markSetupComplete, updateConfig, getDaemonDataDir } from './config/config.js';
 export { getWorkspaceState } from './config/workspaces.js';
 export { appendRecentActivity, getRecentActivity } from './config/recent-activity.js';
 export type { RecentActivityEntry } from './config/recent-activity.js';
@@ -154,19 +185,59 @@ export type { CreateMeshOptions, UpdateMeshOptions, AddNodeOptions } from './con
 
 // ── Mesh Coordinator ──
 export { buildCoordinatorSystemPrompt } from './mesh/coordinator-prompt.js';
+export { upsertMeshMission, getMeshMissions, getMeshMission, summarizeMissionTasks, summarizeMeshMission, getActiveMeshMissionSummaries, getMeshStatusMissionSummaries, listMeshMissionSummaries, buildMissionPromptSection, GOAL_PREVIEW_MAX, MESH_MISSION_STATUSES } from './mesh/mesh-missions.js';
+export type { MeshMissionRecord, MeshMissionStatus, MeshMissionSummary, MeshMissionSlimSummary, MeshMissionTaskAggregate } from './mesh/mesh-missions.js';
+export { computeMeshTaskStats, computeMeshMissionStats } from './mesh/mesh-task-stats.js';
+export type { MeshTaskStats, MeshMissionStats } from './mesh/mesh-task-stats.js';
+export { deriveMeshReviewInboxItems } from './mesh/mesh-review-inbox.js';
+export type { MeshReviewInboxItem, MeshReviewInboxDerivation, MeshReviewInboxEvidence, MeshReviewInboxDiffSummary, MeshReviewInboxDiffFile, MeshReviewInboxReason, MeshReviewInboxConvergence } from './mesh/mesh-review-inbox.js';
 export type { CoordinatorPromptContext } from './mesh/coordinator-prompt.js';
-export { syncMeshes } from './mesh/mesh-sync.js';
-export type { MeshSyncTransport, MeshSyncResult, RemoteMeshRecord } from './mesh/mesh-sync.js';
+export { loadMeshCoordinatorRegistry, registerMeshCoordinator, unregisterMeshCoordinator, getCoordinatorForSession, listCoordinatorsForWorkspace } from './mesh/coordinator-registry.js';
+export type { CoordinatorRegistryEntry } from './mesh/coordinator-registry.js';
+export {
+  MESH_REFINE_CONFIG_LOCATIONS,
+  MESH_REFINE_CONFIG_SCHEMA,
+  loadMeshRefineConfig,
+  resolveMeshRefineValidationPlan,
+  suggestMeshRefineConfig,
+  validateMeshRefineConfig,
+} from './mesh/refine-config.js';
+export {
+  MESH_WORKTREE_BOOTSTRAP_CONFIG_LOCATIONS,
+  MESH_WORKTREE_BOOTSTRAP_CONFIG_SCHEMA,
+  loadMeshWorktreeBootstrapConfig,
+  runMeshWorktreeBootstrap,
+  validateMeshWorktreeBootstrapConfig,
+  type RepoMeshWorktreeBootstrapConfig,
+  type WorktreeBootstrapState,
+} from './mesh/worktree-bootstrap-config.js';
+export type {
+  MeshRefineValidationCategory,
+  MeshRefineValidationCommandPlan,
+  MeshRefineValidationPlan,
+  RepoMeshRefineConfig,
+  RepoMeshRefineValidationCommandConfig,
+} from './mesh/refine-config.js';
 
 // ── Mesh Task Ledger ──
-export { appendLedgerEntry, appendRemoteLedgerEntries, readLedgerEntries, readLedgerSlice, getLedgerSummary, getLedgerDir, getSessionRecoveryContext, MAX_LEDGER_SLICE_LIMIT } from './mesh/mesh-ledger.js';
-export type { AppendRemoteLedgerResult, MeshLedgerEntry, MeshLedgerKind, MeshLedgerSlice, MeshLedgerSummary, ReadLedgerOptions, ReadLedgerSliceOptions, SessionRecoveryContext } from './mesh/mesh-ledger.js';
+export { appendLedgerEntry, appendRemoteLedgerEntries, buildTaskCompletionEvidence, normalizeMeshWorkerResult, readLedgerEntries, readLedgerSlice, readLedgerSliceFromStore, getLedgerSummary, getLedgerDir, getSessionRecoveryContext, MAX_LEDGER_SLICE_LIMIT } from './mesh/mesh-ledger.js';
+export type { AppendRemoteLedgerResult, MeshLedgerEntry, MeshLedgerKind, MeshLedgerSlice, MeshLedgerSummary, ReadLedgerOptions, ReadLedgerSliceOptions, SessionRecoveryContext, MeshTaskCompletionEvidence, MeshWorkerResultArtifact, MeshProcessArtifact, MeshValidationResultArtifact } from './mesh/mesh-ledger.js';
+export { fastForwardMeshNode } from './mesh/mesh-fast-forward.js';
+export type { MeshFastForwardNodeArgs, MeshFastForwardPlannedStep, MeshFastForwardResult } from './mesh/mesh-fast-forward.js';
 export { buildMeshLedgerReconciliationEvidence, buildMeshLedgerReplicaEvidence } from './mesh/mesh-ledger-reconciliation.js';
-export type { MeshLedgerReconciliationEvidence, MeshLedgerReplicaEvidence, MeshLedgerReplicaStatus } from './mesh/mesh-ledger-reconciliation.js';
+export type { AnyLedgerSlice, MeshLedgerReconciliationEvidence, MeshLedgerReplicaEvidence, MeshLedgerReplicaStatus } from './mesh/mesh-ledger-reconciliation.js';
 
 // ── Mesh Work Queue (GUPP) ──
-export { enqueueTask, getQueue, claimNextTask, updateTaskStatus, updateSessionTaskStatus, cancelTask, requeueTask, getMeshQueueStats } from './mesh/mesh-work-queue.js';
-export type { MeshWorkQueueEntry, MeshTaskStatus, MeshWorkQueueStats } from './mesh/mesh-work-queue.js';
+export { enqueueTask, recordDirectDispatchTask, getQueue, claimNextTask, updateTaskStatus, updateSessionTaskStatus, cancelTask, requeueTask, getMeshQueueStats, getMeshQueueRevision, normalizeMeshTaskMode, validateMeshTaskModeRequest, buildMeshNodeCapabilityTags, nodeSatisfiesRequiredTags, normalizeMeshCapabilityTags, resolveConvergeRequiredTags, insertDirectDispatch, getActiveDirectDispatches, updateDirectDispatchStatus, cleanupTerminalDirectDispatches, markStaleDirectDispatches, deleteDirectDispatchesByTaskId, recordMeshToolCall, assertNoDependencyCycle, hasPendingDependents, describeTaskDependencyState } from './mesh/mesh-work-queue.js';
+export type { MeshWorkQueueEntry, MeshTaskStatus, MeshTaskMode, MeshWorkQueueStats, MeshQueueMutationOptions, MeshTaskModeValidationResult, DirectDispatchRecord, MeshToolCallRateResult } from './mesh/mesh-work-queue.js';
+export { buildCompactStaleDirectWorkSummary, buildMeshActiveWork, buildMeshActiveWorkSummary, classifyStaleDirectForPrune, PRUNABLE_ORPHAN_STALE_REASONS } from './mesh/mesh-active-work.js';
+export type { StaleDirectPruneClassification } from './mesh/mesh-active-work.js';
+export type { MeshActiveWorkRecord, MeshActiveWorkStatus, MeshActiveWorkSummary, MeshActiveWorkSource, MeshStaleDirectWorkSummary } from './mesh/mesh-active-work.js';
+export { buildMeshAsyncRefineJobs, summarizeMeshAsyncRefineJobs, STALE_TERMINAL_REFINE_WINDOW_MS, RECENT_TERMINAL_REFINE_CAP } from './mesh/mesh-refine-status.js';
+export type { MeshAsyncRefineJobStatus, MeshAsyncRefineJobSummary, MeshAsyncRefineJobsSummary } from './mesh/mesh-refine-status.js';
+
+// ── Mesh Host Ownership ──
+export { buildMeshHostRequiredFailure, createDefaultMeshHostMetadata, isMeshHostOwner, normalizeMeshDaemonRole, requireMeshHostQueueOwner, resolveMeshHostStatus } from './mesh/mesh-host-ownership.js';
 
 // ── Mesh Visualization ──
 // buildMeshGraph and MeshGraph types moved to @adhdev/web-core to avoid
@@ -176,9 +247,13 @@ export type { MeshWorkQueueEntry, MeshTaskStatus, MeshWorkQueueStats } from './m
 // 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 Delivery Policy ──
+export { resolveDeliveryDecision, createSessionDelivery, updateSessionDeliveryStatus, getActiveSessionDeliveries, markSessionDeliveriesTerminal, recordCompletionConflict, getRecentCompletionConflicts } from './mesh/mesh-delivery-policy.js';
+export type { MeshSessionDeliveryStatus, MeshSessionDeliveryKind, MeshDeliveryDecision, MeshDeliveryPolicyResult, SessionDeliveryRecord } from './mesh/mesh-delivery-policy.js';
+
 // ── Mesh P2P Relay Failure Classification ──
 export {
   P2pRelayFailureError,
@@ -222,7 +297,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,
@@ -243,6 +318,8 @@ export type {
 export { DaemonStatusReporter } from './status/reporter.js';
 export { buildSessionEntries, findCdpManager, hasCdpManager, isCdpConnected } from './status/builders.js';
 export { buildStatusSnapshot, buildMachineInfo } from './status/snapshot.js';
+export { getDaemonBuildInfo } from './build-info.js';
+export type { DaemonBuildInfo } from './build-info.js';
 export { normalizeManagedStatus, isManagedStatusWorking, isManagedStatusWaiting, normalizeActiveChatData } from './status/normalize.js';
 export type { ManagedStatus } from './status/normalize.js';
 export type { StatusSnapshotOptions, StatusSnapshot } from './status/snapshot.js';
@@ -388,6 +465,13 @@ export type { CliAdapter } from './cli-adapter-types.js';
 export { NodePtyTransportFactory } from './cli-adapters/pty-transport.js';
 export type { PtyRuntimeTransport, PtyTransportFactory, PtySpawnOptions } from './cli-adapters/pty-transport.js';
 export { SessionHostPtyTransportFactory } from './cli-adapters/session-host-transport.js';
+export {
+  RawTerminalAttachment,
+  namedKeyToAnsi,
+  namedKeysToAnsi,
+  withRawTerminalAttachment,
+} from './cli-adapters/raw-terminal-io.js';
+export type { NamedKey, RawTerminalAttachmentOptions, RawTerminalSessionHostClient } from './cli-adapters/raw-terminal-io.js';
 export type { HostedCliRuntimeDescriptor, CliTransportFactoryParams } from './commands/cli-manager.js';
 export {
   DEFAULT_SESSION_HOST_APP_NAME,
@@ -415,3 +499,50 @@ export type { ExtensionInfo as InstallerExtensionInfo } from './installer.js';
 // ── Boot / Lifecycle ──
 export { initDaemonComponents, startDaemonDevSupport, shutdownDaemonComponents } from './boot/daemon-lifecycle.js';
 export type { DaemonInitConfig, DaemonComponents, DaemonDevSupportOptions } from './boot/daemon-lifecycle.js';
+
+// ── Local IPC server (shared between cloud + standalone daemons) ──
+export {
+  startLocalIpcServer,
+  buildIpcStatusHttpResponse,
+  type LocalIpcServerOptions,
+  type LocalIpcServerHandle,
+  type IpcCommandContext,
+  type IpcCommandResult,
+  type IpcStatusPayload,
+} from './ipc/local-ipc-server.js';
+
+// ── CLI Spec (adhdev:cli/spec@4) ──
+export { createNativeHistoryDispatcher } from './providers/native-history/index.js';
+export type { ReaderId } from './providers/native-history/index.js';
+export {
+    readClaudeCliSession, readCodexCliSession,
+    readAntigravityCliSession, readHermesCliSession,
+} from './providers/native-history/index.js';
+export type {
+    ControlAction, Control,
+    NotificationRule, DelegateTrigger,
+} from './providers/spec/types.js';
+export type { TraceEntry } from './providers/spec/evaluator.js';
+export { evaluateFsm } from './providers/spec/fsm-evaluator.js';
+export type { FsmClock } from './providers/spec/fsm-evaluator.js';
+export { validateFsmSpec } from './providers/spec/fsm-loader.js';
+export { FsmDriver } from './providers/spec/fsm-driver.js';
+export type { DashboardEvent, DashboardCommand, SpecDriverOpts, ISpecDriver } from './providers/spec/fsm-driver.js';
+export { TerminalAdapter } from './providers/spec/adapter.js';
+export type { TerminalAdapterOpts, TerminalAdapterHandlers } from './providers/spec/adapter.js';
+
+// ── Provider SDK (v1) — selective re-exports for external tooling ──
+// Tooling (registry publish, dashboard validators, the e2e harness) needs
+// the manifest validator, the builder catalog, and the contract version.
+// We don't re-export *everything* from the SDK to keep the public surface
+// stable; consumers that need internal SDK types still import from the
+// sdk/v1 subpath.
+export {
+  validateCliProviderManifest,
+  formatManifestValidationIssues,
+  type ManifestValidationIssue,
+  type ManifestValidationResult,
+  V1_CONTRACT_VERSION,
+  V1_PRIMITIVE_CATALOG,
+  V1_ALL_PRIMITIVES,
+} from './providers/sdk/v1/index.js';

package/src/installer.d.ts

@@ -31,7 +31,7 @@ export interface InstallResult {
 /**
  * Check if an extension is already installed
  */
-export declare function isExtensionInstalled(ide: IDEInfo, marketplaceId: string): boolean;
+export declare function isExtensionInstalled(ide: IDEInfo, marketplaceId: string): Promise<boolean>;
 /**
  * Install a single extension
  */

package/src/installer.ts

@@ -122,20 +122,22 @@ export interface InstallResult {
 /**
  * Check if an extension is already installed
  */
-export function isExtensionInstalled(
+import { promisify } from 'util';
+const execAsync = promisify(exec);
+
+export async function isExtensionInstalled(
     ide: IDEInfo,
     marketplaceId: string
-): boolean {
+): Promise<boolean> {
     if (!ide.cliCommand) return false;
 
     try {
-        const result = execSync(`"${ide.cliCommand}" --list-extensions`, {
+        const { stdout } = await execAsync(`"${ide.cliCommand}" --list-extensions`, {
             encoding: 'utf-8',
             timeout: 15000,
-            stdio: ['pipe', 'pipe', 'pipe'],
         });
 
-        const installed = result
+        const installed = stdout
             .trim()
             .split('\n')
             .map((e) => e.trim().toLowerCase());
@@ -163,7 +165,7 @@ export async function installExtension(
     }
 
  // Check if already installed
-    const alreadyInstalled = isExtensionInstalled(ide, extension.marketplaceId);
+    const alreadyInstalled = await isExtensionInstalled(ide, extension.marketplaceId);
     if (alreadyInstalled) {
         return {
             extensionId: extension.id,

package/src/ipc/local-ipc-server.ts

@@ -0,0 +1,278 @@
+/**
+ * LocalIpcServer — generic HTTP + WebSocket IPC endpoint for daemon processes.
+ *
+ * Both daemon-cloud and daemon-standalone need a local IPC surface so
+ * external tools — the `adhdev mcp --mode ipc` MCP server and anything
+ * else that wants to issue commands without going through the cloud
+ * Worker — can connect over `ws://127.0.0.1:<port>/ipc`.
+ *
+ * Until now the implementation lived only in daemon-cloud. Standalone
+ * sessions therefore couldn't host MCP mesh tools — codex/claude config
+ * pointing at `--mode ipc` got `Cannot reach ipc daemon`. This module
+ * moves the transport into daemon-core so both daemons can mount it.
+ *
+ * The transport itself is daemon-agnostic. Cloud-specific behaviors
+ * (mesh relay, mandatory update gates) are injected via the caller's
+ * `handleCommand` hook; the IPC layer just frames/unframes JSON and
+ * routes messages.
+ */
+
+import { createServer, type IncomingMessage, type Server as HttpServer } from 'http';
+import { WebSocketServer, WebSocket } from 'ws';
+import { LOG } from '../logging/logger.js';
+import { DAEMON_WS_PATH } from '../ipc-protocol.js';
+
+/** Parameters passed to `handleCommand` for each incoming ext:command frame. */
+export interface IpcCommandContext {
+    /** The raw `command` field from the message — caller decides routing. */
+    command: string;
+    /** Args provided by the client; may have been normalized by the caller. */
+    args: Record<string, unknown>;
+    /** Stable id correlating the request and the eventual ext:command_result. */
+    requestId: string;
+    /** The connected WebSocket — only needed if the caller wants to send extra events. */
+    ws: WebSocket;
+}
+
+/** Result reported back to the client. `result` is optional context for success. */
+export interface IpcCommandResult {
+    success: boolean;
+    result?: unknown;
+    error?: string;
+    /**
+     * Additional fields the caller wants merged into the response payload
+     * (e.g. the cloud daemon's mandatory-update-block fields). Reserved.
+     */
+    extra?: Record<string, unknown>;
+}
+
+/** Status payload returned from GET / on the IPC HTTP port. */
+export interface IpcStatusPayload {
+    ok: true;
+    pid: number;
+    wsPath: string;
+    port: number;
+    /** Arbitrary daemon-specific summary. Cloud daemon includes mesh state, etc. */
+    status: Record<string, unknown> | null;
+}
+
+export interface LocalIpcServerOptions {
+    /** TCP port to listen on. 19222 is the conventional default. */
+    port: number;
+    /** Build the GET / status payload. Called on every health probe. */
+    buildStatusPayload: () => Record<string, unknown> | null;
+    /** Build the welcome message sent to a freshly-connected client. */
+    buildWelcomePayload: () => Record<string, unknown>;
+    /** Handle a single ext:command frame. Caller decides routing and returns the result. */
+    handleCommand: (ctx: IpcCommandContext) => Promise<IpcCommandResult>;
+    /** Optional notification when a new client connects (lets daemon track them for broadcasts). */
+    onClientConnected?: (ws: WebSocket) => void;
+    /** Optional notification when a client disconnects. */
+    onClientDisconnected?: (ws: WebSocket) => void;
+    /** Optional logger label (defaults to "IPC"). */
+    logCategory?: string;
+}
+
+/**
+ * Returned controller for stopping the server and broadcasting to clients.
+ * Stored by the daemon and torn down at shutdown.
+ */
+export interface LocalIpcServerHandle {
+    /** True once `listen()` succeeded. */
+    isListening(): boolean;
+    /** Push a message to every connected client. */
+    broadcast(type: string, payload: unknown): void;
+    /** Close all client sockets + the HTTP server. */
+    close(): Promise<void>;
+}
+
+/**
+ * Build a JSON HTTP response describing the IPC endpoint. Exposed so caller
+ * code (and tests) can build the same shape without spinning a real server.
+ */
+export function buildIpcStatusHttpResponse(
+    method: string | undefined,
+    url: string | undefined,
+    payload: IpcStatusPayload,
+): { statusCode: number; body: Record<string, unknown> } {
+    if (method && method.toUpperCase() !== 'GET') {
+        return { statusCode: 405, body: { ok: false, error: 'method not allowed' } };
+    }
+    // `/health` is the probe path used by the MCP IpcTransport ping —
+    // mirror cloud daemon behavior so `adhdev mcp --mode ipc` recognizes
+    // us as a live IPC host. `/` and `/status` return the same shape.
+    if (url && url !== '/' && url !== '/status' && url !== '/health') {
+        return { statusCode: 404, body: { ok: false, error: 'not found' } };
+    }
+    return { statusCode: 200, body: payload as unknown as Record<string, unknown> };
+}
+
+/**
+ * Start the local IPC server. Returns a handle the caller can use to broadcast
+ * events and tear down at shutdown.
+ */
+export async function startLocalIpcServer(opts: LocalIpcServerOptions): Promise<LocalIpcServerHandle> {
+    const logCategory = opts.logCategory || 'IPC';
+    const clients = new Set<WebSocket>();
+    let httpServer: HttpServer | null = null;
+    let wss: WebSocketServer | null = null;
+    let listening = false;
+
+    httpServer = createServer((req, res) => {
+        const payload: IpcStatusPayload = {
+            ok: true,
+            pid: process.pid,
+            wsPath: DAEMON_WS_PATH,
+            port: opts.port,
+            status: opts.buildStatusPayload(),
+        };
+        const response = buildIpcStatusHttpResponse(req.method, req.url, payload);
+        const body = JSON.stringify(response.body);
+        res.writeHead(response.statusCode, {
+            'Content-Type': 'application/json',
+            'Content-Length': Buffer.byteLength(body),
+            'Connection': 'close',
+        });
+        res.end(body);
+    });
+
+    wss = new WebSocketServer({ noServer: true });
+    wss.on('connection', (ws) => handleConnection(ws));
+
+    httpServer.on('upgrade', (req: IncomingMessage, socket, head) => {
+        const wsUrl = new URL(req.url || '/', `http://${req.headers.host || '127.0.0.1'}`);
+        if (wsUrl.pathname !== DAEMON_WS_PATH) {
+            socket.write('HTTP/1.1 404 Not Found\r\n\r\n');
+            socket.destroy();
+            return;
+        }
+        wss!.handleUpgrade(req, socket, head, (ws) => {
+            wss!.emit('connection', ws, req);
+        });
+    });
+
+    function handleConnection(ws: WebSocket): void {
+        clients.add(ws);
+        sendWelcome(ws);
+        opts.onClientConnected?.(ws);
+
+        ws.on('message', (raw) => {
+            void handleMessage(ws, raw.toString());
+        });
+        ws.on('close', () => {
+            clients.delete(ws);
+            opts.onClientDisconnected?.(ws);
+        });
+        ws.on('error', () => {
+            clients.delete(ws);
+            opts.onClientDisconnected?.(ws);
+        });
+    }
+
+    function sendWelcome(ws: WebSocket): void {
+        try {
+            ws.send(JSON.stringify({
+                type: 'daemon:welcome',
+                payload: opts.buildWelcomePayload(),
+            }));
+        } catch (error: any) {
+            LOG.warn(logCategory, `Failed to send welcome: ${error?.message || error}`);
+        }
+    }
+
+    async function handleMessage(ws: WebSocket, raw: string): Promise<void> {
+        let msg: any;
+        try { msg = JSON.parse(raw); } catch { return; }
+        if (!msg || typeof msg !== 'object') return;
+
+        // Re-issue welcome on client request (used by reconnecting MCP servers).
+        if (msg.type === 'ext:register') {
+            sendWelcome(ws);
+            return;
+        }
+        if (msg.type !== 'ext:command') return;
+
+        const payload = msg.payload && typeof msg.payload === 'object' ? msg.payload : {};
+        const command = typeof payload.command === 'string' ? payload.command : '';
+        const args = payload.args && typeof payload.args === 'object'
+            ? payload.args as Record<string, unknown>
+            : {};
+        const requestId = typeof payload.requestId === 'string'
+            ? payload.requestId
+            : typeof payload.messageId === 'string'
+                ? payload.messageId
+                : `ipc-${Date.now()}`;
+
+        if (!command) {
+            ws.send(JSON.stringify({
+                type: 'ext:command_result',
+                payload: { requestId, success: false, error: 'command required' },
+            }));
+            return;
+        }
+
+        try {
+            const result = await opts.handleCommand({ command, args, requestId, ws });
+            ws.send(JSON.stringify({
+                type: 'ext:command_result',
+                payload: {
+                    requestId,
+                    success: result.success,
+                    result: result.result,
+                    error: result.error,
+                    ...(result.extra || {}),
+                },
+            }));
+        } catch (error: any) {
+            ws.send(JSON.stringify({
+                type: 'ext:command_result',
+                payload: {
+                    requestId,
+                    success: false,
+                    error: error?.message || String(error),
+                },
+            }));
+        }
+    }
+
+    await new Promise<void>((resolve, reject) => {
+        const onError = (error: Error) => {
+            httpServer?.off('listening', onListening);
+            reject(error);
+        };
+        const onListening = () => {
+            httpServer?.off('error', onError);
+            listening = true;
+            resolve();
+        };
+        httpServer!.once('error', onError);
+        httpServer!.once('listening', onListening);
+        httpServer!.listen(opts.port, '127.0.0.1');
+    });
+
+    LOG.info(logCategory, `Local IPC listening on ws://127.0.0.1:${opts.port}${DAEMON_WS_PATH}`);
+
+    return {
+        isListening: () => listening,
+        broadcast(type, payload) {
+            const message = JSON.stringify({ type, payload });
+            for (const client of clients) {
+                if (client.readyState !== WebSocket.OPEN) continue;
+                try { client.send(message); } catch { /* drop silently */ }
+            }
+        },
+        async close() {
+            for (const client of clients) {
+                try { client.close(); } catch { /* ignore */ }
+            }
+            clients.clear();
+            await new Promise<void>((resolve) => {
+                if (!httpServer) { resolve(); return; }
+                httpServer.close(() => resolve());
+            });
+            httpServer = null;
+            wss = null;
+            listening = false;
+        },
+    };
+}

package/src/launch.d.ts

@@ -18,7 +18,7 @@
 /** Kill IDE process (graceful → force) */
 export declare function killIdeProcess(ideId: string): Promise<boolean>;
 /** Check if IDE process is running */
-export declare function isIdeRunning(ideId: string): boolean;
+export declare function isIdeRunning(ideId: string): Promise<boolean>;
 export interface LaunchOptions {
     ideId?: string;
     workspace?: string;