dsh-mesh-node 0.0.0-stage → 0.0.2

package/src/tools/index.js

@@ -0,0 +1,122 @@
+import { buildCore } from './core.js'
+import { buildFs } from './fs.js'
+import { buildGit } from './git.js'
+import { buildShell } from './shell.js'
+import { buildTasks } from './tasks.js'
+import { buildChannel } from './channel.js'
+import { buildHost } from './host.js'
+import { buildRepair } from './repair.js'
+import { buildRepairFs } from './repair-fs.js'
+import { buildCluster } from './cluster.js'
+import { buildDelegate } from './delegate.js'
+import { buildSessionHistory } from './session-history.js'
+import { buildConfigPatch } from './config-patch.js'
+import { buildAlerts } from './alerts.js'
+import { buildControl } from './control.js'
+import { buildControlApps } from './control-apps.js'
+import { buildControlPath } from './control-path.js'
+import { denied, internal, notFound } from '../core/result.js'
+import { short } from '../core/util.js'
+
+/** Every tool spec for this node, built against the current context. */
+export function buildAll(ctx) {
+  return [
+    ...buildCore(ctx),
+    ...buildFs(ctx),
+    ...buildGit(ctx),
+    ...buildShell(ctx),
+    ...buildTasks(ctx),
+    ...buildChannel(ctx),
+    ...buildHost(ctx),
+    ...buildRepair(ctx),
+    ...buildRepairFs(ctx),
+    ...buildCluster(ctx),
+    ...buildDelegate(ctx),
+    ...buildSessionHistory(ctx),
+    ...buildConfigPatch(ctx),
+    ...buildAlerts(ctx),
+    ...buildControl(ctx),
+    ...buildControlApps(ctx),
+    ...buildControlPath()
+  ]
+}
+
+export function toolNames(ctx) {
+  return buildAll(ctx).map((spec) => spec.name)
+}
+
+/** Deny-by-default ACL: `deny` wins over `allow`. */
+export function isAllowed(config, name) {
+  const acl = config?.acl || {}
+  if ((acl.deny || []).includes(name)) return false
+  return (acl.allow || []).includes(name)
+}
+
+/**
+ * Narrow the node-wide config by a per-token ACL (from secrets.json).
+ * `allow` = intersection with the node-wide list (a peer can never gain a tool);
+ * `deny` = union (a peer-specific denial always wins); `fsRoots` may only narrow.
+ */
+export function applyPeerAcl(config, peerAcl) {
+  if (!peerAcl) return config
+  const base = config?.acl || {}
+  const baseAllow = base.allow || []
+  const peerAllow = Array.isArray(peerAcl.allow) ? peerAcl.allow : null
+  const allow = peerAllow ? baseAllow.filter((name) => peerAllow.includes(name)) : baseAllow
+  const deny = [...new Set([...(base.deny || []), ...((peerAcl.deny || []))])]
+  const fsRoots = Array.isArray(peerAcl.fsRoots) && peerAcl.fsRoots.length > 0 ? peerAcl.fsRoots : base.fsRoots
+  return { ...config, acl: { ...base, allow, deny, fsRoots } }
+}
+
+/**
+ * The single execution path for every tool call, whether it comes from a peer over MCP
+ * or from the local job queue. Applies ACL, audits the attempt, and converts thrown
+ * errors into structured E_INTERNAL results so a peer always gets an answer.
+ */
+export async function dispatch(ctx, name, args = {}, { signal, jobId } = {}) {
+  const specs = buildAll(ctx)
+  const spec = specs.find((s) => s.name === name)
+  if (!spec) return notFound(`unknown tool: ${name}`)
+  const config = ctx.getConfig()
+  if (!isAllowed(config, name)) {
+    await ctx.audit({ peer: ctx.peerId, tool: name, ok: false, code: 'E_DENIED', jobId, args: Object.keys(args || {}) })
+    return denied(`${name} is not allowed by local ACL`, { allow: config.acl?.allow || [] })
+  }
+  const started = Date.now()
+  try {
+    const result = await spec.handler(args, { signal, jobId, peerId: ctx.peerId })
+    await ctx.audit({
+      peer: ctx.peerId,
+      tool: name,
+      ok: !result?.isError,
+      code: result?.isError ? 'E_TOOL' : undefined,
+      ms: Date.now() - started,
+      jobId,
+      args: Object.keys(args || {})
+    })
+    return result
+  } catch (error) {
+    await ctx.audit({
+      peer: ctx.peerId,
+      tool: name,
+      ok: false,
+      code: 'E_INTERNAL',
+      ms: Date.now() - started,
+      jobId,
+      message: short(error?.message || error)
+    })
+    return internal(`${name} failed: ${short(error?.message || error)}`)
+  }
+}
+
+/** Register every tool on an McpServer; each callback funnels through dispatch(). */
+export function registerTools(server, ctx) {
+  for (const spec of buildAll(ctx)) {
+    server.registerTool(
+      spec.name,
+      { title: spec.title, description: spec.description, inputSchema: spec.inputSchema },
+      async (args, extra) => dispatch(ctx, spec.name, args, { signal: extra?.signal })
+    )
+  }
+  return server
+}

