@goodandready/dsh-kanban 0.1.24 → 0.1.26

package/lib/index.js

@@ -23,12 +23,15 @@ import {
   buildBoard, applyMove, createTask, updateTask, deleteTask, appendNote, setArchived, listArchive,
   taskBody,
   taskLog, taskBySession, exportBoard, importBoard, assignTask, boardMetrics,
+  confirmPermission,
 } from './routes.js'
 import { listImportable, importIssue, refreshTask, searchRepos, createProjectTask } from './import.js'
 import {
   runTask, resolveModel, buildStartMessage,
   runBatch, queueTask, unqueueTask, liveSessions,
+  PERMISSION_RANKS,
 } from './launcher.js'
+import { cleanupTaskWorktree, checkWorktreeDirty } from './worktree.js'
 import { dispatchMove, MOVE_DETAIL, stopWork, STOP_DETAIL } from './commands.js'
 import { createGiteaClient } from './gitea.js'
 import { syncAll, createSyncState, intakeAll, archiveOverdue } from './sync.js'
@@ -37,6 +40,9 @@ import { handleSessionEvent } from './lifecycle.js'
 import { boardMoveDefinition, boardPlanDefinition } from './board-tool.js'
 import { verifySignature, parseEvent } from './webhook.js'
 import { planOutbound, planAssign, createOutbox } from './outbound.js'
+import { computeNextRun } from './cron.js'
+import { PowerInhibitor } from './power.js'
+import { formatProgressDump, parseProgressDump } from './progress-dump.js'
 import { credentialRef } from '@deepseek-ai/dsh-credentials'
 
 export { COLUMN_ORDER, wipLimitField, withDefaults } from './config.js'
@@ -196,17 +202,140 @@ export function apply(ctx, config) {
     return () => { try { store.close() } catch { /* уже закрыта */ } }
   }, 'dsh-kanban: хранилище задач')
 
-  // Признак ожидания по событиям сессии. Задача ищется по идентификатору
-  // сессии; сессий не с доски большинство, и для них здесь ничего не
-  // происходит — это штатный ход, а не пропуск.
+  // Кроссплатформенный ингибитор сна системы во время работы задач
+  const powerInhibitor = new PowerInhibitor({
+    platform: process.platform,
+    pid: process.pid,
+  })
+
+  const syncPower = () => {
+    try {
+      const cfg = getConfig()
+      powerInhibitor.setEnabled(cfg.preventIdleSleep === true)
+      if (store) {
+        const activeCount = store.countInColumn('main', 'in-progress') + store.countInColumn('simple', 'in-progress')
+        powerInhibitor.setReasons(activeCount)
+      }
+    } catch { /* игнорируем */ }
+  }
+  rearmers.add(syncPower)
+  ctx.effect(() => {
+    syncPower()
+    return () => { powerInhibitor.destroy() }
+  }, 'dsh-kanban: ингибитор сна')
+
+  // Инъекция секции доски в системный промпт агента
+  let disposePromptSection
+  const syncPromptSection = () => {
+    if (disposePromptSection) {
+      try { disposePromptSection() } catch {}
+      disposePromptSection = undefined
+    }
+    const cfg = getConfig()
+    const sp = ctx.get('systemPrompt')
+    if (cfg.announceToAgent !== false && sp && typeof sp.section === 'function') {
+      try {
+        disposePromptSection = sp.section({
+          name: 'plugin:dsh-kanban',
+          order: 200,
+          text: 'В системе развернута доска задач dsh-kanban. При работе над задачами вы можете перемещать карточки инструментом board_move и вести чек-лист плана через board_plan. При исчерпании контекста или завершении подэтапа сформируйте блок <<<PROGRESSDUMP\\nЦель: ...\\nПрогресс: ...\\nСледующие шаги: ...\\n>>>PROGRESSDUMP для передачи эстафеты следующей сессии.',
+        })
+      } catch (err) {
+        ctx.logger?.warn?.(`dsh-kanban: не удалось зарегистрировать секцию промпта: ${err?.message}`)
+      }
+    }
+  }
+  rearmers.add(syncPromptSection)
+  ctx.effect(() => {
+    syncPromptSection()
+    return () => { if (disposePromptSection) { try { disposePromptSection() } catch {} } }
+  }, 'dsh-kanban: секция системного промпта')
+
+  // Признак ожидания, исходы сессий и PROGRESSDUMP по событиям сессии.
   ctx.effect(() => ctx.on('session/event', (session, event) => {
     try {
-      handleSessionEvent({ store, sessionId: String(session?.id ?? ''), type: event?.type })
+      const text = event?.content?.[0]?.text ?? event?.text ?? ''
+      handleSessionEvent({
+        store,
+        sessionId: String(session?.id ?? ''),
+        type: event?.type,
+        text,
+        error: event?.error,
+      })
+      syncPower()
     } catch (error) {
       ctx.logger?.warn?.(`dsh-kanban: событие сессии не обработано: ${error?.message}`)
     }
   }), 'dsh-kanban: события сессии')
 
