@adhdev/daemon-core 0.9.76-rc.2 → 0.9.76-rc.20

package/dist/mesh/coordinator-prompt.d.ts

@@ -14,5 +14,6 @@ export interface CoordinatorPromptContext {
     mesh: LocalMeshEntry;
     status?: RepoMeshStatus;
     userInstruction?: string;
+    coordinatorCliType?: string;
 }
 export declare function buildCoordinatorSystemPrompt(ctx: CoordinatorPromptContext): string;

package/dist/providers/cli-provider-instance.d.ts

@@ -8,6 +8,7 @@ import { type ProviderModule } from './contracts.js';
 import type { ProviderInstance, ProviderState, InstanceContext, HotChatSessionState, SessionModalState } from './provider-instance.js';
 import { ProviderCliAdapter } from '../cli-adapters/provider-cli-adapter.js';
 import type { PtyTransportFactory } from '../cli-adapters/pty-transport.js';
+import type { ChatMessage } from '../types.js';
 type PersistableCliHistoryMessage = {
     role: string;
     content: string;
@@ -67,6 +68,7 @@ export declare class CliProviderInstance implements ProviderInstance {
     constructor(provider: ProviderModule, workingDir: string, cliArgs?: string[], instanceId?: string, transportFactory?: PtyTransportFactory, options?: {
         providerSessionId?: string;
         launchMode?: 'new' | 'resume' | 'manual';
+        extraEnv?: Record<string, string>;
         onProviderSessionResolved?: (info: {
             instanceId: string;
             providerType: string;
@@ -112,6 +114,7 @@ export declare class CliProviderInstance implements ProviderInstance {
     private maybeAppendRuntimeRecoveryMessage;
     private appendRuntimeSystemMessage;
     private appendRuntimeMessage;
+    mergeRuntimeChatMessages(parsedMessages: ChatMessage[]): ChatMessage[];
     private mergeConversationMessages;
     private formatApprovalRequestMessage;
     private promoteProviderSessionId;

package/dist/repo-mesh-types.d.ts

@@ -149,6 +149,10 @@ export interface LocalMeshNodeEntry {
     policy: RepoMeshNodePolicy;
     /** For single-machine mesh: same daemon, different worktree */
     isLocalWorktree?: boolean;
+    /** Branch this worktree tracks (set when created via clone_mesh_node) */
+    worktreeBranch?: string;
+    /** Node ID this worktree was cloned from */
+    clonedFromNodeId?: string;
 }
 export interface RepoMeshStatus {
     meshId: string;

package/dist/shared-types.d.ts

@@ -328,6 +328,15 @@ export interface CompactSessionEntry {
     settings?: Record<string, any>;
 }
 export type VersionUpdateReason = 'force_update_below' | 'major_minor_mismatch' | 'patch_mismatch' | 'daemon_ahead';
+export type ReleaseChannel = 'stable' | 'preview';
+export type NpmUpdateTag = 'latest' | 'next';
+export interface VersionUpdatePolicy {
+    channel: ReleaseChannel;
+    npmTag: NpmUpdateTag;
+    targetVersion: string;
+    minVersion?: string;
+    updateCommand: string;
+}
 /** Available provider information */
 export interface AvailableProviderInfo {
     type: string;
@@ -469,6 +478,10 @@ export interface CompactDaemonEntry {
     versionMismatch?: boolean;
     versionUpdateRequired?: boolean;
     versionUpdateReason?: VersionUpdateReason;
+    releaseChannel?: ReleaseChannel;
+    updateChannel?: ReleaseChannel;
+    updatePolicy?: VersionUpdatePolicy;
+    updateCommand?: string;
     terminalBackend?: TerminalBackendStatus;
     detectedIdes?: DetectedIdeInfo[];
     availableProviders?: AvailableProviderInfo[];
@@ -490,10 +503,14 @@ export interface CloudDaemonSummaryEntry {
     versionMismatch?: boolean;
     versionUpdateRequired?: boolean;
     versionUpdateReason?: VersionUpdateReason;
+    releaseChannel?: ReleaseChannel;
+    updateChannel?: ReleaseChannel;
+    updatePolicy?: VersionUpdatePolicy;
+    updateCommand?: string;
     terminalBackend?: TerminalBackendStatus;
 }
 /** Minimal daemon bootstrap payload used by dashboard WS to initiate P2P. */
-export interface DashboardBootstrapDaemonEntry {
+export interface DashboardBootstrapDaemonEntry extends Partial<CloudDaemonSummaryEntry> {
     id: string;
     p2p?: StatusReportPayload['p2p'];
     timestamp?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/daemon-core",
-  "version": "0.9.76-rc.2",
+  "version": "0.9.76-rc.20",
   "description": "ADHDev daemon core — CDP, IDE detection, providers, command execution",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -52,16 +52,15 @@
     "chalk": "^5.3.0",
     "chokidar": "^5.0.0",
     "conf": "^13.0.0",
+    "js-yaml": "^4.1.1",
     "node-pty": "^1.2.0-beta.12",
     "ws": "^8.19.0"
   },
-  "bundleDependencies": [
-    "@adhdev/session-host-core"
-  ],
   "optionalDependencies": {
     "@adhdev/ghostty-vt-node": "*"
   },
   "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.0.0",
     "@types/ws": "^8.18.1",
     "tsup": "^8.2.0",

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

@@ -266,9 +266,10 @@ export class ProviderCliAdapter implements CliAdapter {
         const currentSnapshot = normalizeScreenSnapshot(screenText);
         const lastSnapshot = this.lastScreenSnapshot;
         if (!lastSnapshot || lastSnapshot === currentSnapshot) return screenText;
-        const staleSnapshotLooksActive = /\besc to (?:interrupt|stop)\b|Enter to interrupt, Ctrl\+C to cancel/i.test(lastSnapshot);
-        const currentScreenLooksIdle = /(?:^|\n|\r)\s*[❯›>]\s*(?:\n|\r|$)/.test(screenText)
-            && !/\besc to (?:interrupt|stop)\b|Enter to interrupt, Ctrl\+C to cancel/i.test(screenText);
+        const activeScreenPattern = /\besc to (?:interrupt|stop)\b|Enter to interrupt, Ctrl\+C to cancel|Enter to confirm\s*[·•-]\s*Esc to cancel|\b(?:MCP servers?|tool calls?)\b[^\n\r]{0,160}\brequire approval\b/i;
+        const staleSnapshotLooksActive = activeScreenPattern.test(lastSnapshot);
+        const currentScreenLooksIdle = /(?:^|\n|\r)\s*[❯›>]\s*(?:Try\s+["“][^\n\r"”]+["”])?\s*(?:\n|\r|$)/.test(screenText)
+            && !activeScreenPattern.test(screenText);
         if (staleSnapshotLooksActive && currentScreenLooksIdle) return screenText;
         if (currentSnapshot.length >= lastSnapshot.length) return screenText;
         // Terminal screen reads can miss a just-rendered completed Hermes box while
@@ -421,6 +422,7 @@ export class ProviderCliAdapter implements CliAdapter {
         provider: CliProviderModule,
         workingDir: string,
         private extraArgs: string[] = [],
+        private extraEnv: Record<string, string> = {},
         transportFactory: PtyTransportFactory = new NodePtyTransportFactory(),
     ) {
         this.provider = provider;
@@ -522,6 +524,7 @@ export class ProviderCliAdapter implements CliAdapter {
             runtimeSettings: this.runtimeSettings,
             workingDir: this.workingDir,
             extraArgs: this.extraArgs,
+            extraEnv: this.extraEnv,
         });
 
         LOG.info('CLI', `[${this.cliType}] Spawning in ${this.workingDir}`);

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

@@ -27,8 +27,9 @@ export function resolveCliSpawnPlan(options: {
     runtimeSettings: Record<string, any>;
     workingDir: string;
     extraArgs: string[];
+    extraEnv?: Record<string, string>;
 }): CliSpawnPlan {
-    const { provider, runtimeSettings, workingDir, extraArgs } = options;
+    const { provider, runtimeSettings, workingDir, extraArgs, extraEnv } = options;
     const { spawn: spawnConfig } = provider;
     const configuredCommand = typeof runtimeSettings.executablePath === 'string' && runtimeSettings.executablePath.trim()
         ? runtimeSettings.executablePath.trim()
@@ -65,7 +66,7 @@ export function resolveCliSpawnPlan(options: {
         shellArgs = allArgs;
     }
 
-    const env = buildCliSpawnEnv(process.env, spawnConfig.env);
+    const env = buildCliSpawnEnv(process.env, { ...(spawnConfig.env || {}), ...(extraEnv || {}) });
     // Some CLI agents, notably Hermes, route their tools through TERMINAL_CWD
     // rather than process.cwd(). Keep the generic ADHDev launch workspace as
     // the single source of truth so PTY cwd and tool cwd cannot diverge.

package/src/commands/chat-commands.ts

@@ -28,6 +28,10 @@ interface ApprovalSelectableInstance extends ProviderInstance {
     recordApprovalSelection?(buttonText: string): void;
 }
 
+interface RuntimeChatMessageMerger extends ProviderInstance {
+    mergeRuntimeChatMessages?(messages: ChatMessage[]): ChatMessage[];
+}
+
 type LegacyStringScript = (params?: Record<string, unknown> | string) => string;
 
 function getCurrentProviderType(h: CommandHelpers, fallback = ''): string {
@@ -250,6 +254,40 @@ function normalizeReadChatCommandStatus(status: unknown, activeModal: unknown):
     }
 }
 
+function isGeneratingLikeStatus(status: unknown): boolean {
+    return status === 'generating' || status === 'streaming' || status === 'long_generating' || status === 'starting';
+}
+
+function shouldTrustCliAdapterTerminalStatus(parsedStatus: unknown, activeModal: unknown, adapter: CliAdapter, adapterStatus: any): boolean {
+    if (!isGeneratingLikeStatus(parsedStatus)) return false;
+    if (hasNonEmptyModalButtons(activeModal)) return false;
+    const adapterRawStatus = typeof adapterStatus?.status === 'string' ? adapterStatus.status.trim() : '';
+    if (adapterRawStatus !== 'idle') return false;
+    if (typeof adapter.isProcessing === 'function' && adapter.isProcessing()) return false;
+    return true;
+}
+
+function normalizeCliReadChatStatus(parsedStatus: unknown, activeModal: unknown, adapter: CliAdapter, adapterStatus: any): string {
+    if (shouldTrustCliAdapterTerminalStatus(parsedStatus, activeModal, adapter, adapterStatus)) return 'idle';
+    return typeof parsedStatus === 'string' && parsedStatus.trim() ? parsedStatus : 'idle';
+}
+
+function finalizeStreamingMessagesWhenIdle(messages: ChatMessage[], status: string): ChatMessage[] {
+    if (status !== 'idle') return messages;
+    return messages.map((message) => {
+        const meta = message.meta && typeof message.meta === 'object'
+            ? message.meta as Record<string, unknown>
+            : undefined;
+        const hasStreamingMeta = meta?.streaming === true;
+        if (message.bubbleState !== 'streaming' && !hasStreamingMeta) return message;
+        return {
+            ...message,
+            ...(message.bubbleState === 'streaming' ? { bubbleState: 'final' as const } : {}),
+            ...(hasStreamingMeta ? { meta: { ...meta, streaming: false } } : {}),
+        };
+    });
+}
+
 function buildReadChatCommandResult(payload: Record<string, any>, args: any): CommandResult {
     let validatedPayload: Record<string, any>;
     const debugReadChat = payload?.debugReadChat && typeof payload.debugReadChat === 'object'
@@ -760,10 +798,17 @@ export async function handleReadChat(h: CommandHelpers, args: any): Promise<Comm
                 ? parsedRecord.coverage
                 : undefined;
             const activeModal = parsedRecord.activeModal ?? parsedRecord.modal ?? null;
-            const returnedStatus = parsedRecord.status || 'idle';
-            LOG.debug('Command', `[read_chat] cli-like parsed provider=${adapter.cliType} target=${String(args?.targetSessionId || '')} adapterStatus=${String(adapterStatus.status || '')} parsedStatus=${String(parsedRecord.status || '')} parsedMsgCount=${parsedRecord.messages.length}`);
+            const returnedStatus = normalizeCliReadChatStatus(parsedRecord.status, activeModal, adapter, adapterStatus);
+            const runtimeMessageMerger = getTargetInstance(h, args) as RuntimeChatMessageMerger | null;
+            const parsedMessages = finalizeStreamingMessagesWhenIdle(parsedRecord.messages as ChatMessage[], returnedStatus);
+            const returnedMessages = runtimeMessageMerger?.category === 'cli'
+                && runtimeMessageMerger.type === adapter.cliType
+                && typeof runtimeMessageMerger.mergeRuntimeChatMessages === 'function'
+                ? runtimeMessageMerger.mergeRuntimeChatMessages(parsedMessages)
+                : parsedMessages;
+            LOG.debug('Command', `[read_chat] cli-like parsed provider=${adapter.cliType} target=${String(args?.targetSessionId || '')} adapterStatus=${String(adapterStatus.status || '')} parsedStatus=${String(parsedRecord.status || '')} parsedMsgCount=${parsedRecord.messages.length} returnedMsgCount=${returnedMessages.length}`);
             return buildReadChatCommandResult({
-                messages: parsedRecord.messages,
+                messages: returnedMessages,
                 status: returnedStatus,
                 activeModal,
                 debugReadChat: {
@@ -774,7 +819,7 @@ export async function handleReadChat(h: CommandHelpers, args: any): Promise<Comm
                     returnedStatus: String(returnedStatus || ''),
                     shouldPreferAdapterMessages: false,
                     parsedMsgCount: parsedRecord.messages.length,
-                    returnedMsgCount: parsedRecord.messages.length,
+                    returnedMsgCount: returnedMessages.length,
                 },
                 ...(title ? { title } : {}),
                 ...(providerSessionId ? { providerSessionId } : {}),

package/src/commands/cli-manager.ts

@@ -132,6 +132,12 @@ type CliAdapterWithExtraArgs = CliAdapter & {
     extraArgs?: string[];
 };
 
+type CliStartOptions = {
+    resumeSessionId?: string;
+    settingsOverride?: Record<string, any>;
+    extraEnv?: Record<string, string>;
+};
+
 function isUuid(value: string): boolean {
     return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value);
 }
@@ -365,6 +371,7 @@ export class DaemonCliManager {
         runtimeId: string,
         providerSessionId?: string,
         attachExisting = false,
+        extraEnv?: Record<string, string>,
     ): CliAdapter {
  // cliType normalize (Resolve alias)
         const normalizedType = this.providerLoader.resolveAlias(cliType);
@@ -382,7 +389,7 @@ export class DaemonCliManager {
                 providerSessionId,
                 attachExisting,
             );
-            return new ProviderCliAdapter(resolvedProvider as CliProviderModule, workingDir, cliArgs, transportFactory);
+            return new ProviderCliAdapter(resolvedProvider as CliProviderModule, workingDir, cliArgs, extraEnv || {}, transportFactory);
         }
 
         throw new Error(`No CLI provider found for '${cliType}'. Create a provider.js in providers/cli/${cliType}/`);
@@ -425,6 +432,7 @@ export class DaemonCliManager {
         options?: {
             providerSessionId?: string;
             launchMode?: CliLaunchMode;
+            extraEnv?: Record<string, string>;
             onProviderSessionResolved?: (info: {
                 instanceId: string;
                 providerType: string;
@@ -480,7 +488,7 @@ export class DaemonCliManager {
         workingDir: string,
         cliArgs?: string[],
         initialModel?: string,
-        options?: { resumeSessionId?: string, settingsOverride?: Record<string, any> },
+        options?: CliStartOptions,
     ): Promise<{ runtimeSessionId: string; providerSessionId?: string }> {
         const trimmed = (workingDir || '').trim();
         if (!trimmed) throw new Error('working directory required');
@@ -629,6 +637,7 @@ export class DaemonCliManager {
                 {
                     providerSessionId: sessionBinding.providerSessionId,
                     launchMode: sessionBinding.launchMode,
+                    extraEnv: options?.extraEnv,
                     onProviderSessionResolved: ({ providerSessionId, providerName, providerType, workspace }) => {
                         this.persistRecentActivity({
                             kind: 'cli',
@@ -651,6 +660,7 @@ export class DaemonCliManager {
                 key,
                 sessionBinding.providerSessionId,
                 false,
+                options?.extraEnv,
             );
             try {
                 await adapter.spawn();
@@ -904,7 +914,7 @@ export class DaemonCliManager {
                     dir,
                     args?.cliArgs,
                     args?.initialModel,
-                    { resumeSessionId: args?.resumeSessionId, settingsOverride: args?.settings },
+                    { resumeSessionId: args?.resumeSessionId, settingsOverride: args?.settings, extraEnv: args?.env },
                 );
 
                 return {

package/src/commands/mesh-coordinator.ts

@@ -1,6 +1,8 @@
-import { existsSync, realpathSync } from 'node:fs'
+import { execFileSync } from 'node:child_process'
+import { existsSync, readdirSync, realpathSync } from 'node:fs'
 import { createRequire } from 'node:module'
-import { dirname, join, resolve } from 'node:path'
+import * as os from 'node:os'
+import { dirname, isAbsolute, join, resolve } from 'node:path'
 import type { ProviderModule, MeshCoordinatorMcpConfigFormat } from '../providers/contracts.js'
 
 export interface MeshCoordinatorMcpServerLaunch {
@@ -32,6 +34,7 @@ export type MeshCoordinatorSetup =
 
 export interface ResolveMeshCoordinatorSetupOptions {
   provider?: ProviderModule | null
+  cliType?: string
   meshId: string
   workspace: string
   adhdevMcpCommand?: string
@@ -41,6 +44,58 @@ export interface ResolveMeshCoordinatorSetupOptions {
 
 const DEFAULT_SERVER_NAME = 'adhdev-mesh'
 const DEFAULT_ADHDEV_MCP_COMMAND = 'adhdev-mcp'
+const HERMES_CLI_TYPE = 'hermes-cli'
+const HERMES_MCP_CONFIG_PATH = '~/.hermes/config.yaml'
+
+function isHermesProvider(provider: ProviderModule | null | undefined, cliType?: string): boolean {
+  const type = cliType?.trim() || provider?.type?.trim() || ''
+  return type === HERMES_CLI_TYPE
+}
+
+function resolveHermesMeshCoordinatorSetup(options: ResolveMeshCoordinatorSetupOptions): MeshCoordinatorSetup {
+  const mcpServer = resolveAdhdevMcpServerLaunch({
+    meshId: options.meshId,
+    nodeExecutable: options.nodeExecutable,
+    adhdevMcpEntryPath: options.adhdevMcpEntryPath,
+  })
+  if (!mcpServer) {
+    return {
+      kind: 'unsupported',
+      reason: 'Could not resolve the ADHDev MCP server entrypoint and a Node runtime with WebSocket support for daemon IPC mode',
+    }
+  }
+  const configPath = resolveMcpConfigPath(HERMES_MCP_CONFIG_PATH, options.workspace)
+  if (!configPath.trim()) {
+    return createHermesManualMeshCoordinatorSetup(options.meshId, options.workspace)
+  }
+  return {
+    kind: 'auto_import',
+    serverName: DEFAULT_SERVER_NAME,
+    configPath,
+    configFormat: 'hermes_config_yaml',
+    mcpServer,
+  }
+}
+
+export function createHermesManualMeshCoordinatorSetup(meshId: string, workspace: string): MeshCoordinatorSetup {
+  return {
+    kind: 'manual',
+    serverName: DEFAULT_SERVER_NAME,
+    configFormat: 'hermes_config_yaml',
+    configPathCommand: HERMES_MCP_CONFIG_PATH,
+    requiresRestart: true,
+    instructions: 'Hermes CLI does not auto-import repo-local .mcp.json. Add this MCP server to Hermes config under mcp_servers, then start a fresh Hermes session.',
+    template: renderMeshCoordinatorTemplate(
+      'mcp_servers:\n  {{serverName}}:\n    command: {{adhdevMcpCommand}}\n    args:\n      - --repo-mesh\n      - {{meshId}}\n    enabled: true\n',
+      {
+        meshId,
+        workspace,
+        serverName: DEFAULT_SERVER_NAME,
+        adhdevMcpCommand: DEFAULT_ADHDEV_MCP_COMMAND,
+      },
+    ),
+  }
+}
 
 export function resolveMeshCoordinatorSetup(options: ResolveMeshCoordinatorSetupOptions): MeshCoordinatorSetup {
   const { provider, meshId, workspace } = options
@@ -52,6 +107,10 @@ export function resolveMeshCoordinatorSetup(options: ResolveMeshCoordinatorSetup
     }
   }
 
+  if (isHermesProvider(provider, options.cliType)) {
+    return resolveHermesMeshCoordinatorSetup(options)
+  }
+
   const mcpConfig = config.mcpConfig
   if (!mcpConfig || mcpConfig.mode === 'none') {
     return {
@@ -74,13 +133,13 @@ export function resolveMeshCoordinatorSetup(options: ResolveMeshCoordinatorSetup
     if (!mcpServer) {
       return {
         kind: 'unsupported',
-        reason: 'Could not resolve the ADHDev MCP server entrypoint without relying on a PATH bin shim',
+        reason: 'Could not resolve the ADHDev MCP server entrypoint and a Node runtime with WebSocket support for daemon IPC mode',
       }
     }
     return {
       kind: 'auto_import',
       serverName,
-      configPath: join(workspace, path),
+      configPath: resolveMcpConfigPath(path, workspace),
       configFormat: mcpConfig.format,
       mcpServer,
     }
@@ -118,6 +177,14 @@ function renderMeshCoordinatorTemplate(template: string, values: Record<string,
   return template.replace(/\{\{\s*(meshId|workspace|serverName|adhdevMcpCommand)\s*\}\}/g, (_, key: string) => values[key] || '')
 }
 
+function resolveMcpConfigPath(configPath: string, workspace: string): string {
+  const trimmed = configPath.trim()
+  if (trimmed === '~') return os.homedir()
+  if (trimmed.startsWith('~/')) return join(os.homedir(), trimmed.slice(2))
+  if (isAbsolute(trimmed)) return trimmed
+  return join(workspace, trimmed)
+}
+
 function resolveAdhdevMcpServerLaunch(options: {
   meshId: string
   nodeExecutable?: string
@@ -125,9 +192,85 @@ function resolveAdhdevMcpServerLaunch(options: {
 }): MeshCoordinatorMcpServerLaunch | null {
   const entryPath = resolveAdhdevMcpEntryPath(options.adhdevMcpEntryPath)
   if (!entryPath) return null
+  const nodeExecutable = resolveMcpNodeExecutable(options.nodeExecutable)
+  if (!nodeExecutable) return null
   return {
-    command: options.nodeExecutable?.trim() || process.execPath,
-    args: [entryPath, '--repo-mesh', options.meshId],
+    command: nodeExecutable,
+    args: [entryPath, '--mode', 'ipc', '--repo-mesh', options.meshId],
+  }
+}
+
+function resolveMcpNodeExecutable(explicitExecutable?: string): string | null {
+  const explicit = explicitExecutable?.trim()
+  if (explicit) return explicit
+
+  const candidates: string[] = []
+  const addCandidate = (candidate?: string | null) => {
+    const trimmed = candidate?.trim()
+    if (!trimmed) return
+    const normalized = normalizeExistingPath(trimmed) || trimmed
+    if (!candidates.includes(normalized)) candidates.push(normalized)
+  }
+
+  addCandidate(process.env.ADHDEV_MCP_NODE_EXECUTABLE)
+  addCandidate(process.env.ADHDEV_NODE_EXECUTABLE)
+  addCandidate(process.env.npm_node_execpath)
+  addNodeCandidatesFromPath(process.env.PATH, addCandidate)
+  addNodeCandidatesFromNvm(os.homedir(), addCandidate)
+  addCandidate('/opt/homebrew/bin/node')
+  addCandidate('/usr/local/bin/node')
+  addCandidate('/usr/bin/node')
+  addCandidate(process.execPath)
+
+  for (const candidate of candidates) {
+    if (nodeRuntimeSupportsWebSocket(candidate)) return candidate
+  }
+  return null
+}
+
+function addNodeCandidatesFromPath(pathValue: string | undefined, addCandidate: (candidate?: string | null) => void) {
+  for (const entry of (pathValue || '').split(':')) {
+    const dir = entry.trim()
+    if (!dir) continue
+    addCandidate(join(dir, 'node'))
+  }
+}
+
+function addNodeCandidatesFromNvm(homeDir: string, addCandidate: (candidate?: string | null) => void) {
+  const versionsDir = join(homeDir, '.nvm', 'versions', 'node')
+  try {
+    const versionDirs = readdirSync(versionsDir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .sort(compareNodeVersionNamesDescending)
+    for (const versionDir of versionDirs) {
+      addCandidate(join(versionsDir, versionDir, 'bin', 'node'))
+    }
+  } catch {
+    // nvm is optional; PATH and process.execPath candidates still cover normal installs.
+  }
+}
+
+function compareNodeVersionNamesDescending(a: string, b: string): number {
+  const parse = (value: string) => value.replace(/^v/, '').split('.').map((part) => Number.parseInt(part, 10) || 0)
+  const left = parse(a)
+  const right = parse(b)
+  for (let i = 0; i < Math.max(left.length, right.length); i++) {
+    const diff = (right[i] || 0) - (left[i] || 0)
+    if (diff !== 0) return diff
+  }
+  return b.localeCompare(a)
+}
+
+function nodeRuntimeSupportsWebSocket(nodeExecutable: string): boolean {
+  try {
+    execFileSync(nodeExecutable, ['-e', "process.exit(typeof WebSocket === 'function' ? 0 : 42)"], {
+      stdio: 'ignore',
+      timeout: 3000,
+    })
+    return true
+  } catch {
+    return false
   }
 }