dsh-taskboard 0.1.0

package/src/host/execution.ts

@@ -0,0 +1,244 @@
+/**
+ * Host execution service: runs a task through dsh's REAL session machinery —
+ * a fresh agent+session inside the task's project workspace (creation carries
+ * the pinned model when the task has one), the session is attached to the
+ * workspace so it appears in the GUI's project session list, the effective
+ * prompt is submitted as an ordinary user message, and the turn settlement
+ * (turn/end reason) is folded back into the task's execution record.
+ *
+ * Every execution is a NEW session: clean context, no reuse of previous runs.
+ *
+ * @module dsh-taskboard/host/execution
+ */
+import { effectivePrompt, newExecutionId, type ExecutionRecord, type TaskRecord } from '../shared/protocol.ts'
+import { MessageId } from './sdk.ts'
+import type { TaskStore } from './store.ts'
+
+/** Narrow agents face (the registry's create, structurally). */
+export interface AgentsFace {
+  create(options: {
+    sessionId: string
+    meta?: { cwd?: string }
+    agentOptions?: { provider?: string; model?: string }
+  }): Promise<{
+    agent: {
+      id: string
+      followup(message: unknown): void
+      whenIdle(): Promise<void>
+    }
+    dispose(): Promise<void>
+  }>
+}
+
+/** Narrow workspaces face for execution. */
+export interface ExecutionWorkspaceFace {
+  get(id: string): { id: string; path: string } | undefined
+  attach(workspaceId: string, sessionId: string): Promise<void>
+}
+
+/** Narrow event-bus face for settlement listening. */
+export interface EventsFace {
+  onSessionEvent(listener: (sessionId: string, event: { type: string; data?: unknown }) => void): () => void
+}
+
+/** Everything the execution service needs. */
+export interface ExecutionDeps {
+  store: TaskStore
+  agents: AgentsFace
+  workspaces: ExecutionWorkspaceFace
+  events: EventsFace
+  now: () => number
+  /** The deployment default model (fills sessions of unpinned tasks). */
+  defaultModel?: () => { provider: string; model: string } | undefined
+  /** Mint session ids (injectable for tests). */
+  mintSessionId?: () => string
+  /** Mint message ids (injectable for tests). */
+  mintMessageId?: () => string
+}
+
+/** Outcome of a run request (immediate; the run settles asynchronously). */
+export type RunRequestResult =
+  | { ok: true; executionId: string; sessionId: string }
+  | { ok: false; error: string }
+
+/** Whether a turn/end payload closed with an error reason. */
+function isErrorTurnEnd(data: unknown): { message: string } | undefined {
+  if (typeof data !== 'object' || data === null) return undefined
+  const reason = (data as { reason?: unknown }).reason
+  if (typeof reason !== 'object' || reason === null) return undefined
+  const kind = (reason as { kind?: unknown }).kind
+  if (kind !== 'error') return undefined
+  const error = (reason as { error?: { message?: unknown } }).error
+  const detail = JSON.stringify(error) ?? ''
+  const message = typeof error?.message === 'string' ? error.message : 'turn failed'
+  console.error('[dsh-taskboard] turn error detail:', detail.slice(0, 2000))
+  void detail
+  return { message }
+}
+
+/**
+ * The execution service.
+ */
+export class ExecutionService {
+  /** Execution ids currently settling. */
+  private readonly settling = new Map<string, () => void>()
+
+  /** @param deps - store + agents + workspaces + events + clock. */
+  constructor(private readonly deps: ExecutionDeps) {
+    deps.events.onSessionEvent((sessionId, event) => {
+      if (event.type !== 'turn/end') return
+      const failure = isErrorTurnEnd(event.data)
+      if (failure !== undefined) this.noteFailure(sessionId, failure.message)
+    })
+  }
+
+  /** Record a turn failure against the running execution of that session. */
+  private noteFailure(sessionId: string, message: string): void {
+    void this.deps.store.mutate('execution-recorded', (ledger) => {
+      for (const task of ledger.tasks) {
+        for (const execution of task.executions) {
+          if (execution.sessionId === sessionId && execution.outcome === 'running') {
+            execution.outcome = 'failed'
+            execution.error = message.slice(0, 500)
+            execution.endedAt = this.deps.now()
+            return [task]
+          }
+        }
+      }
+      return undefined
+    })
+  }
+
+  /** Patch one task's execution record in the ledger. */
+  private async patchExecution(executionId: string, patch: Partial<ExecutionRecord>): Promise<void> {
+    await this.deps.store.mutate('execution-recorded', (ledger) => {
+      for (const task of ledger.tasks) {
+        const execution = task.executions.find(e => e.id === executionId)
+        if (execution !== undefined) {
+          Object.assign(execution, patch)
+          return [task]
+        }
+      }
+      return undefined
+    })
+  }
+
+  /**
+   * Run one task now (manual button or scheduler tick).
+   * @param taskId - the task to run.
+   * @param trigger - what started it.
+   * @returns the immediate result; settlement lands in the ledger.
+   */
+  async run(taskId: string, trigger: ExecutionRecord['trigger']): Promise<RunRequestResult> {
+    const task = this.deps.store.get(taskId)
+    if (task === undefined || task.trashedAt !== undefined) {
+      return { ok: false, error: `no task ${taskId}` }
+    }
+    if (task.status === 'in_progress') {
+      return { ok: false, error: 'task is already in progress' }
+    }
+    const workspace = this.deps.workspaces.get(task.workspaceId)
+    if (workspace === undefined) {
+      return { ok: false, error: `unknown workspace ${task.workspaceId}` }
+    }
+
+    const executionId = newExecutionId()
+    const sessionId = this.deps.mintSessionId?.() ?? `session-taskboard-${crypto.randomUUID()}`
+
+    // 1. Open the execution record and move the card to in_progress in one write.
+    await this.deps.store.mutate('execution-recorded', (ledger) => {
+      const target = ledger.tasks.find(t => t.id === taskId)
+      if (target === undefined) return undefined
+      target.executions.push({
+        id: executionId,
+        trigger,
+        startedAt: this.deps.now(),
+        outcome: 'running',
+      })
+      target.status = 'in_progress'
+      target.updatedAt = this.deps.now()
+      target.updatedBy = { kind: 'user' }
+      return [target]
+    })
+
+    // 2. Create the fresh agent+session inside the task's project, carrying
+    //    the pinned model — or the deployment default when unpinned (the
+    //    persona template renders {{model}}, so the session always needs one).
+    let handle: Awaited<ReturnType<AgentsFace['create']>>
+    try {
+      const model = task.model ?? this.deps.defaultModel?.()
+      handle = await this.deps.agents.create({
+        sessionId,
+        meta: { cwd: workspace.path },
+        ...(model !== undefined ? { agentOptions: { provider: model.provider, model: model.model } } : {}),
+      })
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      await this.patchExecution(executionId, { outcome: 'failed', error: message.slice(0, 500), endedAt: this.deps.now() })
+      await this.revertProgress(taskId)
+      return { ok: false, error: message }
+    }
+
+    // 3. Attach the session to the workspace (GUI project session list).
+    await this.deps.workspaces.attach(task.workspaceId, sessionId).catch(() => { /* cosmetic */ })
+
+    // 4. Record the session id (execution is really started now).
+    await this.patchExecution(executionId, { sessionId })
+
+    // 5. Submit the effective prompt as an ordinary user message and settle
+    //    on quiescence (turn/end errors were already folded by the listener).
+    const message = {
+      id: this.deps.mintMessageId?.() ?? MessageId(`msg-taskboard-${crypto.randomUUID()}`),
+      role: 'user' as const,
+      content: [{ type: 'text' as const, text: this.executionPrompt(task) }],
+      source: { kind: 'plugin' as const, plugin: 'dsh-taskboard' },
+    }
+    handle.agent.followup(message)
+
+    // 6. Settlement watcher.
+    const settle = (): void => {
+      this.settling.delete(executionId)
+      void this.deps.store.mutate('execution-recorded', (ledger) => {
+        for (const t of ledger.tasks) {
+          const execution = t.executions.find(e => e.id === executionId)
+          if (execution !== undefined && execution.outcome === 'running') {
+            execution.outcome = 'succeeded'
+            execution.endedAt = this.deps.now()
+            return [t]
+          }
+        }
+        return undefined
+      })
+    }
+    this.settling.set(executionId, settle)
+    void handle.agent.whenIdle().then(settle, () => {
+      this.noteFailure(sessionId, 'agent did not reach quiescence')
+      settle()
+    })
+
+    return { ok: true, executionId, sessionId }
+  }
+
+  /** The prompt text one execution submits (task context + instructions). */
+  private executionPrompt(task: TaskRecord): string {
+    const head = `【任务看板执行】${task.title}（任务 ID: ${task.id}）`
+    const state = '本任务由执行服务启动本会话并已置为 in_progress（你无需再认领，也无需移到 done）。'
+    const tail = `完成后请：1) 用 taskboard_get 读取任务 ${task.id} 拿最新 version；`
+      + `2) 用 taskboard_comment_add 留评论（做了什么改动、如何验证、剩余风险）；`
+      + `3) 用 taskboard_move 把任务 ${task.id} 移到 in_review（带 ifVersion）。`
+    return `${head}\n\n${state}\n\n${effectivePrompt(task)}\n\n${tail}`
+  }
+
+  /** Move a task back out of in_progress after a failed start. */
+  private async revertProgress(taskId: string): Promise<void> {
+    await this.deps.store.mutate('execution-recorded', (ledger) => {
+      const target = ledger.tasks.find(t => t.id === taskId)
+      if (target !== undefined && target.status === 'in_progress') {
+        target.status = 'todo'
+        target.updatedAt = this.deps.now()
+        return [target]
+      }
+      return undefined
+    })
+  }
+}