+  // Фоновый шедулер cron для задач
+  ctx.effect(() => {
+    let cronTimer
+    const armCron = () => {
+      clearInterval(cronTimer)
+      cronTimer = undefined
+      if (getConfig().cronEnabled !== true) return
+      cronTimer = setInterval(async () => {
+        try {
+          if (!store) return
+          const now = Date.now()
+          const dueTasks = store.listDueTasks(now)
+          for (const task of dueTasks) {
+            if (task.column === 'in-progress') {
+              const next = computeNextRun(task.cron, now)
+              store.updateTask(task.id, { lastRunAt: now, nextRunAt: next || 0 })
+              continue
+            }
+            if (getConfig().permissionGateEnabled) {
+              const perm = task.permission || 'read-only'
+              const defaultPerm = getConfig().sessionDefaultPermission || 'read-only'
+              if ((PERMISSION_RANKS[perm] ?? 0) > (PERMISSION_RANKS[defaultPerm] ?? 0) && !task.permissionConfirmedAt) {
+                const next = computeNextRun(task.cron, now)
+                store.updateTask(task.id, { lastRunAt: now, nextRunAt: next || 0 })
+                store.addTransition({
+                  taskId: task.id,
+                  fromCol: task.column,
+                  toCol: task.column,
+                  source: 'tool',
+                  detail: 'cron: запуск отклонён (требуется подтверждение повышенных прав)',
+                })
+                continue
+              }
+            }
+            const picked = resolveModel({
+              requested: { model: task.model, provider: task.provider },
+              fallback: ctx.get('agentDefaultModel')?.currentSelection?.(),
+            })
+            if (picked.model) {
+              await runTask({
+                agents: ctx.agents,
+                store,
+                task,
+                config: getConfig(),
+                provider: picked.provider,
+                model: picked.model,
+                mintSessionId: () => SessionId(`kanban-${task.id}-${randomUUID()}`),
+                createMessage: createUserMessage,
+                logger: ctx.logger,
+                workspaceRegistry: ctx.get('workspaceRegistry'),
+                claimAs: 'cron',
+              })
+              syncPower()
+            }
+            const next = computeNextRun(task.cron, now)
+            store.updateTask(task.id, { lastRunAt: now, nextRunAt: next || 0 })
+          }
+        } catch (err) {
+          ctx.logger?.warn?.(`dsh-kanban: ошибка шедулера cron: ${err?.message}`)
+        }
+      }, 30_000)
+      if (typeof cronTimer.unref === 'function') cronTimer.unref()
+    }
+    armCron()
+    rearmers.add(armCron)
+    return () => { rearmers.delete(armCron); clearInterval(cronTimer) }
+  }, 'dsh-kanban: шедулер cron')
+
   // Периодическая сверка с Gitea. Ноль в настройках отключает её целиком, а
   // перекрытие запусков не допускается: медленный инстанс иначе копил бы
   // очередь сверок вместо одной идущей.
@@ -645,7 +774,7 @@ export function apply(ctx, config) {
             fallback: ctx.get('agentDefaultModel')?.currentSelection?.(),
           })
           if (picked.error) { writeJson(res, picked.status, { error: picked.error }); return }
