dsh-taskboard 0.1.2 → 0.2.1

package/src/host/execution.ts

@@ -10,10 +10,20 @@
  *
  * @module dsh-taskboard/host/execution
  */
-import { effectivePrompt, newExecutionId, type ExecutionRecord, type TaskRecord } from '../shared/protocol.ts'
+import {
+  effectivePrompt,
+  newCommentId,
+  newExecutionId,
+  normalizeBody,
+  type ExecutionRecord,
+  type TaskRecord,
+} from '../shared/protocol.ts'
 import { MessageId } from './sdk.ts'
 import type { TaskStore } from './store.ts'
 
+/** Default cap on concurrently running executions (env-overridable). */
+export const DEFAULT_MAX_CONCURRENT = 3
+
 /** Narrow agents face (the registry's create, structurally). */
 export interface AgentsFace {
   create(options: {
@@ -24,6 +34,7 @@ export interface AgentsFace {
     agent: {
       id: string
       followup(message: unknown): void
+      inject(message: unknown): void
       whenIdle(): Promise<void>
     }
     dispose(): Promise<void>
@@ -56,6 +67,8 @@ export interface ExecutionDeps {
   mintMessageId?: () => string
   /** Best-effort session rename (pins the session list title to the task title). */
   renameSession?: (sessionId: string, title: string) => void
+  /** Max concurrently running executions across all tasks (default 3). */
+  maxConcurrent?: number
 }
 
 /** Outcome of a run request (immediate; the run settles asynchronously). */
@@ -63,6 +76,11 @@ export type RunRequestResult =
   | { ok: true; executionId: string; sessionId: string }
   | { ok: false; error: string }
 
+/** Outcome of a cancel request. */
+export type CancelRequestResult =
+  | { ok: true; executionId: 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
@@ -78,12 +96,19 @@ function isErrorTurnEnd(data: unknown): { message: string } | undefined {
   return { message }
 }
 
+/** One live execution tracked for settlement and cancellation. */
+interface RunEntry {
+  sessionId: string
+  settle: () => void
+  dispose: () => Promise<void>
+}
+
 /**
  * The execution service.
  */
 export class ExecutionService {
-  /** Execution ids currently settling. */
-  private readonly settling = new Map<string, () => void>()
+  /** Live executions by execution id (settles and cancels remove entries). */
+  private readonly runs = new Map<string, RunEntry>()
 
   /** @param deps - store + agents + workspaces + events + clock. */
   constructor(private readonly deps: ExecutionDeps) {
@@ -94,7 +119,7 @@ export class ExecutionService {
     })
   }
 
-  /** Record a turn failure against the running execution of that session. */
+  /** Record a turn failure against the running execution of that session and give the task back. */
   private noteFailure(sessionId: string, message: string): void {
     void this.deps.store.mutate('execution-recorded', (ledger) => {
       for (const task of ledger.tasks) {
@@ -103,6 +128,21 @@ export class ExecutionService {
             execution.outcome = 'failed'
             execution.error = message.slice(0, 500)
             execution.endedAt = this.deps.now()
+            // The failed session will not finish the work: hand the task back
+            // instead of leaving it stuck in in_progress forever — and leave a
+            // system comment so the GUI shows why.
+            if (task.status === 'in_progress' && task.claimedBy === sessionId) {
+              task.status = 'todo'
+              task.updatedAt = this.deps.now()
+              delete task.claimedBy
+              delete task.claimedAt
+              task.comments.push({
+                id: newCommentId(),
+                body: normalizeBody(`[系统] 执行失败：${message.slice(0, 300)}；任务已退回待办。`),
+                version: 1,
+                createdAt: this.deps.now(),
+              })
+            }
             return [task]
           }
         }
@@ -127,18 +167,24 @@ export class ExecutionService {
 
   /**
    * Run one task now (manual button or scheduler tick).
+   *
+   * The in-progress gate and the execution-open write happen inside ONE
+   * serial-queue mutation, so two overlapping run() calls (double click,
+   * overlapping scheduler ticks) can never both pass — exactly one session
+   * is opened per task.
    * @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 max = this.deps.maxConcurrent ?? DEFAULT_MAX_CONCURRENT
+    if (this.runs.size >= max) {
+      return { ok: false, error: `execution concurrency limit reached (${this.runs.size}/${max} running)` }
+    }
     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}` }
@@ -147,10 +193,19 @@ export class ExecutionService {
     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.
+    // 1. Open the execution record, flip the card to in_progress, and record
+    //    the executing session as the claim holder — atomically.
+    let gate: string | undefined
     await this.deps.store.mutate('execution-recorded', (ledger) => {
       const target = ledger.tasks.find(t => t.id === taskId)
-      if (target === undefined) return undefined
+      if (target === undefined || target.trashedAt !== undefined) {
+        gate = `no task ${taskId}`
+        return undefined
+      }
+      if (target.status === 'in_progress') {
+        gate = 'task is already in progress'
+        return undefined
+      }
       target.executions.push({
         id: executionId,
         trigger,
@@ -160,8 +215,11 @@ export class ExecutionService {
       target.status = 'in_progress'
       target.updatedAt = this.deps.now()
       target.updatedBy = { kind: 'user' }
+      target.claimedBy = sessionId
+      target.claimedAt = this.deps.now()
       return [target]
     })
+    if (gate !== undefined) return { ok: false, error: gate }
 
     // 2. Create the fresh agent+session inside the task's project, carrying
     //    the pinned model — or the deployment default when unpinned (the
@@ -194,34 +252,65 @@ export class ExecutionService {
     // 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).
-    //    Source `user` (not `plugin`) so the opening message renders as a
-    //    normal user bubble in the conversation, exactly like a typed prompt.
-    const message = {
+    // 5. Submit the opening pair and settle on quiescence (turn/end errors
+    //    were already folded by the listener). Two messages, ONE turn:
+    //    - inject() queues the plugin framing line (next-step, no wake); it
+    //      renders as a plugin context row in the conversation.
+    //    - followup() queues the card body as a normal user message
+    //      (next-turn, wakes the driver). At claim time the loop drains ALL
+    //      next-step messages plus the one next-turn message into a single
+    //    turn — framing first, then the user bubble.
+    handle.agent.inject({
+      id: this.deps.mintMessageId?.() ?? MessageId(`msg-taskboard-${crypto.randomUUID()}`),
+      role: 'user' as const,
+      content: [{ type: 'text' as const, text: this.pluginFraming(task) }],
+      source: { kind: 'plugin' as const, plugin: 'dsh-taskboard' },
+    })
+    handle.agent.followup({
       id: this.deps.mintMessageId?.() ?? MessageId(`msg-taskboard-${crypto.randomUUID()}`),
       role: 'user' as const,
-      content: [{ type: 'text' as const, text: this.executionPrompt(task) }],
+      content: [{ type: 'text' as const, text: this.userBody(task) }],
       source: { kind: 'user' as const },
-    }
-    handle.agent.followup(message)
+    })
 
-    // 6. Settlement watcher.
+    // 6. Settlement watcher: mark succeeded, release the executing session's
+    //    hold, and — when the session did NOT follow the handoff protocol —
+    //    auto-move the card to in_review with a system comment (otherwise a
+    //    disobedient session would leave it hanging in in_progress forever).
     const settle = (): void => {
-      this.settling.delete(executionId)
+      this.runs.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') {
+            const now = this.deps.now()
             execution.outcome = 'succeeded'
-            execution.endedAt = this.deps.now()
+            execution.endedAt = now
+            if (t.status === 'in_progress' && t.claimedBy === sessionId) {
+              delete t.claimedBy
+              delete t.claimedAt
+            }
+            if (t.status === 'in_progress') {
+              const commented = t.comments.some(c => c.threadId === sessionId)
+              t.comments.push({
+                id: newCommentId(),
+                body: normalizeBody(commented
+                  ? '[系统] 执行会话已结束并留有评论，但未移至待验收；系统自动移入待验收。'
+                  : '[系统] 执行会话已结束，但未按协议交接（无评论、未移至待验收）；系统自动移入待验收，请审查后退回或验收。'),
+                version: 1,
+                createdAt: now,
+              })
+              t.status = 'in_review'
+              t.updatedAt = now
+              t.updatedBy = { kind: 'user' }
+            }
             return [t]
           }
         }
         return undefined
       })
     }
-    this.settling.set(executionId, settle)
+    this.runs.set(executionId, { sessionId, settle, dispose: () => handle.dispose() })
     void handle.agent.whenIdle().then(settle, () => {
       this.noteFailure(sessionId, 'agent did not reach quiescence')
       settle()
@@ -230,22 +319,127 @@ export class ExecutionService {
     return { ok: true, executionId, sessionId }
   }
 
-  /** The prompt text one execution submits (task context + instructions). */
-  private executionPrompt(task: TaskRecord): string {
-    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 `【任务】${task.title}（任务 ID: ${task.id}）\n\n${state}\n\n${effectivePrompt(task)}\n\n${tail}`
+  /** How many executions are currently running (for the concurrency cap). */
+  inFlight(): number {
+    return this.runs.size
+  }
+
+  /**
+   * Cancel the running execution of a task (user action): stop the agent
+   * session, mark the execution cancelled, and hand the task back to todo.
+   * @param taskId - the task whose execution should be stopped.
+   * @returns the immediate result.
+   */
+  async cancel(taskId: string): Promise<CancelRequestResult> {
+    const task = this.deps.store.get(taskId)
+    if (task === undefined) return { ok: false, error: `no task ${taskId}` }
+    const running = [...task.executions].reverse().find(e => e.outcome === 'running')
+    if (running === undefined) return { ok: false, error: 'no running execution' }
+
+    const entry = this.runs.get(running.id)
+    this.runs.delete(running.id)
+    // Stop the agent first (best effort): dispose stops the loop, unregisters
+    // the agent, and removes its session. A late whenIdle settlement no-ops —
+    // the record is no longer 'running'.
+    try {
+      await entry?.dispose()
+    } catch { /* already gone */ }
+
+    await this.deps.store.mutate('execution-recorded', (ledger) => {
+      const target = ledger.tasks.find(t => t.id === taskId)
+      if (target === undefined) return undefined
+      const execution = target.executions.find(e => e.id === running.id)
+      if (execution === undefined || execution.outcome !== 'running') return undefined
+      execution.outcome = 'cancelled'
+      execution.endedAt = this.deps.now()
+      if (target.status === 'in_progress') {
+        target.status = 'todo'
+        target.updatedAt = this.deps.now()
+        delete target.claimedBy
+        delete target.claimedAt
+      }
+      return [target]
+    })
+    return { ok: true, executionId: running.id }
+  }
+
+  /**
+   * Startup reconciliation after a host restart: executions left `running`
+   * by the previous process can never settle here (their settlement watchers
+   * died with it), so mark them failed and hand their tasks back to todo.
+   */
+  async reconcile(): Promise<void> {
+    await this.deps.store.mutate('execution-recorded', (ledger) => {
+      const now = this.deps.now()
+      const touched: TaskRecord[] = []
+      for (const task of ledger.tasks) {
+        let dirty = false
+        for (const execution of task.executions) {
+          if (execution.outcome === 'running') {
+            execution.outcome = 'failed'
+            execution.error = 'interrupted by host restart'
+            execution.endedAt = now
+            dirty = true
+          }
+        }
+        if (!dirty) continue
+        if (task.status === 'in_progress') {
+          task.status = 'todo'
+          task.updatedAt = now
+          delete task.claimedBy
+          delete task.claimedAt
+        }
+        touched.push(task)
+      }
+      return touched.length > 0 ? touched : undefined
+    })
+  }
+
+  /**
+   * The plugin framing line (rendered as a plugin context row): task head,
+   * already-claimed state, and the handoff protocol — everything the session
+   * must know about the board. The task id appears exactly once (here); the
+   * protocol steps below refer to it as 本任务.
+   */
+  private pluginFraming(task: TaskRecord): string {
+    return `【任务看板】${task.title}（ID: ${task.id}）\n`
+      + `本会话由任务看板执行服务启动，任务已置为进行中——无需认领；「已完成」仅限用户在界面操作（代码已限制，移了会被拒）。\n`
+      + `完成后按序交接：\n`
+      + `1. taskboard_get 读取本任务，取得最新 version\n`
+      + `2. taskboard_comment_add 留评论：做了什么改动 / 如何验证 / 剩余风险\n`
+      + `3. taskboard_move 将本任务移至待验收 in_review（带 ifVersion）\n`
+      + `若无法完成：留评论说明原因，将任务移回待办 todo。`
+  }
+
+  /**
+   * The card body as a normal user bubble: the effective prompt (explicit
+   * prompt, else title+description) with template variables resolved from
+   * the task's own history at submit time (valuable for recurring patrols):
+   * `{{lastExecution}}` → the previous execution's trigger/outcome/error;
+   * `{{lastComments}}` → the last three comments (who + body).
+   */
+  private userBody(task: TaskRecord): string {
+    const lastExec = [...task.executions].reverse().find(e => e.outcome !== 'running')
+    const lastExecText = lastExec === undefined
+      ? '（无）'
+      : `${lastExec.trigger} · ${lastExec.outcome}${lastExec.error !== undefined ? ` · ${lastExec.error.slice(0, 200)}` : ''} · ${new Date(lastExec.startedAt ?? 0).toISOString()}`
+    const lastCommentsText = task.comments.slice(-3)
+      .map(c => `[${c.threadId !== undefined ? 'agent' : 'user'}] ${c.body}`)
+      .join('\n') || '（无）'
+    return effectivePrompt(task)
+      .replace(/\{\{lastExecution\}\}/g, lastExecText)
+      .replace(/\{\{lastComments\}\}/g, lastCommentsText)
   }
 
-  /** Move a task back out of in_progress after a failed start. */
+  /** Move a task back out of in_progress (and release its hold) 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()
+        delete target.claimedBy
+        delete target.claimedAt
         return [target]
       }
       return undefined

package/src/host/routes.ts

@@ -21,9 +21,12 @@ import {
   newTaskId,
   normalizeBody,
   normalizeExecution,
+  normalizeModel,
   normalizePrompt,
   normalizeTitle,
   summarize,
+  syncClaim,
+  type TaskModel,
   type TaskRecord,
 } from '../shared/protocol.ts'
 import { ROUTE_PREFIX, SSE_PATH, type ApiFail, type ApiResult } from '../shared/api.ts'
@@ -43,6 +46,23 @@ export interface TaskboardRoutesOptions {
   now: () => number
   /** Manual-run hook (the execution service); absent → 501. */
   run?: (taskId: string) => Promise<{ ok: true; executionId: string; sessionId: string } | { ok: false; error: string }>
+  /** Cancel hook (the execution service); absent → 501. */
+  cancel?: (taskId: string) => Promise<{ ok: true; executionId: string } | { ok: false; error: string }>
+  /**
+   * Registered model provider routes (from the host llm runtime), for
+   * advisory validation of pinned models; undefined = runtime unavailable.
+   */
+  modelProviders?: () => string[] | undefined
+}
+
+/** Validate a pinned model: structural check always, provider route when known. */
+function checkModel(raw: unknown, modelProviders?: () => string[] | undefined): TaskModel {
+  const model = normalizeModel(raw)
+  const providers = modelProviders?.()
+  if (providers !== undefined && !providers.includes(model.provider)) {
+    throw new Error(`Error: invalid_input: model provider "${model.provider}" has no registered route (available: ${providers.join(', ')})`)
+  }
+  return model
 }
 
 /** JSON-envelope writer. */
@@ -117,14 +137,6 @@ export function registerTaskboardRoutes(ctx: Context, options: TaskboardRoutesOp
   }
   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')
@@ -181,7 +193,7 @@ export function registerTaskboardRoutes(ctx: Context, options: TaskboardRoutesOp
           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 model = body.model === undefined ? undefined : checkModel(body.model, options.modelProviders)
           const now = options.now()
           const task: TaskRecord = {
             id: newTaskId(),
@@ -245,7 +257,7 @@ export function registerTaskboardRoutes(ctx: Context, options: TaskboardRoutesOp
             // 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 }
+            else if (body.model !== undefined) next.model = checkModel(body.model, options.modelProviders)
             next.version = task.version + 1
             next.updatedAt = options.now()
             next.updatedBy = { kind: 'user' }
@@ -270,6 +282,8 @@ export function registerTaskboardRoutes(ctx: Context, options: TaskboardRoutesOp
             next.updatedAt = options.now()
             next.updatedBy = { kind: 'user' }
             if (task.status === 'todo' && to === 'in_progress') next.blocked = false
+            // A user move records no holder; leaving in_progress releases any hold.
+            syncClaim(next, to, options.now())
             await store.mutate('task-moved', ledger => {
               const i = ledger.tasks.findIndex(t => t.id === id)
               ledger.tasks[i] = next
@@ -332,6 +346,20 @@ export function registerTaskboardRoutes(ctx: Context, options: TaskboardRoutesOp
             }
             return
           }
+          if (action === 'cancel') {
+            if (options.cancel === undefined) {
+              const f = fail('invalid_input', 'execution service unavailable')
+              json(res, f.res, 501)
+              return
+            }
+            const result = await options.cancel(id)
+            if (result.ok) json(res, { ok: true, value: { cancelled: true, executionId: result.executionId } }, 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) {
@@ -341,7 +369,6 @@ export function registerTaskboardRoutes(ctx: Context, options: TaskboardRoutesOp
         return
       }
 
-      void taskPath
       res.writeHead(404)
       res.end()
     } catch (error) {

package/src/host/scheduler.ts

@@ -9,7 +9,7 @@
  * @module dsh-taskboard/host/scheduler
  */
 import { nextCronTime, parseCron, type TaskLedger } from '../shared/protocol.ts'
-import type { ExecutionService } from './execution.ts'
+import { DEFAULT_MAX_CONCURRENT, type ExecutionService } from './execution.ts'
 import type { TaskStore } from './store.ts'
 
 /** Tick cadence. */
@@ -21,8 +21,10 @@ const SKIP_AFTER_MS = 5 * 60_000
 /** Everything the scheduler needs. */
 export interface SchedulerDeps {
   store: TaskStore
-  execution: Pick<ExecutionService, 'run'>
+  execution: Pick<ExecutionService, 'run' | 'inFlight'>
   now: () => number
+  /** Max concurrently running executions (default 3; must match the execution service). */
+  maxConcurrent?: number
   /** Timer face (injectable for tests). */
   timers?: {
     setInterval(fn: () => void, ms: number): unknown
@@ -35,6 +37,7 @@ export interface SchedulerDeps {
  */
 export class SchedulerService {
   private handle: unknown
+  private catchup: ReturnType<typeof setTimeout> | undefined
 
   /** @param deps - store + execution + clock. */
   constructor(private readonly deps: SchedulerDeps) {}
@@ -46,12 +49,17 @@ export class SchedulerService {
       clearInterval: (handle: unknown) => clearInterval(handle as ReturnType<typeof setInterval>),
     }
     this.handle = timers.setInterval(() => { void this.tick() }, TICK_MS)
-    // Catch up promptly on host restart: run one tick soon after start.
-    setTimeout(() => { void this.tick() }, 3_000)
+    // Catch up promptly on host restart: run one tick soon after start. The
+    // handle is cleared on dispose so a torn-down scheduler never fires.
+    this.catchup = setTimeout(() => { void this.tick() }, 3_000)
   }
 
   /** Stop ticking. */
   dispose(): void {
+    if (this.catchup !== undefined) {
+      clearTimeout(this.catchup)
+      this.catchup = undefined
+    }
     if (this.handle === undefined) return
     const timers = this.deps.timers ?? { clearInterval: (h: unknown) => clearInterval(h as ReturnType<typeof setInterval>) }
     timers.clearInterval(this.handle)
@@ -60,13 +68,21 @@ export class SchedulerService {
 
   /** One scheduler pass (exported for tests). */
   async tick(): Promise<void> {
+    // Load once before reading: snapshot() does not trigger a load, and the
+    // scheduler may be the first consumer after a host restart (otherwise it
+    // would tick over an empty ledger until something else loads it).
+    await this.deps.store.load()
     const now = this.deps.now()
     const ledger: TaskLedger = this.deps.store.snapshot()
+    const atCapacity = this.deps.execution.inFlight() >= (this.deps.maxConcurrent ?? DEFAULT_MAX_CONCURRENT)
     for (const task of ledger.tasks) {
       if (task.execution.mode !== 'scheduled' || task.execution.cron === undefined) continue
       if (task.execution.nextRunAt === undefined) continue
       if (task.status === 'in_progress' || task.trashedAt !== undefined) continue
       if (task.execution.nextRunAt > now) continue
+      // At the concurrency cap: leave nextRunAt in the past and retry next
+      // tick — advancing here would silently burn this window.
+      if (atCapacity) continue
       const missed = now - task.execution.nextRunAt > SKIP_AFTER_MS
 
       // Advance the schedule FIRST (idempotent under re-ticks), then run

package/src/host/store.ts

@@ -11,6 +11,7 @@ import { dirname, join } from 'node:path'
 import {
   LEDGER_SCHEMA_VERSION,
   emptyLedger,
+  pruneExecutions,
   type TaskLedger,
   type TaskRecord,
 } from '../shared/protocol.ts'
@@ -55,7 +56,18 @@ export class TaskStore {
       const raw = await readFile(this.file, 'utf8')
       const parsed = JSON.parse(raw) as TaskLedger
       if (typeof parsed.revision === 'number' && Array.isArray(parsed.tasks)) {
-        this.ledger = { schemaVersion: LEDGER_SCHEMA_VERSION, revision: parsed.revision, tasks: parsed.tasks }
+        const tasks = parsed.tasks as TaskRecord[]
+        // Migration from pre-claim-field ledgers: an agent-held in_progress
+        // task carried its holder in updatedBy — backfill the explicit claim
+        // fields so the hold survives user edits (updatedBy is audit-only).
+        for (const task of tasks) {
+          if (task.status === 'in_progress' && task.claimedBy === undefined
+            && task.updatedBy?.kind === 'agent' && typeof task.updatedBy.sessionId === 'string') {
+            task.claimedBy = task.updatedBy.sessionId
+            task.claimedAt = task.updatedAt
+          }
+        }
+        this.ledger = { schemaVersion: LEDGER_SCHEMA_VERSION, revision: parsed.revision, tasks }
       }
     } catch (error) {
       const code = (error as NodeJS.ErrnoException).code
@@ -70,14 +82,19 @@ export class TaskStore {
     this.loaded = true
   }
 
-  /** The current immutable snapshot. */
+  /**
+   * The current snapshot — a deep-frozen clone. Mutating the returned value
+   * throws (strict mode) instead of silently bypassing the revision/persist
+   * path; internal state is never handed out.
+   */
   snapshot(): TaskLedger {
-    return this.ledger
+    return deepFreeze(structuredClone(this.ledger))
   }
 
-  /** Find a task by id. */
+  /** Find a task by id (frozen clone; internal state is never handed out). */
   get(id: string): TaskRecord | undefined {
-    return this.ledger.tasks.find(t => t.id === id)
+    const task = this.ledger.tasks.find(t => t.id === id)
+    return task === undefined ? undefined : deepFreeze(structuredClone(task))
   }
 
   /** Subscribe to committed changes; returns the unsubscribe. */
@@ -103,6 +120,9 @@ export class TaskStore {
       if (changed === undefined) {
         return { ledger: this.ledger, changed: [] }
       }
+      // Retention cap: every committed mutation re-checks the touched tasks,
+      // so execution history can never grow unbounded (SSE state payload).
+      for (const task of changed) pruneExecutions(task)
       draft.revision += 1
       const json = JSON.stringify(draft)
       await persistAtomic(this.file, json)
@@ -118,16 +138,17 @@ export class TaskStore {
     const result = (this.queue = this.queue.then(run, run)) as ReturnType<typeof run>
     return result
   }
+}
 
-  /** Persist the current ledger now (used after external reconciliation). */
-  async flush(kind: LedgerChange['kind'], changed: readonly TaskRecord[]): Promise<void> {
-    await this.mutate(kind, (ledger) => {
-      // replace tasks wholesale from the live snapshot objects
-      const byId = new Map(this.ledger.tasks.map(t => [t.id, t]))
-      ledger.tasks = ledger.tasks.map(t => byId.get(t.id) ?? t)
-      return [...changed]
-    })
+/** Recursively freeze a plain-data value (defense in depth for handed-out snapshots). */
+function deepFreeze<T>(value: T): T {
+  if (value !== null && typeof value === 'object') {
+    if (!Object.isFrozen(value)) Object.freeze(value)
+    for (const key of Object.keys(value as Record<string, unknown>)) {
+      deepFreeze((value as Record<string, unknown>)[key])
+    }
   }
+  return value
 }
 
 /** Atomic file persist: write temp, then rename over the target. */