package/src/host/protocol-text.ts

@@ -0,0 +1,37 @@
+/**
+ * The agent workflow protocol text — the single source the system-prompt
+ * section serves. This is a behavioral contract, not a feature ad: claiming
+ * discipline, optimistic-version retry rules, review handoff, and the
+ * user-only completion gate.
+ *
+ * The regression test (tests/protocol.spec.ts) locks the discipline
+ * sentences, so editing the text without revisiting the test fails loud.
+ *
+ * @module dsh-taskboard/host/protocol-text
+ */
+
+/** The protocol section served to every agent (Chinese UI deployment). */
+export const TASKBOARD_PROTOCOL = [
+  '本机已安装 dsh-taskboard 插件（DSH 任务看板）：任务挂在项目（DSH workspace）上，',
+  '用 taskboard_* 工具读写；人在 Web GUI 看板上实时看到同样数据。能力：查板(list/get)、',
+  '建卡(create)、改卡(update)、移卡(move)、评论(comment_add/comments)、删除(delete=仅标记)。',
+  '任务带紧急度(urgent红/normal紫/relaxed蓝)、执行方式(claim认领/scheduled定时)与可选指定模型。',
+  '工作纪律：',
+  '1. 开工先查板：开始工作前先 taskboard_list（按本项目过滤、status=todo），有可认领任务时按纪律认领。',
+  '2. 先读后动：动卡前先 taskboard_get 并读评论；评论视为最新需求，若要求等待/暂缓，停下汇报，不改状态。',
+  '3. 先认领再干活：把 todo→in_progress（带 ifVersion）成功后，才开始读代码/分析实现；',
+  '   认领失败（版本冲突/项目边界不符/已被他人持有）就停止并报告，绝不循环重试或接管他人任务。',
+  '4. 版本冲突只重试一次：ifVersion 冲突时重新读卡，仅当状态仍可认领且需求未变时用新版本号重试一次，再失败即停止报告。',
+  '5. 验收交接：实现并自验后，评论记录（改动/验证结果/剩余风险），再把 in_progress→in_review。',
+  '6. 完成须用户确认：你永远不能把任务移到 done——那是用户的确认动作；blocked=无法继续，canceled=不再继续。',
+  '7. backlog=未授权：backlog 任务不算批准执行，被指派也不是授权，除非用户明确要求。',
+  '8. 模型与定时只读：任务的 model 与 execution 配置归创建者/用户所有，update 工具不允许你修改这两个字段。',
+  '项目边界：只有属于任务所在项目的会话才能认领（todo→in_progress）或执行它。',
+  '用户提到「任务看板/看板/认领任务」时即指本插件，请据此协作。',
+].join('\n')
+
+/** Section order inside the tool-guidance band (100–199). */
+export const PROTOCOL_SECTION_ORDER = 180
+
+/** Registered section name. */
+export const PROTOCOL_SECTION_NAME = 'plugin:dsh-taskboard'