package/src/tools/repair-fs.js

@@ -0,0 +1,130 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { z } from 'zod'
+import { assertInside } from '../core/repair.js'
+import { fail, ok } from '../core/result.js'
+import {
+  backupRoot,
+  repairGate,
+  requireProfile,
+  resolveProfileTarget,
+  sha256,
+  timestamp
+} from './repair.js'
+
+const confirmSchema = z
+  .boolean()
+  .optional()
+  .describe('Must be true. Repair operations rewrite a DSH profile on this machine.')
+
+const instanceSchema = z
+  .string()
+  .optional()
+  .describe('Host instance id whose profile is targeted (default: first enabled instance).')
+
+/**
+ * M7 step 3 (fs_write): write ONE file inside a DSH profile, with a backup, a
+ * sha256 verification of the written bytes, and a rollback on any failure.
+ * Lives in its own module so the repair toolkit stays readable (and under the
+ * 400-line-per-file rule); the shared helpers come from ./repair.js.
+ */
+export function buildRepairFs(ctx) {
+  return [
+    {
+      name: 'fs_write',
+      title: 'Write one UTF-8 file inside a DSH profile (backup + verify + rollback)',
+      description:
+        'Writes one file inside the target DSH profile. The old content is copied to the backup dir, the new content is re-read and verified by sha256, and any failure rolls the file back. Confined to `hosts[].profileDir` (relative paths, or absolute paths inside that profile) — use it to repair a config/patch/plugin file on an instance you cannot reach otherwise. Requires config.repair.enabled=true and confirm:true.',
+      inputSchema: z.object({
+        path: z
+          .string()
+          .describe('Target file: relative to the profile root (forward slashes) or absolute inside it. Parent dirs are created when missing.'),
+        content: z.string().describe('Full new UTF-8 file content.'),
+        instance: instanceSchema,
+        profileDir: z.string().optional().describe('Explicit profile dir; must equal one of hosts[].profileDir.'),
+        createDirs: z.boolean().optional().describe('Create missing parent directories (default true).'),
+        confirm: confirmSchema
+      }),
+      handler: async (args) => {
+        const config = ctx.getConfig()
+        const gate = repairGate(config)
+        if (gate) return gate
+        if (args?.confirm !== true) {
+          return fail('E_INVALID_ARG', 'pass confirm:true to write a file inside a DSH profile')
+        }
+        const repair = config.repair || {}
+        const maxFileBytes = repair.maxFileBytes ?? 262144
+        const raw = String(args?.path || '').trim()
+        if (!raw) return fail('E_INVALID_ARG', 'path is required')
+        const content = args?.content
+        if (typeof content !== 'string') return fail('E_INVALID_ARG', 'content must be a string')
+        const bytes = Buffer.byteLength(content, 'utf8')
+        if (bytes > maxFileBytes) {
+          return fail('E_INVALID_ARG', `content is ${bytes} bytes > limit ${maxFileBytes}`)
+        }
+
+        let profileDir
+        let instanceId = ''
+        try {
+          const target = resolveProfileTarget(config, args)
+          profileDir = target.profileDir
+          instanceId = target.instanceId
+          requireProfile(profileDir)
+        } catch (error) {
+          return fail(error.code || 'E_INVALID_ARG', error.message)
+        }
+
+        let absolute
+        try {
+          const normalized = raw.replace(/\\/g, '/')
+          absolute =
+            /^[a-z]:/i.test(normalized) || normalized.startsWith('/')
+              ? assertInside(profileDir, normalized)
+              : assertInside(profileDir, join(profileDir, ...normalized.split('/').filter((part) => part.length > 0)))
+        } catch (error) {
+          return fail(error.code || 'E_INVALID_ARG', error.message)
+        }
+
+        const existed = existsSync(absolute)
+        const backupDir = backupRoot(config, ctx.home)
+        let backup = null
+        let previous = null
+        if (existed) {
+          previous = readFileSync(absolute)
+          backup = join(backupDir, `fs-${timestamp()}-${absolute.split(/[\\/]/).pop().replace(/[^\w.-]/g, '_')}`)
+          mkdirSync(backupDir, { recursive: true })
+          writeFileSync(backup, previous)
+        }
+        try {
+          if (args?.createDirs !== false) mkdirSync(dirname(absolute), { recursive: true })
+          writeFileSync(absolute, content, 'utf8')
+          const written = readFileSync(absolute)
+          const expected = sha256(Buffer.from(content, 'utf8'))
+          if (sha256(written) !== expected) throw new Error('sha256 mismatch after write')
+          return ok({
+            path: absolute,
+            instance: instanceId || undefined,
+            bytes,
+            sha256: expected,
+            created: !existed,
+            verified: true,
+            backup
+          })
+        } catch (error) {
+          // rollback: restore the previous bytes (or remove the file we just created)
+          try {
+            if (existed && previous !== null) writeFileSync(absolute, previous)
+            else rmSync(absolute, { force: true })
+          } catch {
+            /* best effort */
+          }
+          return fail('E_WRITE_FAILED', `fs_write failed and was rolled back: ${error.message}`, {
+            retryable: false,
+            path: absolute,
+            backup
+          })
+        }
+      }
+    }
+  ]
+}

