@adhdev/daemon-core 0.9.82-rc.43 → 0.9.82-rc.430

package/src/commands/mesh-coordinator.ts

@@ -1,10 +1,14 @@
-import { execFileSync } from 'node:child_process'
-import { createHash } from 'node:crypto'
-import { existsSync, readdirSync, realpathSync } from 'node:fs'
-import { createRequire } from 'node:module'
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import * as os from 'node:os'
-import { dirname, isAbsolute, join, resolve } from 'node:path'
-import type { ProviderModule, MeshCoordinatorMcpConfigFormat } from '../providers/contracts.js'
+import { DEFAULT_SESSION_HOST_COLS, DEFAULT_SESSION_HOST_ROWS } from '@adhdev/session-host-core'
+import { basename, isAbsolute, join, resolve } from 'node:path'
+import { LOG } from '../logging/logger.js'
+import { shortHash } from '../system/hash.js'
+import type {
+  MeshCoordinatorMcpConfigFormat,
+  MeshCoordinatorSystemPromptInjection,
+  ProviderModule,
+} from '../providers/contracts.js'
 
 export interface MeshCoordinatorMcpServerLaunch {
   command: string
@@ -36,6 +40,7 @@ export type MeshCoordinatorSetup =
       command: string
       requiresRestart: boolean
       instructions: string
+      mcpServer: MeshCoordinatorMcpServerLaunch
     }
   | {
       kind: 'unsupported'
@@ -55,7 +60,7 @@ export interface ResolveMeshCoordinatorSetupOptions {
 }
 
 const DEFAULT_SERVER_NAME = 'adhdev-mesh'
-const DEFAULT_ADHDEV_MCP_COMMAND = 'adhdev-mcp'
+const DEFAULT_ADHDEV_MCP_COMMAND = 'adhdev'
 const HERMES_CLI_TYPE = 'hermes-cli'
 const HERMES_MCP_CONFIG_PATH = '~/.hermes/config.yaml'
 
@@ -67,8 +72,9 @@ function isHermesProvider(provider: ProviderModule | null | undefined, cliType?:
 function resolveHermesMeshCoordinatorSetup(options: ResolveMeshCoordinatorSetupOptions): MeshCoordinatorSetup {
   const mcpServer = resolveAdhdevMcpServerLaunch({
     meshId: options.meshId,
-    nodeExecutable: options.nodeExecutable,
+    adhdevMcpCommand: options.adhdevMcpCommand,
     adhdevMcpEntryPath: options.adhdevMcpEntryPath,
+    nodeExecutable: options.nodeExecutable,
     adhdevMcpTransport: options.adhdevMcpTransport,
     adhdevMcpPort: options.adhdevMcpPort,
   })
@@ -100,7 +106,7 @@ export function createHermesManualMeshCoordinatorSetup(meshId: string, workspace
     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',
+      'mcp_servers:\n  {{serverName}}:\n    command: {{adhdevMcpCommand}}\n    args:\n      - mcp\n      - --mode\n      - ipc\n      - --repo-mesh\n      - {{meshId}}\n    enabled: true\n',
       {
         meshId,
         workspace,
@@ -141,8 +147,9 @@ export function resolveMeshCoordinatorSetup(options: ResolveMeshCoordinatorSetup
     }
     const mcpServer = resolveAdhdevMcpServerLaunch({
       meshId,
-      nodeExecutable: options.nodeExecutable,
+      adhdevMcpCommand: options.adhdevMcpCommand,
       adhdevMcpEntryPath: options.adhdevMcpEntryPath,
+      nodeExecutable: options.nodeExecutable,
       adhdevMcpTransport: options.adhdevMcpTransport,
       adhdevMcpPort: options.adhdevMcpPort,
     })
@@ -167,22 +174,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 {
@@ -203,12 +229,19 @@ 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 {
   const key = `${meshId || 'mesh'}\n${resolve(workspace || os.tmpdir())}`
-  const hash = createHash('sha256').update(key).digest('hex').slice(0, 16)
+  const hash = shortHash(key)
   return join(os.tmpdir(), `adhdev-hermes-mesh-coordinator-${hash}`)
 }
 
@@ -222,25 +255,53 @@ function resolveMcpConfigPath(configPath: string, workspace: string): string {
 
 function resolveAdhdevMcpServerLaunch(options: {
   meshId: string
-  nodeExecutable?: string
+  adhdevMcpCommand?: string
   adhdevMcpEntryPath?: string
+  nodeExecutable?: string
   adhdevMcpTransport?: 'local' | 'ipc'
   adhdevMcpPort?: number
 }): MeshCoordinatorMcpServerLaunch | null {
-  const entryPath = resolveAdhdevMcpEntryPath(options.adhdevMcpEntryPath)
-  if (!entryPath) return null
-  const nodeExecutable = resolveMcpNodeExecutable(options.nodeExecutable)
-  if (!nodeExecutable) return 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 = [entryPath, '--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 {
-    command: nodeExecutable,
+    command,
     args,
   }
 }
 
+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()
@@ -255,127 +316,276 @@ function resolveMcpPort(explicitPort?: number): number | undefined {
   return Number.isInteger(parsed) && parsed > 0 ? parsed : undefined
 }
 
-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)
-  }
+/**
+ * Apply a provider's declared system-prompt injection rule, mutating `cliArgs`
+ * and `launchEnv` in place and writing any required workspace context file.
+ *
+ * Replaces the previous hard-coded `if (cliType === 'claude-cli') ... else if
+ * (cliType === 'hermes-cli') ...` branches in router.ts. Adding a new CLI is
+ * now provider.v1.json data, not a router edit.
+ *
+ * Failures are non-fatal: log and continue with whatever was applied so the
+ * coordinator session still launches, just without the prompt for that
+ * provider. A missing/unknown rule means "skip injection" — safe by default
+ * (the previous fallback unconditionally pushed --append-system-prompt onto
+ * every non-Claude CLI, which crashed agy on launch).
+ */
+export interface CoordinatorInjectionEffect {
+  /** Absolute path the daemon wrote a wrapper-blocked file to. Only set for
+   *  context_file injection. R48 schedules a strip after launch so workers
+   *  don't see the wrapper on disk; R47's unregister cleanup uses it as a
+   *  fallback if the timer never fires (process crash, etc). */
+  contextFilePath?: string
+}
 
-  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
+export function applyMeshCoordinatorSystemPromptInjection(
+  systemPrompt: string,
+  injection: MeshCoordinatorSystemPromptInjection | undefined,
+  ctx: { cliArgs: string[]; launchEnv: Record<string, string>; workspace: string; cliType: string },
+): CoordinatorInjectionEffect {
+  if (!systemPrompt || !injection) return {}
+  return applyInjectionRule(systemPrompt, injection, ctx)
 }
 
-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 applyInjectionRule(
+  systemPrompt: string,
+  injection: MeshCoordinatorSystemPromptInjection,
+  ctx: { cliArgs: string[]; launchEnv: Record<string, string>; workspace: string; cliType: string },
+): CoordinatorInjectionEffect {
+  switch (injection.mode) {
+    case 'cli_arg': {
+      if (!injection.flag) return {}
+      ctx.cliArgs.push(injection.flag, systemPrompt)
+      return {}
+    }
+    case 'config_override': {
+      if (!injection.flag || !injection.template) return {}
+      const rendered = injection.template
+        .replace(/\{prompt_json\}/g, JSON.stringify(systemPrompt))
+        .replace(/\{prompt\}/g, systemPrompt)
+      ctx.cliArgs.push(injection.flag, rendered)
+      return {}
+    }
+    case 'env_var': {
+      if (!injection.name) return {}
+      ctx.launchEnv[injection.name] = systemPrompt
+      return {}
+    }
+    case 'context_file': {
+      if (!injection.path) return {}
+      const target = isAbsolute(injection.path)
+        ? injection.path
+        : join(ctx.workspace, injection.path)
+      const wrapper = injection.wrapper && injection.wrapper.includes('{prompt}')
+        ? injection.wrapper
+        : '{prompt}'
+      // Prepend a short managed-by hint inside the wrapper block so a user
+      // opening AGENTS.md / GEMINI.md immediately understands the block is
+      // auto-regenerated by the daemon on every coordinator launch. The hint
+      // sits between the opening sentinel and the prompt body, so the stable
+      // sentinels declared in provider.v1.json are untouched and the
+      // idempotent replace regex above still matches on relaunches.
+      const managedNote =
+        '> _Managed by adhdev mesh coordinator — do not hand-edit this block. ' +
+        'Changes inside the sentinels are overwritten on next coordinator launch._'
+      const promptWithNote = `${managedNote}\n\n${systemPrompt}`
+      const rendered = wrapper.replace(/\{prompt\}/g, promptWithNote)
+      // If the wrapper has a stable opening sentinel, treat everything up to
+      // the matching closing sentinel as our previously-written block and
+      // replace it. Otherwise just append. The marker is the first non-
+      // placeholder line of the wrapper; this keeps relaunches idempotent
+      // without forcing spec authors to declare an explicit marker.
+      const sentinel = wrapper.split('{prompt}')[0].trim()
+      try {
+        if (existsSync(target)) {
+          const existing = readFileSync(target, 'utf-8')
+          if (sentinel && existing.includes(sentinel)) {
+            const closing = wrapper.split('{prompt}')[1]?.trim()
+            const safeOpen = sentinel.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+            const safeClose = closing
+              ? closing.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+              : ''
+            const re = closing
+              ? new RegExp(`${safeOpen}[\\s\\S]*?${safeClose}`, 'g')
+              : new RegExp(`${safeOpen}[\\s\\S]*$`, 'g')
+            writeFileSync(target, existing.replace(re, rendered), 'utf-8')
+          } else {
+            writeFileSync(target, `${existing}\n\n${rendered}`, 'utf-8')
+          }
+        } else {
+          writeFileSync(target, rendered, 'utf-8')
+        }
+        LOG.info('MeshCoordinator', `Wrote coordinator prompt to ${target} (${ctx.cliType})`)
+        return { contextFilePath: target }
+      } catch (error: any) {
+        LOG.warn('MeshCoordinator', `Could not write ${target}: ${error?.message || error}`)
+        return {}
+      }
+    }
+    default:
+      // Unknown future mode — skip silently. Adding the new mode is a spec-
+      // language extension, not a runtime crash.
+      return {}
   }
 }
 
-function addNodeCandidatesFromNvm(homeDir: string, addCandidate: (candidate?: string | null) => void) {
-  const versionsDir = join(homeDir, '.nvm', 'versions', 'node')
+/**
+ * Strip the daemon's wrapper block from a context_file we previously wrote.
+ *
+ * Used in two places:
+ *   1. R48 inject-then-remove: ~5s after spawn, after agy/gemini have read
+ *      the file into their in-memory system-prompt cache. Removing it from
+ *      disk at that point doesn't affect the running coordinator but keeps
+ *      worker sessions (or fresh non-coordinator launches) in the same
+ *      workspace from picking up our wrapper.
+ *   2. R47 unregister fallback: if the timer never fires (process crash,
+ *      kill -9), coordinator-registry.unregisterMeshCoordinator runs the
+ *      same logic when its entry is dropped.
+ *
+ * Idempotent: missing file is fine, missing sentinels are fine, returns
+ * silently. Leaves user-authored content outside the sentinels intact.
+ * Deletes the file outright if our wrapper was the only content.
+ */
+export function stripCoordinatorWrapperFile(filePath: string): void {
+  const OPEN = '<!-- adhdev-mesh-coordinator-prompt -->'
+  const CLOSE = '<!-- /adhdev-mesh-coordinator-prompt -->'
   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'))
+    if (!existsSync(filePath)) return
+    const existing = readFileSync(filePath, 'utf-8')
+    const openIdx = existing.indexOf(OPEN)
+    if (openIdx < 0) return
+    const closeIdx = existing.indexOf(CLOSE, openIdx)
+    if (closeIdx < 0) return
+    const remaining = (existing.slice(0, openIdx) + existing.slice(closeIdx + CLOSE.length))
+      .replace(/^\s*\n+/, '')
+      .replace(/\n+\s*$/, '')
+    if (!remaining.trim()) {
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const fs = require('node:fs')
+        fs.unlinkSync(filePath)
+      } catch { /* best-effort */ }
+    } else {
+      writeFileSync(filePath, remaining + '\n', 'utf-8')
     }
-  } catch {
-    // nvm is optional; PATH and process.execPath candidates still cover normal installs.
-  }
+  } catch { /* best-effort */ }
 }
 
-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)
+export interface PtyExecResult {
+  exitCode: number | null
+  signal: number | null
+  output: string
+  timedOut: boolean
 }
 
-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
-  }
+export interface MeshCoordinatorRegistrationStep {
+  command: string
+  args: string[]
+  required: boolean
+  label: 'remove_existing' | 'register'
 }
 
-function resolveAdhdevMcpEntryPath(explicitPath?: string): string | null {
-  const explicit = explicitPath?.trim()
-  if (explicit) return normalizeExistingPath(explicit) || explicit
-
-  const envPath = process.env.ADHDEV_MCP_SERVER_PATH?.trim()
-  if (envPath) return normalizeExistingPath(envPath) || envPath
-
-  const candidates: string[] = []
-  const addCandidate = (candidate: string) => {
-    if (!candidates.includes(candidate)) candidates.push(candidate)
-  }
-  const addPackagedCandidates = (baseFile?: string) => {
-    if (!baseFile) return
-    const realBase = normalizeExistingPath(baseFile) || baseFile
-    const dir = dirname(realBase)
-    addCandidate(resolve(dir, '../vendor/mcp-server/index.js'))
-    addCandidate(resolve(dir, '../../vendor/mcp-server/index.js'))
-    addCandidate(resolve(dir, '../../../vendor/mcp-server/index.js'))
-    // Source checkout/dev mode does not vendor the MCP server into daemon-standalone.
-    // Resolve the sibling workspace build directly so Repo Mesh auto-import still
-    // writes an absolute Node entrypoint instead of falling back to a PATH bin shim.
-    addCandidate(resolve(dir, '../../mcp-server/dist/index.js'))
-    addCandidate(resolve(dir, '../../../mcp-server/dist/index.js'))
-  }
-
-  addPackagedCandidates(process.argv[1])
-
-  for (const candidate of candidates) {
-    const normalized = normalizeExistingPath(candidate)
-    if (normalized) return normalized
+/**
+ * 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',
   }
-
-  try {
-    const requireBase = process.argv[1] ? (normalizeExistingPath(process.argv[1]) || process.argv[1]) : join(process.cwd(), 'adhdev-daemon.js')
-    const req = createRequire(requireBase)
-    const resolvedModule = req.resolve('@adhdev/mcp-server')
-    return normalizeExistingPath(resolvedModule) || resolvedModule
-  } catch {
-    return null
+  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]
 }
 
-function normalizeExistingPath(filePath: string): string | null {
+/**
+ * Run a one-shot CLI command under a real PTY and collect its output.
+ *
+ * Some provider mcp-registration commands (`agy mcp add`, future bubbletea
+ * TUIs) refuse to run without `/dev/tty`. Daemon-side `execFileSync` runs
+ * pipe-only, so those commands fail with errors like
+ *   `bubbletea: error opening TTY: open /dev/tty: device not configured`
+ * and silently skip the registration, leaving the launched session
+ * without the adhdev-mesh MCP tools — which is exactly what we saw with
+ * agy coordinators.
+ *
+ * Wrapping the registration through node-pty gives the child a real PTY,
+ * so the bubbletea check passes. We close stdin immediately and just
+ * collect stdout until the process exits or the timeout fires.
+ */
+export async function execUnderPty(
+  command: string,
+  args: string[],
+  options: { cwd?: string; env?: Record<string, string>; timeoutMs?: number } = {},
+): Promise<PtyExecResult> {
+  let ptyLib: any
   try {
-    if (!existsSync(filePath)) return null
-    return realpathSync.native(filePath)
-  } catch {
-    return null
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    ptyLib = require('node-pty')
+  } catch (error: any) {
+    throw new Error(`node-pty is not available: ${error?.message || error}`)
   }
+  const env = { ...(options.env ?? (process.env as Record<string, string>)), TERM: 'xterm-256color' }
+  const timeoutMs = typeof options.timeoutMs === 'number' && options.timeoutMs > 0 ? options.timeoutMs : 20_000
+  return new Promise<PtyExecResult>((resolveResult) => {
+    let child: any
+    try {
+      child = ptyLib.spawn(command, args, {
+        name: 'xterm-256color',
+        cols: DEFAULT_SESSION_HOST_COLS,
+        rows: DEFAULT_SESSION_HOST_ROWS,
+        cwd: options.cwd ?? process.cwd(),
+        env,
+      })
+    } catch (error: any) {
+      resolveResult({ exitCode: null, signal: null, output: String(error?.message || error), timedOut: false })
+      return
+    }
+    let buffer = ''
+    let settled = false
+    const timer = setTimeout(() => {
+      if (settled) return
+      settled = true
+      try { child.kill() } catch { /* ignore */ }
+      resolveResult({ exitCode: null, signal: null, output: buffer, timedOut: true })
+    }, timeoutMs)
+    child.onData((chunk: string) => {
+      buffer += chunk
+      if (buffer.length > 256 * 1024) {
+        buffer = buffer.slice(-128 * 1024)
+      }
+    })
+    child.onExit(({ exitCode, signal }: { exitCode: number; signal?: number }) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      resolveResult({ exitCode, signal: signal ?? null, output: buffer, timedOut: false })
+    })
+  })
 }