dsh-taskboard 0.5.0 → 0.5.2

package/src/host/tools.ts

@@ -46,6 +46,7 @@ import {
   syncClaim,
   type Actor,
   type ChecklistItem,
+  type TaskLedger,
   type TaskModel,
   type TaskRecord,
 } from '../shared/protocol.ts'
@@ -124,7 +125,7 @@ function taskDetail(t: TaskRecord & { effectivePrompt?: string }): string {
   } else {
     lines.push('执行记录: 无')
   }
-  const updatedBy = t.updatedBy.kind === 'agent' ? `agent ${String(t.updatedBy.sessionId).slice(0, 24)}` : 'user'
+  const updatedBy = t.updatedBy.kind === 'agent' ? `agent ${String(t.updatedBy.sessionId).slice(0, 24)}` : t.updatedBy.kind === 'system' ? 'system' : 'user'
   lines.push(`更新: ${new Date(t.updatedAt).toISOString()} 由 ${updatedBy}`)
   return lines.join('\n')
 }
@@ -140,8 +141,10 @@ export const ERR = {
   invalidInput: 'invalid_input',
 } as const
 
-/** Tool failure: an Error whose message starts with a stable code. */
-class ToolError extends Error {
+/** Tool failure: an Error whose message starts with a stable code. The code
+ *  is also carried structurally so the routes layer can map failures without
+ *  re-parsing messages (review P2). */
+export class ToolError extends Error {
   constructor(readonly code: string, detail: string) {
     super(`Error: ${code}: ${detail}`)
   }
@@ -223,6 +226,20 @@ function versionGuard(task: TaskRecord, ifVersion: number | undefined): void {
   }
 }
 
+/**
+ * Find a live (non-trashed) task INSIDE a mutator (R1: every guard must run
+ * on the fresh draft the serial queue hands us, never on a pre-read clone —
+ * a pre-read can pass its version check and then blind-overwrite a task that
+ * changed while the caller awaited). Throws not_found for missing/trashed.
+ */
+function liveTaskAt(ledger: TaskLedger, id: string): { index: number; task: TaskRecord } {
+  const index = ledger.tasks.findIndex(t => t.id === id)
+  if (index < 0) throw new ToolError(ERR.notFound, `no task ${id}`)
+  const task = ledger.tasks[index]!
+  if (task.trashedAt !== undefined) throw new ToolError(ERR.notFound, `no task ${id}`)
+  return { index, task }
+}
+
 /** Re-throw with a stable code; non-ToolErrors become invalid_input. */
 function fail(error: unknown): never {
   if (error instanceof ToolError) throw error
@@ -249,7 +266,7 @@ export interface ToolContextFace {
 }
 
 /**
- * Register all eight tools.
+ * Register all ten tools.
  * @param ctx - a context exposing `tools.register`.
  * @param deps - store + workspaces + clock.
  * @returns dispose functions, one per tool.
@@ -415,8 +432,8 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
         }
         const urgency = asUrgency(args.urgency)
         const status = args.status === undefined ? 'todo' as const : asStatus(args.status)
-        if (status === 'done' || status === 'archived') {
-          throw new ToolError(ERR.invalidTransition, 'a new task cannot start as done/archived')
+        if (status !== 'backlog' && status !== 'todo') {
+          throw new ToolError(ERR.invalidTransition, 'a new task must start as backlog or todo (in_progress requires claiming the task)')
         }
         const execution = normalizeExecution(args.execution ?? {}, deps.now())
         const model = args.model !== undefined ? checkModel(deps, args.model) : undefined
@@ -425,7 +442,10 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
         // existing tasks.
         const isolation = args.isolation === undefined ? defaultIsolationOf(store.snapshot().settings) : asIsolation(args.isolation)
         const presetId = args.presetId?.trim() || undefined
-        const checklist = args.checklist !== undefined ? checklistFromTexts(args.checklist) : undefined
+        // T9: match the GUI create route — trim and drop blank lines instead
+        // of failing the whole call over one empty string.
+        const checklistTexts = args.checklist?.map(c => c.trim()).filter(c => c.length > 0)
+        const checklist = checklistTexts !== undefined && checklistTexts.length > 0 ? checklistFromTexts(checklistTexts) : undefined
         const now = deps.now()
         const task: TaskRecord = {
           id: newTaskId(),
@@ -492,25 +512,27 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
     }, exec: unknown) {
       try {
         const { actor } = caller(exec as ToolRunContext)
-        const task = store.get(args.id)
-        if (task === undefined || task.trashedAt !== undefined) throw new ToolError(ERR.notFound, `no task ${args.id}`)
-        versionGuard(task, args.ifVersion)
-        if (task.status === 'archived') throw new ToolError(ERR.invalidTransition, 'archived tasks are immutable')
-        const next: TaskRecord = structuredClone(task)
-        if (args.title !== undefined) next.title = normalizeTitle(args.title)
-        if (args.description !== undefined) next.description = args.description.trim()
-        if (args.prompt !== undefined) next.prompt = normalizePrompt(args.prompt)
-        if (args.urgency !== undefined) next.urgency = asUrgency(args.urgency)
-        if (args.blocked !== undefined) next.blocked = args.blocked
-        next.version = task.version + 1
-        next.updatedAt = deps.now()
-        next.updatedBy = actor
+        // R1: lookup + version guard + write run inside the serial-queue
+        // mutation, on the fresh draft — a pre-read clone could pass its
+        // version check and then blind-overwrite a concurrent writer.
+        let next: TaskRecord | undefined
         await store.mutate('task-updated', ledger => {
-          const i = ledger.tasks.findIndex(t => t.id === args.id)
-          ledger.tasks[i] = next
+          const { index, task } = liveTaskAt(ledger, args.id)
+          versionGuard(task, args.ifVersion)
+          if (task.status === 'archived') throw new ToolError(ERR.invalidTransition, 'archived tasks are immutable')
+          next = structuredClone(task)
+          if (args.title !== undefined) next.title = normalizeTitle(args.title)
+          if (args.description !== undefined) next.description = args.description.trim()
+          if (args.prompt !== undefined) next.prompt = normalizePrompt(args.prompt)
+          if (args.urgency !== undefined) next.urgency = asUrgency(args.urgency)
+          if (args.blocked !== undefined) next.blocked = args.blocked
+          next.version = task.version + 1
+          next.updatedAt = deps.now()
+          next.updatedBy = actor
+          ledger.tasks[index] = next
           return [next]
         })
-        return json({ task: summarize(next) })
+        return json({ task: summarize(next!) })
       } catch (error) { fail(error) }
     },
   })) as () => void)
@@ -540,44 +562,47 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
       try {
         const { actor } = caller(exec as ToolRunContext)
         const to = asStatus(args.status)
-        const task = store.get(args.id)
-        if (task === undefined || task.trashedAt !== undefined) throw new ToolError(ERR.notFound, `no task ${args.id}`)
-        versionGuard(task, args.ifVersion)
+        // Claim boundary (policy gate): resolving the caller's workspace is
+        // async, so it happens BEFORE the mutation — the comparison runs INSIDE
+        // against the FRESH task (stronger than the old stale-clone compare).
+        const callerWsId = to === 'in_progress'
+          ? await callerWorkspace(deps, exec as ToolRunContext)
+          : undefined
+        // R1: every state guard + the write itself run inside the mutation.
+        let next: TaskRecord | undefined
+        await store.mutate('task-moved', ledger => {
+          const { index, task } = liveTaskAt(ledger, args.id)
+          versionGuard(task, args.ifVersion)
 
-        // Code-level gate: agents never complete a task.
-        if (to === 'done') {
-          throw new ToolError(ERR.forbidden, 'moving a task to done requires explicit user confirmation (GUI); agents cannot do it')
-        }
-        if (!canTransition(task.status, to)) {
-          throw new ToolError(ERR.invalidTransition, `illegal transition ${task.status} → ${to}`)
-        }
-        // Exclusive hold: while a task is in_progress under a session
-        // (explicit claimedBy — an agent claim or a live execution), no other
-        // session may move it (that would be a takeover).
-        if (task.status === 'in_progress' && task.claimedBy !== undefined && task.claimedBy !== actor.sessionId) {
-          throw new ToolError(ERR.forbidden, `task is held by session ${task.claimedBy}; never take over another session's claim`)
-        }
-        // Claim boundary: the calling session must belong to the task's project.
-        if (isClaim(task.status, to)) {
-          const wsId = await callerWorkspace(deps, exec as ToolRunContext)
-          if (wsId !== task.workspaceId) {
+          // Code-level gate: agents never complete a task.
+          if (to === 'done') {
+            throw new ToolError(ERR.forbidden, 'moving a task to done requires explicit user confirmation (GUI); agents cannot do it')
+          }
+          if (!canTransition(task.status, to)) {
+            throw new ToolError(ERR.invalidTransition, `illegal transition ${task.status} → ${to}`)
+          }
+          // Exclusive hold: while a task is in_progress under a session
+          // (explicit claimedBy — an agent claim or a live execution), no other
+          // session may move it (that would be a takeover).
+          if (task.status === 'in_progress' && task.claimedBy !== undefined && task.claimedBy !== actor.sessionId) {
+            throw new ToolError(ERR.forbidden, `task is held by session ${task.claimedBy}; never take over another session's claim`)
+          }
+          // Claim boundary: the calling session must belong to the task's project.
+          if (isClaim(task.status, to) && callerWsId !== task.workspaceId) {
             throw new ToolError(ERR.workspaceMismatch, 'only a session inside this task\'s project may claim it')
           }
-        }
-        const next: TaskRecord = structuredClone(task)
-        next.status = to
-        next.version = task.version + 1
-        next.updatedAt = deps.now()
-        next.updatedBy = actor
-        if (isClaim(task.status, to)) next.blocked = false
-        // Record the holder on a claim; every move out of in_progress releases it.
-        syncClaim(next, to, deps.now(), isClaim(task.status, to) ? actor.sessionId : undefined)
-        await store.mutate('task-moved', ledger => {
-          const i = ledger.tasks.findIndex(t => t.id === args.id)
-          ledger.tasks[i] = next
+          next = structuredClone(task)
+          next.status = to
+          next.version = task.version + 1
+          next.updatedAt = deps.now()
+          next.updatedBy = actor
+          if (isClaim(task.status, to)) next.blocked = false
+          // Record the holder on a claim; every move out of in_progress releases it.
+          syncClaim(next, to, deps.now(), isClaim(task.status, to) ? actor.sessionId : undefined)
+          ledger.tasks[index] = next
           return [next]
         })
-        return json({ task: summarize(next) })
+        return json({ task: summarize(next!) })
       } catch (error) { fail(error) }
     },
   })) as () => void)
@@ -610,8 +635,6 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
     async execute(args: { id: string; body: string }, exec: unknown) {
       try {
         const { sessionId } = caller(exec as ToolRunContext)
-        const task = store.get(args.id)
-        if (task === undefined || task.trashedAt !== undefined) throw new ToolError(ERR.notFound, `no task ${args.id}`)
         const comment = {
           id: newCommentId(),
           body: normalizeBody(args.body),
@@ -619,16 +642,21 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
           createdAt: deps.now(),
           threadId: sessionId,
         }
-        const next: TaskRecord = structuredClone(task)
-        next.comments.push(comment)
-        next.version = task.version + 1
-        next.updatedAt = deps.now()
+        // R1: find + append inside the mutation (no ifVersion by design —
+        // comments are append-only — but the write must not clobber a task
+        // that changed while we were queued).
+        let next: TaskRecord | undefined
         await store.mutate('comment-added', ledger => {
-          const i = ledger.tasks.findIndex(t => t.id === args.id)
-          ledger.tasks[i] = next
+          const { index, task } = liveTaskAt(ledger, args.id)
+          if (task.status === 'archived') throw new ToolError(ERR.invalidTransition, 'archived tasks are immutable')
+          next = structuredClone(task)
+          next.comments.push(comment)
+          next.version = task.version + 1
+          next.updatedAt = deps.now()
+          ledger.tasks[index] = next
           return [next]
         })
-        return json({ comment, task: { id: next.id, version: next.version, status: next.status } })
+        return json({ comment, task: { id: next!.id, version: next!.version, status: next!.status } })
       } catch (error) { fail(error) }
     },
   })) as () => void)
@@ -682,15 +710,23 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
     async execute(args: { id: string; ifVersion: number }, exec: unknown) {
       try {
         caller(exec as ToolRunContext)
-        const task = store.get(args.id)
-        if (task === undefined) throw new ToolError(ERR.notFound, `no task ${args.id}`)
-        versionGuard(task, args.ifVersion)
-        const next: TaskRecord = structuredClone(task)
-        next.trashedAt = deps.now()
-        next.version = task.version + 1
+        // R1: guards inside the mutation. S5: a running execution keeps
+        // writing to the task (report, settlement) — refuse the soft-delete
+        // until it is cancelled or settled. T8: clear claim residue.
+        let next: TaskRecord | undefined
         await store.mutate('task-deleted', ledger => {
-          const i = ledger.tasks.findIndex(t => t.id === args.id)
-          ledger.tasks[i] = next
+          const { index, task } = liveTaskAt(ledger, args.id)
+          versionGuard(task, args.ifVersion)
+          if (task.executions.some(e => e.outcome === 'running')) {
+            throw new ToolError(ERR.invalidInput, '任务有正在运行的执行（先在 GUI 取消或等它结束再删除）')
+          }
+          next = structuredClone(task)
+          next.trashedAt = deps.now()
+          next.version = task.version + 1
+          delete next.claimedBy
+          delete next.claimedAt
+          next.blocked = false
+          ledger.tasks[index] = next
           return [next]
         })
         return { trashed: true }
@@ -739,57 +775,57 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
     }, exec: unknown) {
       try {
         const { actor } = caller(exec as ToolRunContext)
-        const task = store.get(args.id)
-        if (task === undefined || task.trashedAt !== undefined) throw new ToolError(ERR.notFound, `no task ${args.id}`)
-        versionGuard(task, args.ifVersion)
-        if (task.status === 'archived') throw new ToolError(ERR.invalidTransition, 'archived tasks are immutable')
-        const next: TaskRecord = structuredClone(task)
-        const checklist: ChecklistItem[] = next.checklist === undefined ? [] : [...next.checklist]
-
-        if (args.action === 'add') {
-          const texts = args.items ?? []
-          if (texts.length === 0 || texts.length > 10) {
-            throw new ToolError(ERR.invalidInput, 'items must carry 1..10 texts per add call')
-          }
-          if (checklist.length + texts.length > MAX_CHECKLIST_ITEMS) {
-            throw new ToolError(ERR.invalidInput, `checklist may hold at most ${MAX_CHECKLIST_ITEMS} items (currently ${checklist.length})`)
+        // R1: guards + the checklist edit itself run inside the mutation.
+        let next: TaskRecord | undefined
+        await store.mutate('task-updated', ledger => {
+          const { index, task } = liveTaskAt(ledger, args.id)
+          versionGuard(task, args.ifVersion)
+          if (task.status === 'archived') throw new ToolError(ERR.invalidTransition, 'archived tasks are immutable')
+          next = structuredClone(task)
+          const checklist: ChecklistItem[] = next.checklist === undefined ? [] : [...next.checklist]
+
+          if (args.action === 'add') {
+            const texts = args.items ?? []
+            if (texts.length === 0 || texts.length > 10) {
+              throw new ToolError(ERR.invalidInput, 'items must carry 1..10 texts per add call')
+            }
+            if (checklist.length + texts.length > MAX_CHECKLIST_ITEMS) {
+              throw new ToolError(ERR.invalidInput, `checklist may hold at most ${MAX_CHECKLIST_ITEMS} items (currently ${checklist.length})`)
+            }
+            checklist.push(...checklistFromTexts(texts))
+          } else if (args.action === 'check') {
+            if (args.itemId === undefined) throw new ToolError(ERR.invalidInput, 'itemId is required for check')
+            const item = checklist.find(i => i.id === args.itemId)
+            if (item === undefined) throw new ToolError(ERR.notFound, `no checklist item ${args.itemId} (task ${args.id})`)
+            const note = args.note !== undefined && args.note.trim().length > 0 ? args.note.trim().slice(0, 400) : undefined
+            item.checked = true
+            item.checkedBy = actor.sessionId
+            item.checkedAt = deps.now()
+            if (note !== undefined) item.note = note
+          } else if (args.action === 'uncheck') {
+            if (args.itemId === undefined) throw new ToolError(ERR.invalidInput, 'itemId is required for uncheck')
+            const item = checklist.find(i => i.id === args.itemId)
+            if (item === undefined) throw new ToolError(ERR.notFound, `no checklist item ${args.itemId} (task ${args.id})`)
+            item.checked = false
+            delete item.checkedBy
+            delete item.checkedAt
+            delete item.note
+          } else {
+            throw new ToolError(ERR.invalidInput, `action must be add | check | uncheck (got "${args.action}")`)
           }
-          checklist.push(...checklistFromTexts(texts))
-        } else if (args.action === 'check') {
-          if (args.itemId === undefined) throw new ToolError(ERR.invalidInput, 'itemId is required for check')
-          const item = checklist.find(i => i.id === args.itemId)
-          if (item === undefined) throw new ToolError(ERR.notFound, `no checklist item ${args.itemId} (task ${args.id})`)
-          const note = args.note !== undefined && args.note.trim().length > 0 ? args.note.trim().slice(0, 400) : undefined
-          item.checked = true
-          item.checkedBy = actor.sessionId
-          item.checkedAt = deps.now()
-          if (note !== undefined) item.note = note
-        } else if (args.action === 'uncheck') {
-          if (args.itemId === undefined) throw new ToolError(ERR.invalidInput, 'itemId is required for uncheck')
-          const item = checklist.find(i => i.id === args.itemId)
-          if (item === undefined) throw new ToolError(ERR.notFound, `no checklist item ${args.itemId} (task ${args.id})`)
-          item.checked = false
-          delete item.checkedBy
-          delete item.checkedAt
-          delete item.note
-        } else {
-          throw new ToolError(ERR.invalidInput, `action must be add | check | uncheck (got "${args.action}")`)
-        }
 
-        if (checklist.length > 0) next.checklist = checklist
-        else delete next.checklist
-        next.version = task.version + 1
-        next.updatedAt = deps.now()
-        next.updatedBy = actor
-        await store.mutate('task-updated', ledger => {
-          const i = ledger.tasks.findIndex(t => t.id === args.id)
-          ledger.tasks[i] = next
+          if (checklist.length > 0) next.checklist = checklist
+          else delete next.checklist
+          next.version = task.version + 1
+          next.updatedAt = deps.now()
+          next.updatedBy = actor
+          ledger.tasks[index] = next
           return [next]
         })
-        const progress = next.checklist !== undefined
-          ? { done: next.checklist.filter(i => i.checked).length, total: next.checklist.length }
+        const progress = next!.checklist !== undefined
+          ? { done: next!.checklist.filter(i => i.checked).length, total: next!.checklist.length }
           : { done: 0, total: 0 }
-        return json({ task: { id: next.id, version: next.version }, checklist: next.checklist ?? [], ...progress })
+        return json({ task: { id: next!.id, version: next!.version }, checklist: next!.checklist ?? [], ...progress })
       } catch (error) { fail(error) }
     },
   })) as () => void)
@@ -800,7 +836,8 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
     description:
       'Submit the structured execution report for the task you are currently executing (summary / changed '
       + 'files / how you verified / artifacts / remaining risk). Submit BEFORE moving the task to in_review; '
-      + 'a later submission overwrites the previous report. Commits and diffs are host-collected — do not repeat them.',
+      + 'a later submission overwrites the previous report. If your run already settled, you may back-submit '
+      + 'onto your latest succeeded execution while you still hold the task. Commits and diffs are host-collected.',
     parameters: {
       summary: { type: 'string', required: true, description: 'What was done (1..2000 chars).' },
       changedFiles: {
@@ -842,8 +879,8 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
       try {
         const { sessionId } = caller(exec as ToolRunContext)
         const report = normalizeExecutionReport(args)
-        // Locate the RUNNING execution this session owns — reports attach to
-        // the live run, so the agent never needs to know execution ids.
+        // Path 1 (unchanged): attach to the RUNNING execution this session
+        // owns — reports ride the live run, so the agent never needs ids.
         let taskId: string | undefined
         let executionId: string | undefined
         await store.mutate('execution-recorded', ledger => {
@@ -858,8 +895,28 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
           }
           return undefined
         })
+        // Path 2 (review follow-up, P2): back-submit onto a session-owned
+        // SETTLED execution — the main conversation claims tasks directly and
+        // has no live run. Allowed when the session holds the task or owns
+        // its latest successful execution; never touches anyone else's runs.
+        if (taskId === undefined || executionId === undefined) {
+          await store.mutate('execution-recorded', ledger => {
+            for (const task of ledger.tasks) {
+              if (task.trashedAt !== undefined || task.status === 'archived') continue
+              const last = task.executions[task.executions.length - 1]
+              const owned = last !== undefined && last.sessionId === sessionId && last.outcome === 'succeeded'
+              const holds = task.claimedBy === sessionId && last !== undefined && last.sessionId === sessionId
+              if (!owned && !holds) continue
+              last!.report = report
+              taskId = task.id
+              executionId = last!.id
+              return [task]
+            }
+            return undefined
+          })
+        }
         if (taskId === undefined || executionId === undefined) {
-          throw new ToolError(ERR.forbidden, 'no running execution belongs to this session — the report can only be submitted while the taskboard execution session is still running')
+          throw new ToolError(ERR.forbidden, 'no running execution and no settled execution of yours to report on — reports attach to your running execution, or back-submit onto your latest succeeded one while you hold the task')
         }
         return json({ taskId, executionId, report })
       } catch (error) { fail(error) }

package/src/index.ts

@@ -1,7 +1,7 @@
 /**
  * Host loader entry for dsh-taskboard.
  *
- * Wiring: the ledger store (one JSON file under the DSH home), the eight
+ * Wiring: the ledger store (one JSON file under the DSH home), the ten
  * `taskboard_*` agent tools, the agent workflow-protocol system-prompt
  * section, the /taskboard JSON+SSE routes (when a webServer is served),
  * the host execution service (fresh in-project sessions, pinned models), and
@@ -48,6 +48,12 @@ export const inject = ['tools', 'systemPrompt']
 export function apply(ctx: Context): void {
   const store = new TaskStore({ file: dshHomePath(LEDGER_FILE) })
   const templates = new TemplateStore(dshHomePath(TEMPLATES_FILE))
+  // Eager first load: the tools and most routes read snapshot()/get() without
+  // triggering the lazy load, so a fresh boot used to serve an EMPTY board to
+  // taskboard_list/get until the scheduler catchup tick or the first
+  // GET /state happened to load the file (review P0). load() never throws —
+  // a corrupt ledger is quarantined instead.
+  void store.load()
   const now = () => Date.now()
   // Global execution concurrency cap (DSH_TASKBOARD_MAX_CONCURRENT overrides).
   const maxConcurrent = Math.max(1, Number.parseInt(process.env.DSH_TASKBOARD_MAX_CONCURRENT ?? '', 10) || DEFAULT_MAX_CONCURRENT)
@@ -173,6 +179,9 @@ export function apply(ctx: Context): void {
       const scheduler = new SchedulerService({ store, execution, now, maxConcurrent })
       scheduler.start()
       disposers.push(() => scheduler.dispose())
+      // Detach the settlement listener with the plugin — a hot reload must
+      // not leave stale services reacting to turn/end errors (review P1).
+      disposers.push(() => execution.dispose())
 
       return () => {
         disposeRoutes?.()

package/src/shared/api.ts

@@ -195,6 +195,6 @@ export type SummaryResponse = { tasks: TaskSummary[] }
 /** Change frame pushed on every committed ledger mutation. */
 export type ChangeEvent = {
   revision: number
-  kind: 'task-created' | 'task-updated' | 'task-moved' | 'task-deleted' | 'comment-added' | 'execution-recorded'
+  kind: 'task-created' | 'task-updated' | 'task-moved' | 'task-deleted' | 'comment-added' | 'execution-recorded' | 'settings-updated' | 'ledger-replaced'
   tasks: TaskSummary[]
 }

package/src/shared/protocol.ts

@@ -286,6 +286,7 @@ export function nextCronTime(match: CronMatch, from: number): number | null {
 export type Actor =
   | { kind: 'user' }
   | { kind: 'agent'; sessionId: string }
+  | { kind: 'system' }
 
 /** A progress/report comment on a task. */
 export type CommentRecord = {
@@ -479,6 +480,16 @@ function suffix(): string {
   return Math.random().toString(36).slice(2, 8)
 }
 
+/**
+ * Legal task id charset (R4): `t-<base36>-<base36>` from {@link newTaskId},
+ * and the ONLY shape accepted from the outside (import) or used to build
+ * filesystem paths (worktree dirs). Ids ride into `join(ws, '.dsh-worktrees',
+ * id)` — a lax charset here is an arbitrary-directory delete primitive.
+ */
+export function isValidTaskId(id: string): boolean {
+  return /^[A-Za-z0-9][A-Za-z0-9_-]{0,99}$/.test(id)
+}
+
 /** Mint a task id. */
 export function newTaskId(): string {
   return `t-${Date.now().toString(36)}-${suffix()}`
@@ -811,7 +822,10 @@ export function validateImportedTask(raw: unknown, now: number): { ok: true; tas
   const e = raw as Record<string, unknown>
   const id = typeof e.id === 'string' ? e.id.trim() : ''
   const fail = (reason: string): { ok: false; reason: string } => ({ ok: false, reason })
-  if (id.length === 0 || id.length > 100) return fail('missing/invalid id')
+  // R4①: length alone let traversal-shaped ids (`../../x`, `..\..\x`) into
+  // the ledger; the charset gate is the primary defense for every downstream
+  // filesystem use of a task id.
+  if (!isValidTaskId(id)) return fail('missing/invalid id (must match ^[A-Za-z0-9][A-Za-z0-9_-]{0,99}$)')
   try {
     const execution = normalizeExecution(
       typeof e.execution === 'object' && e.execution !== null ? e.execution as { mode?: string; cron?: string } : {},
@@ -909,6 +923,26 @@ export function validateImportedTask(raw: unknown, now: number): { ok: true; tas
   }
 }
 
+/**
+ * Minimal structural check for ONE ledger record at load time (S11): unlike
+ * {@link validateImportedTask} this REBUILDS NOTHING (cron state, ids and
+ * timestamps must survive a load untouched) — it only rejects entries whose
+ * shape would break downstream consumers, including the R4 id charset.
+ * @param raw - the untyped record.
+ */
+export function isPlausibleTaskRecord(raw: unknown): boolean {
+  if (typeof raw !== 'object' || raw === null) return false
+  const t = raw as Record<string, unknown>
+  return typeof t.id === 'string' && isValidTaskId(t.id)
+    && typeof t.title === 'string' && t.title.length > 0
+    && typeof t.workspaceId === 'string' && t.workspaceId.length > 0
+    && ALL_STATUSES.includes(t.status as TaskStatus)
+    && typeof t.version === 'number' && Number.isFinite(t.version) && t.version >= 1
+    && Array.isArray(t.comments) && Array.isArray(t.executions)
+    && typeof t.execution === 'object' && t.execution !== null
+    && (t.execution as { mode?: unknown }).mode !== undefined
+}
+
 /**
  * Validate a whole imported ledger and classify its tasks against the live
  * one (pure). Duplicate ids INSIDE the file are invalid (first wins, later

package/src/shared/version.ts

@@ -6,4 +6,4 @@
  */
 
 /** The package version (must equal package.json "version"). */
-export const PLUGIN_VERSION = '0.5.0'
+export const PLUGIN_VERSION = '0.5.2'

package/src/client/board/NewTaskModal.tsx

@@ -1,8 +0,0 @@
-/**
- * Compatibility shim: the composer moved into TaskFormModal (create + edit
- * in one dialog). Kept so existing imports keep working.
- *
- * @module dsh-taskboard/client/board/NewTaskModal
- */
-export { TaskFormModal as NewTaskModal } from './TaskFormModal.tsx'
-export type { CatalogModel } from './TaskFormModal.tsx'