package/src/tools/repair.js

@@ -0,0 +1,317 @@
+import { execFile } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { z } from 'zod'
+import { hostInstances, resolveHostInstance } from '../core/host-agent.js'
+import {
+  applyPatchInsert,
+  assertInside,
+  normalizePluginFiles,
+  PLUGIN_NAME_RE,
+  pluginRoot,
+  repairError
+} from '../core/repair.js'
+import { fail, ok } from '../core/result.js'
+import { validateRestartCommand } from '../core/restart-policy.js'
+
+const confirmSchema = z
+  .boolean()
+  .optional()
+  .describe('Must be true. Repair operations rewrite a DSH profile on this machine.')
+
+const instanceSchema = z
+  .string()
+  .optional()
+  .describe('Host instance id whose profile is targeted (default: first enabled instance).')
+
+/**
+ * M7 step 3: the "repair another DSH" toolkit.
+ *
+ * These tools run on the machine that owns the DSH instance — a peer calls them
+ * over MCP, so a live instance on the other machine can fix this one. Double
+ * gate: `config.repair.enabled === true` AND an explicit ACL allow entry (none
+ * of these tools is in DEFAULT_ALLOW). Every write leaves a backup and is
+ * audited by the dispatcher.
+ */
+
+export function repairGate(config) {
+  if (config?.repair?.enabled === true) return null
+  return fail(
+    'E_DENIED',
+    'repair tools are disabled on this node (config.repair.enabled=true is required, and the tool must also be allowed in acl.allow)'
+  )
+}
+
+export function backupRoot(config, home) {
+  const configured = config?.repair?.backupDir
+  return configured ? resolve(configured) : join(home, 'backups')
+}
+
+export function timestamp() {
+  return new Date().toISOString().replace(/[-:.TZ]/g, '').slice(0, 14)
+}
+
+/**
+ * Resolve the profile a repair tool may touch: an explicit `profileDir` must be
+ * one of the configured `hosts[].profileDir` values, otherwise the instance id
+ * picks the profile. This is the single place the "which profile" decision is
+ * made, shared by plugin_install and fs_write.
+ */
+export function resolveProfileTarget(config, args) {
+  const allowedProfiles = hostInstances(config)
+    .map((entry) => entry.profileDir)
+    .filter(Boolean)
+    .map((dir) => resolve(dir))
+  if (args?.profileDir) {
+    const profileDir = resolve(String(args.profileDir))
+    if (!allowedProfiles.includes(profileDir)) {
+      throw repairError(
+        'E_INVALID_ARG',
+        `profileDir is not one of the configured hosts[].profileDir values: configured=${allowedProfiles.join(', ') || '(none)'}`
+      )
+    }
+    return { profileDir, instanceId: '' }
+  }
+  const entry = resolveHostInstance(config, args?.instance)
+  if (!entry.profileDir) {
+    throw repairError('E_INVALID_ARG', `host instance "${entry.id}" has no profileDir configured`)
+  }
+  return { profileDir: resolve(entry.profileDir), instanceId: entry.id }
+}
+
+/** sha256 of a string or buffer, used to verify a write actually landed. */
+export function sha256(value) {
+  return createHash('sha256').update(value).digest('hex')
+}
+
+export function requireProfile(profileDir) {
+  if (!existsSync(join(profileDir, 'package.json'))) {
+    throw repairError('E_PROFILE_NOT_FOUND', `not a DSH profile (no package.json): ${profileDir}`)
+  }
+}
+
+function tail(text, limit = 8000) {
+  const value = String(text || '')
+  return value.length > limit ? `…${value.slice(-limit)}` : value
+}
+
+function runCommand(command, { timeoutMs, cwd }) {
+  return new Promise((resolvePromise) => {
+    const started = Date.now()
+    execFile(
+      command,
+      { shell: true, timeout: timeoutMs, windowsHide: true, maxBuffer: 4 * 1024 * 1024, cwd },
+      (error, stdout, stderr) => {
+        const exitCode = error ? (typeof error.code === 'number' ? error.code : null) : 0
+        resolvePromise({
+          code: exitCode,
+          signal: error?.signal || null,
+          stdout: tail(stdout),
+          stderr: tail(stderr),
+          error: error ? String(error.message || error) : null,
+          ms: Date.now() - started
+        })
+      }
+    )
+  })
+}
+
+export function buildRepair(ctx) {
+  return [
+    {
+      name: 'repair_status',
+      title: 'Show repair toolkit state on this node',
+      description:
+        'Read-only: whether repair tools are enabled, the file/size limits, which restart scripts are configured, and which DSH profile each host instance maps to. Everything the remote repairer needs before touching anything.',
+      inputSchema: z.object({}),
+      handler: async () => {
+        const config = ctx.getConfig()
+        const repair = config.repair || {}
+        return ok({
+          enabled: repair.enabled === true,
+          maxFiles: repair.maxFiles,
+          maxFileBytes: repair.maxFileBytes,
+          timeoutMs: repair.timeoutMs,
+          backupDir: backupRoot(config, ctx.home),
+          restartScripts: Object.keys(repair.restartScripts || {}),
+          instances: hostInstances(config).map((entry) => ({
+            id: entry.id,
+            label: entry.label || entry.id,
+            profileDir: entry.profileDir || ''
+          }))
+        })
+      }
+    },
+    {
+      name: 'plugin_install',
+      title: 'Install a DSH plugin into a profile (also patches cordis.patch.yml)',
+      description:
+        'Writes plugin files into `<profileDir>/node_modules/<name>/`, backs up any existing copy and the profile patch, then adds a `- insert:` block when the plugin is not wired yet. Use it to repair or extend a DSH instance that is otherwise unreachable — no npm, no git, no shell needed. Requires config.repair.enabled=true and confirm:true.',
+      inputSchema: z.object({
+        name: z.string().describe('Plugin package name, e.g. dsh-mesh-host'),
+        files: z
+          .array(
+            z.object({
+              path: z.string().describe('Relative path inside the package, forward slashes, e.g. lib/index.js'),
+              content: z.string().describe('Full file text (UTF-8)')
+            })
+          )
+          .describe('Every file of the plugin package'),
+        instance: instanceSchema,
+        profileDir: z
+          .string()
+          .optional()
+          .describe('Override profile dir; must equal one of the configured hosts[].profileDir values'),
+        patch: z.boolean().optional().describe('Set false to skip wiring cordis.patch.yml (default true)'),
+        confirm: confirmSchema
+      }),
+      handler: async (args) => {
+        const config = ctx.getConfig()
+        const gate = repairGate(config)
+        if (gate) return gate
+        if (args?.confirm !== true) {
+          return fail('E_INVALID_ARG', 'pass confirm:true to rewrite a DSH profile')
+        }
+        const name = String(args?.name || '')
+        if (!PLUGIN_NAME_RE.test(name)) {
+          return fail('E_INVALID_ARG', `invalid plugin name: ${name || '(empty)'}`)
+        }
+        const repair = config.repair || {}
+        let files
+        try {
+          files = normalizePluginFiles(args?.files, {
+            maxFiles: repair.maxFiles ?? 20,
+            maxFileBytes: repair.maxFileBytes ?? 262144
+          })
+        } catch (error) {
+          return fail(error.code || 'E_INVALID_ARG', error.message)
+        }
+
+        let profileDir
+        let instanceId = ''
+        try {
+          const target = resolveProfileTarget(config, args)
+          profileDir = target.profileDir
+          instanceId = target.instanceId
+          requireProfile(profileDir)
+        } catch (error) {
+          return fail(error.code || 'E_INVALID_ARG', error.message)
+        }
+
+        let packageDir
+        try {
+          packageDir = assertInside(profileDir, pluginRoot(profileDir, name))
+        } catch (error) {
+          return fail(error.code || 'E_INVALID_ARG', error.message)
+        }
+
+        const backups = []
+        const backupDir = backupRoot(config, ctx.home)
+        let packageBackup = null
+        if (existsSync(packageDir)) {
+          packageBackup = join(backupDir, `plugin-${name.replace(/[@/]/g, '_')}-${timestamp()}`)
+          cpSync(packageDir, packageBackup, { recursive: true })
+          backups.push(packageBackup)
+        }
+        let patchBackup = null
+        let patchPath = null
+        let patchCurrent = ''
+        try {
+          for (const file of files) {
+            const absolute = join(packageDir, file.abs)
+            mkdirSync(dirname(absolute), { recursive: true })
+            writeFileSync(absolute, file.content, 'utf8')
+          }
+
+          let patchInfo = null
+          if (args?.patch !== false) {
+            patchPath = join(profileDir, 'cordis.patch.yml')
+            patchCurrent = existsSync(patchPath) ? readFileSync(patchPath, 'utf8') : ''
+            const applied = applyPatchInsert(patchCurrent, name)
+            if (applied.changed) {
+              if (applied.backup) {
+                patchBackup = `${patchPath}.bak-mesh-${timestamp()}`
+                writeFileSync(patchBackup, patchCurrent, 'utf8')
+                backups.push(patchBackup)
+              }
+              writeFileSync(patchPath, applied.text, 'utf8')
+            }
+            patchInfo = { path: patchPath, changed: applied.changed }
+          }
+
+          return ok({
+            name,
+            instance: instanceId || undefined,
+            profileDir,
+            packageDir,
+            files: files.map((file) => ({ path: file.rel, bytes: file.bytes })),
+            patch: patchInfo,
+            backups,
+            restartHint: 'restart that DSH instance to load the plugin'
+          })
+        } catch (error) {
+          // rollback: a half-written plugin is worse than no plugin
+          if (packageBackup) {
+            rmSync(packageDir, { recursive: true, force: true })
+            cpSync(packageBackup, packageDir, { recursive: true })
+          } else {
+            rmSync(packageDir, { recursive: true, force: true })
+          }
+          if (patchPath && patchBackup) writeFileSync(patchPath, patchCurrent, 'utf8')
+          return fail('E_WRITE_FAILED', `plugin_install failed and was rolled back: ${error.message}`, { backups })
+        }
+      }
+    },
+    {
+      name: 'service_restart',
+      title: 'Run a preset restart script for a DSH instance',
+      description:
+        'Runs one command from config.repair.restartScripts by name (the map is the allowlist — arbitrary commands are refused). Use it only after a verified change, and only when a restart is really required. Returns exit code, stdout/stderr tails and duration. Requires config.repair.enabled=true and confirm:true.',
+      inputSchema: z.object({
+        script: z.string().describe('Name of the script from config.repair.restartScripts'),
+        confirm: confirmSchema
+      }),
+      handler: async (args) => {
+        const config = ctx.getConfig()
+        const gate = repairGate(config)
+        if (gate) return gate
+        if (args?.confirm !== true) {
+          return fail('E_INVALID_ARG', 'pass confirm:true to run a restart script')
+        }
+        const scripts = config.repair?.restartScripts || {}
+        const names = Object.keys(scripts)
+        const script = String(args?.script || '')
+        if (!script || !Object.prototype.hasOwnProperty.call(scripts, script)) {
+          return fail('E_NOT_FOUND', `unknown restart script "${script}"; configured: ${names.join(', ') || '(none)'}`, {
+            scripts: names
+          })
+        }
+        const command = String(scripts[script])
+        if (!command.trim()) return fail('E_INVALID_ARG', `restart script "${script}" is empty`)
+        // P2 运行期白名单：手改 config 也塞不进任意命令
+        const policy = validateRestartCommand(command)
+        if (!policy.ok) {
+          return fail('E_DENIED', `restart script "${script}" refused by runtime allowlist: ${policy.reason}`, { script, command: command.slice(0, 160) })
+        }
+        const run = await runCommand(command, {
+          timeoutMs: config.repair?.timeoutMs ?? 120000,
+          cwd: config.repair?.cwd || undefined
+        })
+        if (run.code !== 0) {
+          return fail('E_SCRIPT_FAILED', `restart script "${script}" exited with ${run.code ?? run.signal}`, {
+            retryable: false,
+            script,
+            command,
+            exitCode: run.code,
+            signal: run.signal,
+            stdout: run.stdout,
+            stderr: run.stderr,
+            ms: run.ms
+          })
+        }
+        return ok({ script, command, code: run.code, stdout: run.stdout, stderr: run.stderr, ms: run.ms })
+      }
+    },
+  ]
+}