package/src/host/routes.ts

@@ -0,0 +1,387 @@
+/**
+ * /dsh-taskboard routes on the shared DSH webserver: a JSON API for the
+ * GUI's human operations (create/update/move/comment/delete — actor `user`,
+ * the done move IS allowed here) plus an SSE stream mirroring every
+ * committed ledger mutation.
+ *
+ * All domain validation goes through the shared protocol pure functions; the
+ * route layer only maps transport to envelope.
+ *
+ * @module dsh-taskboard/host/routes
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { Context } from '@deepseek-ai/cordis'
+// Type-only: pulls the webServer Context merge (ctx.webServer).
+import type {} from '@deepseek-ai/dsh-host-webserver'
+import {
+  asStatus,
+  asUrgency,
+  canTransition,
+  newCommentId,
+  newTaskId,
+  normalizeBody,
+  normalizeExecution,
+  normalizePrompt,
+  normalizeTitle,
+  summarize,
+  type TaskRecord,
+} from '../shared/protocol.ts'
+import { ROUTE_PREFIX, SSE_PATH, type ApiFail, type ApiResult } from '../shared/api.ts'
+import type { TaskStore } from './store.ts'
+import type { WorkspaceFace } from './tools.ts'
+
+/** Heartbeat cadence for the SSE stream. */
+const HEARTBEAT_MS = 20_000
+
+/** The workspaces face routes need (same narrow shape as tools). */
+export type RoutesWorkspaceFace = WorkspaceFace
+
+/** Options. */
+export interface TaskboardRoutesOptions {
+  store: TaskStore
+  workspaces: RoutesWorkspaceFace
+  now: () => number
+  /** Manual-run hook (the execution service); absent → 501. */
+  run?: (taskId: string) => Promise<{ ok: true; executionId: string; sessionId: string } | { ok: false; error: string }>
+}
+
+/** JSON-envelope writer. */
+function json(res: ServerResponse, payload: ApiResult<unknown>, status = 200): void {
+  const body = JSON.stringify(payload)
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
+  res.end(body)
+}
+
+/** Domain failure → envelope + HTTP status. */
+function fail(code: ApiFail['error']['code'], message: string): { res: ApiFail; status: number } {
+  const status = code === 'invalid_input' ? 400
+    : code === 'not_found' ? 404
+      : code === 'version_conflict' ? 409
+        : code === 'forbidden' ? 403
+          : 500
+  return { res: { ok: false, error: { code, message } }, status }
+}
+
+/** Read one JSON body (null on parse failure). */
+async function readBody(req: IncomingMessage): Promise<Record<string, unknown> | null> {
+  const chunks: Buffer[] = []
+  for await (const chunk of req) chunks.push(chunk as Buffer)
+  if (chunks.length === 0) return {}
+  try {
+    const parsed = JSON.parse(Buffer.concat(chunks).toString('utf8'))
+    return typeof parsed === 'object' && parsed !== null ? parsed as Record<string, unknown> : null
+  } catch {
+    return null
+  }
+}
+
+/** String field accessor (null when absent/not a string). */
+function str(body: Record<string, unknown>, key: string): string | null {
+  const v = body[key]
+  return typeof v === 'string' ? v : null
+}
+
+/** Number field accessor (undefined when absent; null when present but not a number). */
+function num(body: Record<string, unknown>, key: string): number | undefined | null {
+  const v = body[key]
+  if (v === undefined) return undefined
+  return typeof v === 'number' && Number.isFinite(v) ? v : null
+}
+
+/** Map a thrown domain error to the envelope. */
+function toFail(error: unknown): { res: ApiFail; status: number } {
+  const message = error instanceof Error ? error.message : String(error)
+  const code = message.startsWith('Error: ') ? message.slice(7).split(':')[0] : undefined
+  const known: ApiFail['error']['code'][] = ['invalid_input', 'not_found', 'version_conflict', 'invalid_transition', 'forbidden', 'internal']
+  if (code !== undefined && (known as string[]).includes(code)) {
+    return fail(code as ApiFail['error']['code'], message.slice(7 + code.length + 2))
+  }
+  if (code === 'workspace_mismatch') return fail('forbidden', message.slice(7 + code.length + 2))
+  return fail('invalid_input', message)
+}
+
+/**
+ * Register the taskboard routes.
+ * @param ctx - context carrying the webServer service.
+ * @param options - store + workspaces + clock.
+ * @returns the disposer.
+ */
+export function registerTaskboardRoutes(ctx: Context, options: TaskboardRoutesOptions): () => void {
+  const { store, workspaces } = options
+  const subscribers = new Set<ServerResponse>()
+  let heartbeat: NodeJS.Timeout | undefined
+
+  const broadcast = (change: { revision: number; kind: string; tasks: readonly TaskRecord[] }): void => {
+    const frame = `event: change\ndata: ${JSON.stringify({ revision: change.revision, kind: change.kind, tasks: change.tasks.map(summarize) })}\n\n`
+    for (const res of subscribers) res.write(frame)
+  }
+  store.subscribe(broadcast)
+
+  const taskPath = (id: string, action?: string): RegExp | null => {
+    const escaped = id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    const pattern = action === undefined
+      ? `^${ROUTE_PREFIX}/tasks/${escaped}$`
+      : `^${ROUTE_PREFIX}/tasks/${escaped}/${action}$`
+    return new RegExp(pattern)
+  }
+
+  const handler = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    try {
+      const url = new URL(req.url ?? '/', 'http://x')
+      const pathname = url.pathname
+
+      // ---------------------------------------------------------------- GET
+      if (req.method === 'GET') {
+        if (pathname === `${ROUTE_PREFIX}/state`) {
+          await store.load()
+          json(res, { ok: true, value: store.snapshot() })
+          return
+        }
+        if (pathname === `${ROUTE_PREFIX}/workspaces`) {
+          json(res, { ok: true, value: workspaces.list() })
+          return
+        }
+        const taskMatch = pathname.match(new RegExp(`^${ROUTE_PREFIX}/tasks/([^/]+)$`))
+        if (taskMatch !== null) {
+          const task = store.get(taskMatch[1]!)
+          if (task === undefined) { const f = fail('not_found', 'no such task'); json(res, f.res, f.status); return }
+          json(res, { ok: true, value: task })
+          return
+        }
+        res.writeHead(404)
+        res.end()
+        return
+      }
+
+      if (req.method !== 'POST') {
+        res.writeHead(405)
+        res.end()
+        return
+      }
+      // CSRF fence: cross-site simple requests cannot set application/json.
+      const contentType = req.headers['content-type'] ?? ''
+      if (!contentType.toLowerCase().startsWith('application/json')) {
+        const f = fail('invalid_input', 'content-type must be application/json')
+        json(res, f.res, 415)
+        return
+      }
+      const body = await readBody(req)
+      if (body === null) {
+        const f = fail('invalid_input', 'body is not a JSON object')
+        json(res, f.res, 400)
+        return
+      }
+
+      // ------------------------------------------------- POST /tasks (create)
+      if (pathname === `${ROUTE_PREFIX}/tasks`) {
+        try {
+          const title = normalizeTitle(str(body, 'title') ?? '')
+          const workspaceId = str(body, 'workspaceId') ?? ''
+          if (workspaces.get(workspaceId) === undefined) throw new Error('Error: not_found: unknown workspace')
+          const urgency = asUrgency(str(body, 'urgency') ?? '')
+          const status = str(body, 'status') === null ? 'todo' as const : asStatus(str(body, 'status')!)
+          const execution = normalizeExecution((body.execution as { mode?: string; cron?: string } | undefined) ?? {}, options.now())
+          const model = body.model as { provider: string; model: string } | undefined
+          const now = options.now()
+          const task: TaskRecord = {
+            id: newTaskId(),
+            title,
+            description: (str(body, 'description') ?? '').trim(),
+            prompt: normalizePrompt(str(body, 'prompt') ?? undefined),
+            workspaceId,
+            urgency,
+            status,
+            blocked: false,
+            execution,
+            model,
+            version: 1,
+            createdAt: now,
+            updatedAt: now,
+            createdBy: { kind: 'user' },
+            updatedBy: { kind: 'user' },
+            comments: [],
+            executions: [],
+          }
+          await store.mutate('task-created', ledger => {
+            ledger.tasks.push(task)
+            return [task]
+          })
+          json(res, { ok: true, value: summarize(task) }, 201)
+        } catch (error) {
+          const f = toFail(error)
+          json(res, f.res, f.status)
+        }
+        return
+      }
+
+      // ------------------------------------------- POST /tasks/:id/{action}
+      const actionMatch = pathname.match(new RegExp(`^${ROUTE_PREFIX}/tasks/([^/]+)/(\\w+)$`))
+      if (actionMatch !== null) {
+        const id = actionMatch[1]!
+        const action = actionMatch[2]!
+        try {
+          const task = store.get(id)
+          if (task === undefined) throw new Error('Error: not_found: no such task')
+          if (action === 'update') {
+            const ifVersion = num(body, 'ifVersion')
+            if (ifVersion === undefined || ifVersion === null) throw new Error('Error: version_conflict: ifVersion required')
+            if (ifVersion !== task.version) throw new Error(`Error: version_conflict: stale version ${ifVersion} (current ${task.version})`)
+            const next = structuredClone(task)
+            const title = str(body, 'title')
+            if (title !== null) next.title = normalizeTitle(title)
+            const description = str(body, 'description')
+            if (description !== null) next.description = description.trim()
+            const prompt = str(body, 'prompt')
+            if (prompt !== null) next.prompt = normalizePrompt(prompt)
+            const urgency = str(body, 'urgency')
+            if (urgency !== null) next.urgency = asUrgency(urgency)
+            // GUI-only rebind to another project; validated against the workspace registry.
+            const workspaceId = str(body, 'workspaceId')
+            if (workspaceId !== null) {
+              if (workspaces.get(workspaceId) === undefined) throw new Error('Error: not_found: unknown workspace')
+              next.workspaceId = workspaceId
+            }
+            if (typeof body.blocked === 'boolean') next.blocked = body.blocked
+            // The GUI (task owner surface) may edit model/execution; null clears the model.
+            if (body.execution !== undefined) next.execution = normalizeExecution(body.execution as { mode?: string; cron?: string }, options.now())
+            if (body.model === null) next.model = undefined
+            else if (body.model !== undefined) next.model = body.model as { provider: string; model: string }
+            next.version = task.version + 1
+            next.updatedAt = options.now()
+            next.updatedBy = { kind: 'user' }
+            await store.mutate('task-updated', ledger => {
+              const i = ledger.tasks.findIndex(t => t.id === id)
+              ledger.tasks[i] = next
+              return [next]
+            })
+            json(res, { ok: true, value: summarize(next) })
+            return
+          }
+          if (action === 'move') {
+            const ifVersion = num(body, 'ifVersion')
+            const status = str(body, 'status') ?? ''
+            if (ifVersion === undefined || ifVersion === null) throw new Error('Error: version_conflict: ifVersion required')
+            if (ifVersion !== task.version) throw new Error(`Error: version_conflict: stale version ${ifVersion} (current ${task.version})`)
+            const to = asStatus(status)
+            if (!canTransition(task.status, to)) throw new Error(`Error: invalid_transition: illegal transition ${task.status} → ${to}`)
+            const next = structuredClone(task)
+            next.status = to
+            next.version = task.version + 1
+            next.updatedAt = options.now()
+            next.updatedBy = { kind: 'user' }
+            if (task.status === 'todo' && to === 'in_progress') next.blocked = false
+            await store.mutate('task-moved', ledger => {
+              const i = ledger.tasks.findIndex(t => t.id === id)
+              ledger.tasks[i] = next
+              return [next]
+            })
+            json(res, { ok: true, value: summarize(next) })
+            return
+          }
+          if (action === 'comment') {
+            const bodyText = str(body, 'body') ?? ''
+            const comment = { id: newCommentId(), body: normalizeBody(bodyText), version: 1, createdAt: options.now() }
+            const next = structuredClone(task)
+            next.comments.push(comment)
+            next.version = task.version + 1
+            next.updatedAt = options.now()
+            await store.mutate('comment-added', ledger => {
+              const i = ledger.tasks.findIndex(t => t.id === id)
+              ledger.tasks[i] = next
+              return [next]
+            })
+            json(res, { ok: true, value: comment }, 201)
+            return
+          }
+          if (action === 'delete') {
+            const purge = body.purge === true
+            if (purge) {
+              if (task.trashedAt === undefined) throw new Error('Error: invalid_input: purge requires a trashed task (soft-delete first)')
+              await store.mutate('task-deleted', ledger => {
+                ledger.tasks = ledger.tasks.filter(t => t.id !== id)
+                return []
+              })
+              json(res, { ok: true, value: { purged: true } })
+              return
+            }
+            const ifVersion = num(body, 'ifVersion')
+            if (ifVersion === undefined || ifVersion === null) throw new Error('Error: version_conflict: ifVersion required')
+            if (ifVersion !== task.version) throw new Error(`Error: version_conflict: stale version ${ifVersion} (current ${task.version})`)
+            const next = structuredClone(task)
+            next.trashedAt = options.now()
+            next.version = task.version + 1
+            await store.mutate('task-deleted', ledger => {
+              const i = ledger.tasks.findIndex(t => t.id === id)
+              ledger.tasks[i] = next
+              return [next]
+            })
+            json(res, { ok: true, value: { trashed: true } })
+            return
+          }
+          if (action === 'run') {
+            if (options.run === undefined) {
+              const f = fail('invalid_input', 'execution service unavailable')
+              json(res, f.res, 501)
+              return
+            }
+            const result = await options.run(id)
+            if (result.ok) json(res, { ok: true, value: result }, 202)
+            else {
+              const f = fail('invalid_input', result.error)
+              json(res, f.res, f.status)
+            }
+            return
+          }
+          const f = fail('not_found', `unknown action ${action}`)
+          json(res, f.res, f.status)
+        } catch (error) {
+          const f = toFail(error)
+          json(res, f.res, f.status)
+        }
+        return
+      }
+
+      void taskPath
+      res.writeHead(404)
+      res.end()
+    } catch (error) {
+      const f = fail('internal', error instanceof Error ? error.message : String(error))
+      json(res, f.res, f.status)
+    }
+  }
+
+  const sse = (req: IncomingMessage, res: ServerResponse): void => {
+    res.writeHead(200, {
+      'content-type': 'text/event-stream; charset=utf-8',
+      'cache-control': 'no-cache',
+      connection: 'keep-alive',
+    })
+    res.write('retry: 2000\n\n')
+    // Baseline frame: the client reconciles by revision and refetches state on gaps.
+    res.write(`event: hello\ndata: ${JSON.stringify({ revision: store.snapshot().revision })}\n\n`)
+    subscribers.add(res)
+    if (heartbeat === undefined) {
+      heartbeat = setInterval(() => {
+        for (const current of subscribers) current.write(': ping\n\n')
+      }, HEARTBEAT_MS)
+    }
+    req.on('close', () => {
+      subscribers.delete(res)
+      if (subscribers.size === 0 && heartbeat !== undefined) {
+        clearInterval(heartbeat)
+        heartbeat = undefined
+      }
+    })
+  }
+
+  const disposers = [
+    ctx.webServer.register({ kind: 'prefix', path: ROUTE_PREFIX, handler }),
+    ctx.webServer.register({ kind: 'exact', path: SSE_PATH, handler: sse }),
+  ]
+  return () => {
+    for (const dispose of disposers) dispose()
+    if (heartbeat !== undefined) clearInterval(heartbeat)
+    for (const res of subscribers) res.end()
+    subscribers.clear()
+  }
+}