-          reply(res, await runTask({
+          const started = await runTask({
             agents: ctx.agents,
             store,
             task,
@@ -661,8 +790,11 @@ export function apply(ctx, config) {
             agentPreset: typeof input.agentPreset === 'string' ? input.agentPreset : undefined,
             permission: typeof input.permission === 'string' ? input.permission : undefined,
             permissions: ctx.get('permissionPresets'),
+            workspaceRegistry: ctx.get('workspaceRegistry'),
             claimAs: await whoAmI(),
-          }))
+          })
+          syncPower()
+          reply(res, started)
         } catch (error) {
           ctx.logger?.warn?.(`dsh-kanban: запуск задачи не удался: ${error?.message}`)
           // Отказ по уровню доступа называется своим именем: «не удалось» на
@@ -698,15 +830,64 @@ export function apply(ctx, config) {
           if (out?.task !== undefined) {
             queueOutbound(id, out.task.column)
             if (acted !== undefined) out.command = acted
+            if (input.column === 'cleanup' && was?.worktree) {
+              const dirty = await checkWorktreeDirty({ worktreePath: was.worktree })
+              if (dirty.dirty) {
+                out.worktreeWarning = 'worktree-dirty'
+                out.dirtyFiles = dirty.files
+              }
+            }
           }
           reply(res, out)
           return
         }
+        if (req.method === 'POST' && action === 'cleanup-worktree') {
+          const task = store.getTask(id)
+          if (task === undefined) { writeJson(res, 404, { error: 'task-not-found' }); return }
+          const out = await cleanupTaskWorktree({
+            store,
+            task,
+            workspaceRegistry: ctx.get('workspaceRegistry'),
+            force: input?.force === true,
+          })
+          reply(res, out)
+          return
+        }
+        if (req.method === 'GET' && action === 'worktree-status') {
+          const task = store.getTask(id)
+          if (task === undefined) { writeJson(res, 404, { error: 'task-not-found' }); return }
+          const dirtyCheck = await checkWorktreeDirty({ worktreePath: task.worktree })
+          reply(res, {
+            worktree: task.worktree || '',
+            branch: task.branch || '',
+            workspaceId: task.workspaceId || '',
+            dirty: dirtyCheck.dirty,
+            files: dirtyCheck.files,
+          })
+          return
+        }
+        if (req.method === 'POST' && action === 'confirm-permission') {
+          reply(res, confirmPermission({ store, id }))
+          return
+        }
+        if (req.method === 'POST' && action === 'progress-dump') {
+          const task = store.getTask(id)
+          if (task === undefined) { writeJson(res, 404, { error: 'task-not-found' }); return }
+          const formatted = typeof input === 'string' ? input : formatProgressDump(input)
+          const updated = store.updateTask(id, { progressDump: formatted })
+          reply(res, { task: updated })
+          return
+        }
         if (req.method === 'POST' && action === 'stop') {
           const task = store.getTask(id)
           if (task === undefined) { writeJson(res, 404, { error: 'task-not-found' }); return }
           const out = stopWork({ agents: ctx.agents, task, logger: ctx.logger })
           if (out.acted === 'stopped') {
+            const latestRun = Array.isArray(task.runs) ? task.runs[0] : undefined
+            if (latestRun && !latestRun.endedAt && typeof store.updateTaskRun === 'function') {
+              store.updateTaskRun(task.id, latestRun.id, { endedAt: Date.now(), result: 'cancelled' })
+            }
+            syncPower()
             // Остановка — событие, и в журнале ей место наравне с переносом:
             // иначе прерванная работа выглядит просто оборвавшейся сама.
             store.addTransition({

package/lib/launcher.js

@@ -13,6 +13,11 @@
 // приходят параметрами. Так модуль проверяется без харнесса и без сети.
 
 import { isAbsolute, join, resolve, sep } from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { createTaskWorktree, registerDshWorkspace } from './worktree.js'
+import { formatHandoverPreamble, parseProgressDump } from './progress-dump.js'
+
+export const PERMISSION_RANKS = { 'read-only': 0, 'workspace-write': 1, 'danger-full-access': 2 }
 
 /**
  * Хвост своей задачи — УСЛОВИЕ, а не приказ.
@@ -146,7 +151,7 @@ export function applyPermission({ permissions, agent, name }) {
 
 export async function obtainAgent({
   agents, task, config, provider, model, mintSessionId, cwdOf, logger,
-  agentPreset, permission, permissions,
+  agentPreset, permission, permissions, gitRunner, workspaceRegistry,
 }) {
   const known = typeof task?.sessionId === 'string' && task.sessionId !== '' ? task.sessionId : undefined
 
@@ -165,12 +170,51 @@ export async function obtainAgent({
     }
   }
 
-  const cwd = resolveCwd(task, config, cwdOf)
+  let cwd = resolveCwd(task, config, cwdOf)
+  let worktreePath = task?.worktree || undefined
+  let branchName = task?.branch || undefined
+  let workspaceId = task?.workspaceId || undefined
+  let worktreeCreated = false
+
+  if (config?.worktreeIsolation !== false && task?.repo) {
+    try {
+      const created = await createTaskWorktree({
+        task,
+        repoDir: cwd,
+        config,
+        gitRunner,
+        cwdOf,
+      })
+      if (created) {
+        worktreePath = created.worktreePath
+        branchName = created.branchName
+        worktreeCreated = created.created === true
+        cwd = created.worktreePath
+
+        if (workspaceRegistry) {
+          workspaceId = await registerDshWorkspace({
+            workspaceRegistry,
+            worktreePath,
+            title: `${task.owner ? task.owner + '/' : ''}${task.repo}#${task.issueNumber || task.id.slice(0, 8)}: ${task.title}`,
+          })
+        }
+      }
+    } catch (err) {
+      logger?.warn?.(`dsh-kanban: не удалось создать worktree для ${task.id}: ${err.message}`)
+    }
+  } else if (worktreePath) {
+    cwd = worktreePath
+  }
+
+  const meta = { cwd }
+  if (typeof agentPreset === 'string' && agentPreset !== '') meta.agentPreset = agentPreset
+  if (workspaceId) meta.workspaceId = workspaceId
+
   const handle = await agents.create({
     sessionId: mintSessionId(),
     // Профиль — факт создания сессии: у идущей его не сменить, поэтому он
     // едет здесь, а не отдельным вызовом после.
-    meta: typeof agentPreset === 'string' && agentPreset !== '' ? { cwd, agentPreset } : { cwd },
+    meta,
     agentOptions: { provider, model },
   })
   const access = applyPermission({ permissions, agent: handle.agent, name: permission })
@@ -183,7 +227,15 @@ export async function obtainAgent({
     error.status = 409
     throw error
   }
-  return { agent: handle.agent, sessionId: handle.agent.session.id, mode: 'created' }
+  return {
+    agent: handle.agent,
+    sessionId: handle.agent.session.id,
+    mode: 'created',
+    worktree: worktreePath,
+    branch: branchName,
+    workspaceId,
+    worktreeCreated,
+  }
 }
 
 /**
@@ -241,12 +293,37 @@ export async function runTask({
   agents, store, task, config, provider, model,
   mintSessionId, createMessage, cwdOf, logger, text,
   agentPreset, permission, permissions, claimAs,
+  gitRunner, workspaceRegistry,
 }) {
+  if (config?.permissionGateEnabled) {
+    const perm = permission || task.permission || 'read-only'
+    const defaultPerm = config?.sessionDefaultPermission || 'read-only'
+    if ((PERMISSION_RANKS[perm] ?? 0) > (PERMISSION_RANKS[defaultPerm] ?? 0)) {
+      if (!task.permissionConfirmedAt || task.permissionConfirmedAt === 0) {
+        const err = new Error('Требуется подтверждение прав')
+        err.key = 'permission-unconfirmed'
+        err.status = 403
+        throw err
+      }
+    }
+  }
+
   const taken = await obtainAgent({
     agents, task, config, provider, model, mintSessionId, cwdOf, logger,
-    agentPreset, permission, permissions,
+    agentPreset, permission, permissions, gitRunner, workspaceRegistry,
   })
 
+  // Фиксируем запуск в истории задачи
+  if (typeof store.recordTaskRun === 'function') {
+    store.recordTaskRun(task.id, {
+      id: randomUUID(),
+      sessionId: taken.sessionId,
+      startedAt: Date.now(),
+      model,
+      provider,
+    })
+  }
+
   await taken.agent.whenIdle()
   taken.agent.followup(createMessage({
     // Содержимое — МАССИВ блоков, а не строка: ядро перебирает его как список
@@ -256,12 +333,31 @@ export async function runTask({
   }))
 
   const before = store.getTask(task.id)
-  const patch = { sessionId: taken.sessionId, provider, model }
+  const patch = {
+    sessionId: taken.sessionId,
+    provider,
+    model,
+    ...(permission ? { permission } : {}),
+    ...(taken.worktree ? { worktree: taken.worktree } : {}),
+    ...(taken.branch ? { branch: taken.branch } : {}),
+    ...(taken.workspaceId ? { workspaceId: taken.workspaceId } : {}),
+  }
   store.updateTask(task.id, patch)
   // Запустил — значит отвечаешь: свободная задача становится твоей, чужая
   // остаётся чужой.
   claimOnStart({ store, task: before, login: claimAs })
 
+  // Изоляция сессии в отдельном воркдереве фиксируется в журнале.
+  if (taken.worktreeCreated) {
+    store.addTransition({
+      taskId: task.id,
+      fromCol: before.column,
+      toCol: before.column,
+      source: 'session',
+      detail: `изоляция: создано воркдерево ${taken.worktree} (${taken.branch})`,
+    })
+  }
+
   // Подмена чата не должна быть молчаливой: человек вернётся к задаче и не
   // поймёт, куда делась переписка.
   if (taken.mode === 'created' && before.sessionId) {
@@ -292,7 +388,20 @@ export async function runTask({
 /** Текст сообщения: человеческий, если он есть, иначе встроенная заготовка. */
 function messageFor(task, config, text) {
   const own = typeof text === 'string' ? text.trim() : ''
-  return own !== '' ? own : buildStartMessage(task, config)
+  const base = own !== '' ? own : buildStartMessage(task, config)
+  if (config?.progressDumpEnabled && task.progressDump) {
+    let parsed
+    try {
+      parsed = typeof task.progressDump === 'string' && task.progressDump.startsWith('{')
+        ? JSON.parse(task.progressDump)
+        : parseProgressDump(task.progressDump)?.dump
+    } catch {
+      parsed = parseProgressDump(task.progressDump)?.dump
+    }
+    const preamble = formatHandoverPreamble(parsed)
+    if (preamble) return `${preamble}${base}`
+  }
+  return base
 }
 
 /**

package/lib/lifecycle.js

@@ -9,6 +9,7 @@
 // делать с очередным событием.
 
 import { waitingFromEvent } from './transitions.js'
+import { parseProgressDump, formatProgressDump } from './progress-dump.js'
 
 /**
  * Обработать событие сессии.
@@ -17,14 +18,42 @@ import { waitingFromEvent } from './transitions.js'
  * большинство — для них здесь ничего не происходит, и это штатный ход, а не
  * пропуск.
  *
- * @returns {{taskId: string, waiting: boolean}|undefined} что изменилось
+ * @returns {{taskId: string, waiting?: boolean}|undefined} что изменилось
  */
-export function handleSessionEvent({ store, sessionId, type }) {
-  const next = waitingFromEvent(type)
-  if (next === undefined) return undefined
-
+export function handleSessionEvent({ store, sessionId, type, text, error }) {
   const task = store.findTaskBySession(sessionId)
   if (task === undefined) return undefined
+
+  // Если в ответе пришёл PROGRESSDUMP — обновляем срез в задаче
+  if (typeof text === 'string' && text.includes('<<<PROGRESSDUMP')) {
+    const parsed = parseProgressDump(text)
+    if (parsed.ok) {
+      store.updateTask(task.id, { progressDump: formatProgressDump(parsed.dump) })
+    }
+  }
+
+  // Обновляем исход запуска в истории runs
+  if (type === 'turn/end' || type === 'turn/completed') {
+    const latestRun = Array.isArray(task.runs) ? task.runs[0] : undefined
+    if (latestRun && latestRun.sessionId === sessionId && !latestRun.endedAt && typeof store.updateTaskRun === 'function') {
+      store.updateTaskRun(task.id, latestRun.id, {
+        endedAt: Date.now(),
+        result: 'succeeded',
+      })
+    }
+  } else if (type === 'turn/error' || type === 'session/error') {
+    const latestRun = Array.isArray(task.runs) ? task.runs[0] : undefined
+    if (latestRun && latestRun.sessionId === sessionId && !latestRun.endedAt && typeof store.updateTaskRun === 'function') {
+      store.updateTaskRun(task.id, latestRun.id, {
+        endedAt: Date.now(),
+        result: 'failed',
+        error: typeof error === 'string' ? error : error?.message || 'error',
+      })
+    }
+  }
+
+  const next = waitingFromEvent(type)
+  if (next === undefined) return undefined
   if (task.waiting === next) return undefined
 
   store.updateTask(task.id, { waiting: next })

package/lib/power.js

@@ -0,0 +1,157 @@
+// dsh-kanban: кроссплатформенный ингибитор сна системы во время работы задач.
+// Поддерживает Windows (PowerShell + Win32 API), Linux (systemd-inhibit) и macOS (caffeinate).
+
+import { spawn as defaultSpawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+
+const WINDOWS_HELPER = [
+  '$source = @\'',
+  'using System;',
+  'using System.Runtime.InteropServices;',
+  'public static class DshExecutionState {',
+  '  [DllImport("kernel32.dll", SetLastError = true)]',
+  '  public static extern uint SetThreadExecutionState(uint flags);',
+  '}',
+  '\'@',
+  'Add-Type -TypeDefinition $source',
+  "$continuous = [Convert]::ToUInt32('80000000', 16)",
+  '$systemRequired = [uint32]0x00000001',
+  'try {',
+  '  $result = [DshExecutionState]::SetThreadExecutionState($continuous -bor $systemRequired)',
+  '  if ($result -eq 0) { throw \'SetThreadExecutionState failed\' }',
+  '  [Console]::Out.WriteLine(\'READY\')',
+  '  [Console]::Out.Flush()',
+  '  while ([Console]::In.ReadLine() -ne $null) { }',
+  '} finally {',
+  '  [void][DshExecutionState]::SetThreadExecutionState($continuous)',
+  '}',
+].join('\n')
+
+const LINUX_HELPER = "process.stdout.write('READY\\n'); process.stdin.resume();"
+
+const LINUX_INHIBIT_PATHS = ['/usr/bin/systemd-inhibit', '/bin/systemd-inhibit']
+
+export class PowerInhibitor {
+  constructor(options = {}) {
+    this.platform = options.platform ?? process.platform
+    this.pid = options.pid ?? process.pid
+    this.spawn = options.spawn ?? defaultSpawn
+    this.exists = options.exists ?? existsSync
+    this.enabled = false
+    this.reasons = 0
+    this.child = null
+    this.phase = 'disabled'
+    this.lastError = null
+  }
+
+  setEnabled(enabled) {
+    this.enabled = Boolean(enabled)
+    this.sync()
+  }
+
+  setReasons(count) {
+    this.reasons = Math.max(0, Number(count) || 0)
+    this.sync()
+  }
+
+  acquire() {
+    this.reasons++
+    this.sync()
+  }
+
+  release() {
+    this.reasons = Math.max(0, this.reasons - 1)
+    this.sync()
+  }
+
+  sync() {
+    const shouldHold = this.enabled && this.reasons > 0
+    if (shouldHold && !this.child) {
+      this.startHelper()
+    } else if (!shouldHold && this.child) {
+      this.stopHelper()
+    }
+  }
+
+  startHelper() {
+    this.stopHelper()
+    try {
+      if (this.platform === 'win32') {
+        const psPath = `${process.env.SystemRoot || 'C:\\Windows'}\\System32\\WindowsPowerShell\\v1.0\\powershell.exe`
+        this.child = this.spawn(psPath, ['-NoProfile', '-NonInteractive', '-Command', WINDOWS_HELPER], {
+          shell: false,
+          windowsHide: true,
+          stdio: ['pipe', 'pipe', 'pipe'],
+        })
+      } else if (this.platform === 'darwin') {
+        this.child = this.spawn('/usr/bin/caffeinate', ['-i', '-w', String(this.pid)], {
+          shell: false,
+          windowsHide: true,
+          stdio: ['ignore', 'ignore', 'ignore'],
+        })
+      } else if (this.platform === 'linux') {
+        const bin = LINUX_INHIBIT_PATHS.find((p) => this.exists(p))
+        if (!bin) {
+          this.phase = 'unsupported'
+          return
+        }
+        this.child = this.spawn(
+          bin,
+          ['--what=idle', '--who=dsh-kanban', '--why=Task running', 'node', '-e', LINUX_HELPER],
+          { shell: false, windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'] },
+        )
+      } else {
+        this.phase = 'unsupported'
+        return
+      }
+
+      this.phase = 'running'
+      this.lastError = null
+
+      this.child.on('error', (err) => {
+        this.lastError = err?.message
+        this.phase = 'error'
+        this.child = null
+      })
+
+      this.child.on('exit', () => {
+        this.child = null
+        if (this.enabled && this.reasons > 0) {
+          this.phase = 'disabled'
+        }
+      })
+    } catch (err) {
+      this.lastError = err?.message
+      this.phase = 'error'
+      this.child = null
+    }
+  }
+
+  stopHelper() {
+    if (this.child) {
+      try {
+        if (this.child.stdin && !this.child.stdin.destroyed) {
+          this.child.stdin.end()
+        }
+        this.child.kill()
+      } catch {}
+      this.child = null
+    }
+    this.phase = 'disabled'
+  }
+
+  snapshot() {
+    return {
+      enabled: this.enabled,
+      reasons: this.reasons,
+      phase: this.phase,
+      lastError: this.lastError,
+    }
+  }
+
+  destroy() {
+    this.enabled = false
+    this.reasons = 0
+    this.stopHelper()
+  }
+}