package/src/tools/session-history.js

@@ -0,0 +1,60 @@
+// @generated 2026-10-27 P1：session_history（远程只读导出某条 DSH 会话正文）
+// [why] 以前只有两条路：① 委托对端 AI 导出（起会话、花 token、慢）；② 人跑到对端机器上用
+//       my-skills 的 dsh-sessions.mjs。现在 mesh server 在目标机本地跑 scripts/session-history.mjs
+//       解 zstd 会话日志 → 跨机一条命令看正文。
+import { spawnSync } from 'node:child_process'
+import { dirname, join, resolve } from 'node:path'
+import { homedir } from 'node:os'
+import { fileURLToPath } from 'node:url'
+import { z } from 'zod'
+import { fail, ok } from '../core/result.js'
+
+const SCRIPT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', 'scripts', 'session-history.mjs')
+
+function homeOf(instance) {
+  const id = String(instance || 'dsh0').trim()
+  const match = /^dsh(\d+)$/.exec(id)
+  return join(homedir(), `.dsh${match ? Number(match[1]) : 0}`)
+}
+
+export function buildSessionHistory() {
+  return [
+    {
+      name: 'session_history',
+      title: 'Read one DSH session transcript (read-only)',
+      description:
+        'Read the last N messages of one session log on THIS machine (decompresses the append-only zstd session log, no model round-trip). Use peer-inspect/host_sessions to find the sessionId first. Read-only; returns role/text/time/seq + title. Requires the node ACL to allow `session_history`.',
+      inputSchema: z.object({
+        sessionId: z.string().describe('DSH session id, e.g. session-abf88d8c-8798-43c7-a7d7-f6266bac075a'),
+        instance: z.string().optional().describe('Local DSH instance whose session store to read (default dsh0 → ~/.dsh0).'),
+        limit: z.number().int().min(1).max(200).optional().describe('How many trailing messages (default 40).')
+      }),
+      handler: async ({ sessionId, instance, limit }) => {
+        const id = String(sessionId || '').trim()
+        if (!/^[A-Za-z0-9._-]{8,120}$/.test(id)) return fail('E_INVALID_ARG', 'sessionId looks invalid', { sessionId: id })
+        const home = homeOf(instance)
+        const lines = Math.min(Math.max(Number(limit) || 40, 1), 200)
+        const run = spawnSync(process.execPath, [SCRIPT, '--home', home, '--session', id, '--limit', String(lines)], {
+          encoding: 'utf8',
+          windowsHide: true,
+          timeout: 60000
+        })
+        const stdout = (run.stdout || '').trim()
+        if (!stdout) {
+          return fail('E_HISTORY', `session-history.mjs produced no output (exit ${run.status})`, {
+            stderr: (run.stderr || '').slice(-400),
+            sessionId: id,
+            home
+          })
+        }
+        try {
+          const parsed = JSON.parse(stdout)
+          if (parsed.ok !== true) return fail(parsed.code || 'E_HISTORY', parsed.message || 'session history failed', parsed)
+          return ok(parsed)
+        } catch (error) {
+          return fail('E_HISTORY', `cannot parse session-history output: ${error?.message || error}`, { sample: stdout.slice(0, 300) })
+        }
+      }
+    }
+  ]
+}