@linxin666/dsh-client-ui-task-board 0.4.3 → 0.4.5

package/src/host-ledger.ts

@@ -3,9 +3,9 @@ import { createHash } from 'node:crypto'
 import { chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { dshHome } from './dsh-home.ts'
-import { isValidCron, nextRunAtMs } from './core/schedule.ts'
+import { isValidCron, isValidTimeZone, nextRunAtMs, resolveHostTimeZone } from './core/schedule.ts'
 import { isTaskRecord, parseLedger } from './core/store.ts'
-import { canMoveManually, retainRecentExecutions, settleExecution, startExecution, withStatus, type ExecutionOutcome, type ExecutionRecord, type TaskRecord } from './core/tasks.ts'
+import { canMoveManually, hasOpenExecution, retainRecentExecutions, settleExecution, startExecution, withStatus, type ExecutionOutcome, type ExecutionRecord, type TaskRecord } from './core/tasks.ts'
 import {
   DEFAULT_SUBTASK_DEPTH,
   cascadeTargets,
@@ -20,9 +20,11 @@ import { applyCreateTask } from './core/use-cases/task-create.ts'
 import { applyDeleteTask } from './core/use-cases/task-delete.ts'
 import { applySetSchedule, applyScheduleNextRun } from './core/use-cases/task-schedule.ts'
 import { applySetParent } from './core/use-cases/task-parent.ts'
+import { applyDeleteTag, applyRenameTag } from './core/use-cases/task-tag.ts'
 import { applyUpdateTask, canEditTaskContent, hasContentPatch } from './core/use-cases/task-update.ts'
-import { TASK_BOARD_LEGACY_SCHEMA_VERSION, TASK_BOARD_SCHEMA_VERSION, type TaskBoardAction, type TaskBoardSchedulerSnapshot } from './protocol.ts'
-import { DEFAULT_SESSION_PERMISSION, requiresPermissionConfirmation, type TaskPermission } from './core/handover.ts'
+import { TASK_BOARD_MIGRATABLE_SCHEMA_VERSIONS, TASK_BOARD_SCHEMA_VERSION, type TaskBoardAction, type TaskBoardSchedulerSnapshot } from './protocol.ts'
+import type { ExecutionVerification } from './core/verification.ts'
+import { DEFAULT_SESSION_PERMISSION, effectivePermission, permissionCarriedBy, requiresPermissionConfirmation, type TaskPermission } from './core/handover.ts'
 
 interface PersistedScheduler extends TaskBoardSchedulerSnapshot {
   importedSources?: string[]
@@ -57,7 +59,7 @@ function bindingRefusalMessage(
   surface: 'run' | 'schedule',
 ): string {
   if (refusal.kind === 'subtask-pin') {
-    return `team run cannot honor the permission binding of subtask "${refusal.title}": a teammate runs inside the Lead session; clear that card's permission or run the tree without Agent Team`
+    return `team run cannot honor the permission binding of subtask "${refusal.title}": a teammate runs inside the Lead session and inherits its permission, which that pin exceeds; clear the card's permission or run the tree without Agent Team`
   }
   if (surface === 'schedule') return `task "${refusal.title}" has an unconfirmed above-default permission`
   if (refusal.kind === 'root') {
@@ -84,12 +86,21 @@ export interface OpenExecutionReference {
   readonly executionId: string
   readonly sessionId: string | undefined
   readonly startedAt: number
+  /**
+   * True for a member of a team-mode run other than its Lead. A teammate is a
+   * durable member of the Team: it stays alive after its turn ends, so the
+   * roster may keep reporting its session as running, and the turn it completed
+   * is the only verdict it exposes.
+   */
+  readonly teamMember: boolean
 }
 
 /** Minimal value copy used by the Host scheduler. */
 export interface DueScheduleReference {
   readonly taskId: string
   readonly cron: string
+  /** Zone this rule's wall clock is read in. */
+  readonly timeZone: string
   readonly nextRunAt: number
 }
 
@@ -106,15 +117,16 @@ interface CachedRequest {
 }
 
 function timeZone(): string {
-  return Intl.DateTimeFormat().resolvedOptions().timeZone || 'local'
+  return resolveHostTimeZone()
 }
 
-function cloneTasks(tasks: readonly TaskRecord[]): TaskRecord[] {
-  return JSON.parse(JSON.stringify(tasks)) as TaskRecord[]
+/** The zone a schedule is evaluated in: its own, or the Host zone when it stores none. */
+function scheduleZone(schedule: { timeZone?: string }): string {
+  return schedule.timeZone ?? timeZone()
 }
 
-function hasOpenExecution(task: TaskRecord): boolean {
-  return task.executions.some(execution => execution.endedAt === undefined)
+function cloneTasks(tasks: readonly TaskRecord[]): TaskRecord[] {
+  return JSON.parse(JSON.stringify(tasks)) as TaskRecord[]
 }
 
 /**
@@ -327,7 +339,17 @@ function mergeTask(a: TaskRecord, b: TaskRecord): TaskRecord {
     const previous = byId.get(entry.id)
     byId.set(entry.id, previous === undefined ? entry : betterExecution(previous, entry))
   }
-  const executions = [...byId.values()].sort((x, y) => x.startedAt - y.startedAt)
+  // Acceptance evidence is the one field "betterExecution" cannot choose: a
+  // browser half that also wrote this execution carries no attempts, and taking
+  // its copy would erase the Host's verdict. The copy with the most recorded
+  // attempts wins, and one execution's verdict is never copied onto another.
+  const executions = [...byId.values()].sort((x, y) => x.startedAt - y.startedAt).map(entry => {
+    if (entry.verification !== undefined) return entry
+    const richer = [...a.executions, ...b.executions]
+      .filter(other => other.id === entry.id && other.verification !== undefined)
+      .sort((x, y) => (y.verification?.attempts.length ?? 0) - (x.verification?.attempts.length ?? 0))[0]
+    return richer?.verification === undefined ? entry : { ...entry, verification: richer.verification }
+  })
   return { ...newer, executions: retainRecentExecutions(executions) }
 }
 
@@ -381,6 +403,7 @@ function parseHostTasks(values: readonly unknown[]): TaskRecord[] {
       schedule: {
         enabled: false,
         cron: schedule.cron,
+        ...(typeof schedule.timeZone === 'string' && isValidTimeZone(schedule.timeZone) ? { timeZone: schedule.timeZone } : {}),
         nextRunAt: undefined,
         lastTriggeredAt: typeof schedule.lastTriggeredAt === 'number' && Number.isFinite(schedule.lastTriggeredAt)
           ? schedule.lastTriggeredAt
@@ -401,8 +424,18 @@ export class HostTaskLedger {
   /** Small sidecar for the 30 s scheduler heartbeat (lastTickAt only). */
   readonly schedulerFile: string
 
-  /** Session-default permission the confirmation gate compares against. */
-  readonly sessionDefaultPermission: TaskPermission
+  /** Resolves the baseline the confirmation gate compares a binding against. */
+  private readonly sessionDefault: () => TaskPermission
+
+  /**
+   * Session-default permission the confirmation gate compares against. Read
+   * through the resolver on every use, so a baseline that follows the Host's
+   * own default preset tracks a Settings change made while the board runs.
+   */
+  get sessionDefaultPermission(): TaskPermission {
+    return this.sessionDefault()
+  }
+
   /**
    * Deployment subtask depth limit (1..3): the lineage gate every write obeys.
    * The settings card edits it live, so {@link setMaxSubtaskDepth} mutates it
@@ -410,8 +443,10 @@ export class HostTaskLedger {
    */
   private depthLimit: number
 
-  constructor(dir: string = join(dshHome(), 'task-board'), private readonly now: () => number = Date.now, options: { sessionDefaultPermission?: TaskPermission; maxSubtaskDepth?: number } = {}) {
-    this.sessionDefaultPermission = options.sessionDefaultPermission ?? DEFAULT_SESSION_PERMISSION
+  constructor(dir: string = join(dshHome(), 'task-board'), private readonly now: () => number = Date.now, options: { sessionDefaultPermission?: TaskPermission | (() => TaskPermission); maxSubtaskDepth?: number } = {}) {
+    // Resolved before the load/repair passes below: they can evaluate the gate.
+    const baseline = options.sessionDefaultPermission
+    this.sessionDefault = typeof baseline === 'function' ? baseline : () => baseline ?? DEFAULT_SESSION_PERMISSION
     this.depthLimit = normalizeSubtaskDepth(options.maxSubtaskDepth ?? DEFAULT_SUBTASK_DEPTH)
     mkdirSync(dir, { recursive: true })
     this.file = join(dir, 'ledger-v2.json')
@@ -426,6 +461,10 @@ export class HostTaskLedger {
       }
       this.repairSchedules(true)
       this.reconcileInterruptedStarts()
+      // Boot recovery also folds every already-decided run: a team run whose
+      // Lead recorded its verdict in an earlier process, and a lineage whose
+      // last settle never reached its parent, both leave the running column here.
+      this.finalizeReadyRuns(false)
       // Persist a freshly generated ledger identity and any recovery error
       // immediately, even when there are no tasks to trigger a later action.
       this.commit(false)
@@ -488,6 +527,15 @@ export class HostTaskLedger {
    */
   runtimeView(): LedgerRuntimeView {
     let armedSchedules = 0
+    // Run groups opened by a team-mode card: every other member of those groups
+    // runs as a teammate inside that card's Lead session.
+    const teamGroups = new Set<string>()
+    for (const task of this.document.tasks) {
+      if (task.teamRun !== true) continue
+      for (const execution of task.executions) {
+        if (execution.runGroupId !== undefined) teamGroups.add(execution.runGroupId)
+      }
+    }
     const openExecutions: OpenExecutionReference[] = []
     for (const task of this.document.tasks) {
       if (task.archivedAt === undefined && task.schedule?.enabled === true) armedSchedules += 1
@@ -501,6 +549,9 @@ export class HostTaskLedger {
           executionId: execution.id,
           sessionId: execution.sessionId,
           startedAt: execution.startedAt,
+          teamMember: task.teamRun !== true
+            && execution.runGroupId !== undefined
+            && teamGroups.has(execution.runGroupId),
         })
       }
     }
@@ -543,7 +594,7 @@ export class HostTaskLedger {
       if (task.archivedAt !== undefined) continue
       const schedule = task.schedule
       if (schedule === undefined || !schedule.enabled || schedule.nextRunAt === undefined || schedule.nextRunAt > now) continue
-      due.push({ taskId: task.id, cron: schedule.cron, nextRunAt: schedule.nextRunAt })
+      due.push({ taskId: task.id, cron: schedule.cron, timeZone: scheduleZone(schedule), nextRunAt: schedule.nextRunAt })
     }
     return due
   }
@@ -613,7 +664,7 @@ export class HostTaskLedger {
       rollForward()
       return []
     }
-    if (task.status === 'running' || hasOpenExecution(task)) {
+    if (hasOpenExecution(task)) {
       rollForward()
       return []
     }
@@ -626,7 +677,7 @@ export class HostTaskLedger {
       const schedule = task.schedule
       if (schedule === undefined || !schedule.enabled || schedule.nextRunAt === undefined || schedule.nextRunAt > now) return task
       changed = true
-      return { ...task, schedule: { ...schedule, nextRunAt: nextRunAtMs(schedule.cron, now) }, updatedAt: now }
+      return { ...task, schedule: { ...schedule, nextRunAt: nextRunAtMs(schedule.cron, now, scheduleZone(schedule)) }, updatedAt: now }
     })
     if (changed) this.commit()
   }
@@ -681,20 +732,48 @@ export class HostTaskLedger {
       })
       changed = true
     }
+    // A team run is governed by its Lead: the Lead's own outcome closes whatever
+    // the Team still holds open, so the tree can never wait on a teammate that
+    // will never report one.
+    if (task.teamRun === true
+      && this.closeTeamMembers(taskId, groupId, execution.ownResult ?? outcome, execution.ownError ?? error, now)) changed = true
     if (this.settleCascade(taskId, groupId, now)) changed = true
     if (changed) this.commit()
   }
 
   attachSession(taskId: string, executionId: string, sessionId: string): void {
     const now = this.now()
-    this.document.tasks = this.document.tasks.map(task => task.id !== taskId ? task : {
-      ...task,
+    const task = this.document.tasks.find(item => item.id === taskId)
+    // A run the Lead's verdict already closed keeps its record: attaching a
+    // session to a settled execution would rewrite history the Host no longer
+    // observes (a teammate spawn that resolved after its Team was closed).
+    if (task?.executions.find(entry => entry.id === executionId)?.endedAt !== undefined) return
+    this.document.tasks = this.document.tasks.map(item => item.id !== taskId ? item : {
+      ...item,
       updatedAt: now,
-      executions: task.executions.map(entry => entry.id === executionId ? { ...entry, sessionId } : entry),
+      executions: item.executions.map(entry => entry.id === executionId ? { ...entry, sessionId } : entry),
     })
     this.commit()
   }
 
+  allTasks(): readonly TaskRecord[] {
+    return this.document.tasks
+  }
+
+  getTask(id: string): TaskRecord | undefined {
+    return this.document.tasks.find(item => item.id === id)
+  }
+
+  saveTaskRecord(task: TaskRecord): void {
+    const exists = this.document.tasks.some(item => item.id === task.id)
+    if (exists) {
+      this.document.tasks = this.document.tasks.map(item => item.id === task.id ? task : item)
+    } else {
+      this.document.tasks = [...this.document.tasks, task]
+    }
+    this.commit()
+  }
+
   private apply(action: TaskBoardAction, initiator?: string): { state: LedgerState; runs?: OpenedRun[] } {
     const now = this.now()
     let runs: OpenedRun[] | undefined
@@ -717,17 +796,22 @@ export class HostTaskLedger {
           : `invalid cron disabled for task(s): ${invalidScheduleIds.join(', ')}`
         this.repairSchedules(true, false)
         this.reconcileInterruptedStarts(false)
+        // An imported document may carry a decided-but-open run; fold it in the
+        // same action (apply() commits once at the end).
+        this.finalizeReadyRuns(false)
         break
       }
       case 'create': {
         if (this.document.tasks.some(task => task.id === action.id)) throw new Error('task id already exists')
-        if (action.input.schedule?.enabled === true && (!isValidCron(action.input.schedule.cron) || nextRunAtMs(action.input.schedule.cron, now) === undefined)) {
+        if (action.input.schedule?.enabled === true && (!isValidCron(action.input.schedule.cron)
+          || !isValidTimeZone(action.input.schedule.timeZone ?? timeZone())
+          || nextRunAtMs(action.input.schedule.cron, now, action.input.schedule.timeZone ?? timeZone()) === undefined)) {
           throw new Error('invalid schedule')
         }
         const input = action.input.freeze === undefined || initiator === undefined || initiator === ''
           ? action.input
           : { ...action.input, freeze: { ...action.input.freeze, frozenBy: initiator } }
-        const result = applyCreateTask(this.document.tasks, input, now, action.id, this.maxSubtaskDepth)
+        const result = applyCreateTask(this.document.tasks, input, now, action.id, this.maxSubtaskDepth, timeZone())
         if (result.task === undefined) throw new Error(result.error ?? 'invalid task')
         this.document.tasks = [...result.tasks]
         break
@@ -755,7 +839,7 @@ export class HostTaskLedger {
       case 'delete': {
         const task = this.document.tasks.find(task => task.id === action.taskId)
         if (task === undefined) throw new Error('task not found')
-        if (task.status === 'running' || hasOpenExecution(task)) throw new Error('running task cannot be deleted')
+        if (hasOpenExecution(task)) throw new Error('running task cannot be deleted')
         // Subtasks keep their link: deleting the parent would leave dangling
         // children, so the user detaches or deletes them explicitly first.
         if (this.document.tasks.some(item => item.parentId === action.taskId)) {
@@ -774,7 +858,10 @@ export class HostTaskLedger {
         const task = this.document.tasks.find(item => item.id === action.taskId)
         if (task === undefined) throw new Error('task not found')
         if (task.archivedAt !== undefined) throw new Error('archived task is read-only')
-        if (task.status === 'running' || hasOpenExecution(task)) throw new Error('running task cannot be moved')
+        // The lock belongs to an open execution, not to the column: a card
+        // parked in 'running' by hand has no session and stays movable, while
+        // a card the runner is executing cannot be moved out from under it.
+        if (hasOpenExecution(task)) throw new Error('running task cannot be moved')
         if (!canMoveManually(task.status, action.status)) throw new Error('invalid manual status')
         this.document.tasks = this.document.tasks.map(item => item.id === action.taskId ? withStatus(item, action.status, now) : item)
         break
@@ -786,6 +873,34 @@ export class HostTaskLedger {
         this.document.tasks = [...result.tasks]
         break
       }
+      case 'settle': {
+        const task = this.document.tasks.find(item => item.id === action.taskId)
+        if (task === undefined) throw new Error('task not found')
+        if (task.archivedAt !== undefined) throw new Error('archived task is read-only')
+        if (!task.executions.some(entry => entry.endedAt === undefined)) throw new Error('task has no open execution')
+        // Force-close the executions this card governs. The verdict is
+        // 'cancelled', never 'succeeded': a card whose execution produced no
+        // evidence of a completed turn must not be recorded as finished work,
+        // and a cancelled settlement returns the card to the todo column so the
+        // operator can run it again. Nothing else clears a running card: move,
+        // archive and delete all refuse one, which is what made a stuck card
+        // unrecoverable from the board.
+        const reason = 'execution closed manually by '
+          + (initiator === undefined || initiator === '' ? 'the operator' : initiator)
+          + ': no verdict was recorded'
+        for (const member of cascadeTargets(this.document.tasks, action.taskId, this.maxSubtaskDepth)) {
+          for (const execution of member.executions) {
+            if (execution.endedAt !== undefined) continue
+            this.document.tasks = this.document.tasks.map(item => item.id !== member.id
+              ? item
+              : settleExecution(item, execution.id, 'cancelled', now, reason))
+          }
+        }
+        // Fold whatever became ready in the same action: an ancestor whose last
+        // member this closed leaves the running column with it.
+        this.finalizeReadyRuns(false)
+        break
+      }
       case 'restore': {
         if (this.subtreeHasOpenExecution(action.taskId)) throw new Error('running task cannot be restored')
         const result = applyRestoreTask(this.document.tasks, action.taskId, now, this.maxSubtaskDepth)
@@ -802,10 +917,22 @@ export class HostTaskLedger {
           : item)
         break
       }
+      case 'rename-tag': {
+        const result = applyRenameTag(this.document.tasks, action.from, action.to, now)
+        if (result.error !== undefined) throw new Error(result.error)
+        if (result.changed) this.document.tasks = [...result.tasks]
+        break
+      }
+      case 'delete-tag': {
+        const result = applyDeleteTag(this.document.tasks, action.name, now)
+        if (result.error !== undefined) throw new Error(result.error)
+        if (result.changed) this.document.tasks = [...result.tasks]
+        break
+      }
       case 'set-schedule': {
         const task = this.document.tasks.find(task => task.id === action.taskId)
         if (task?.archivedAt !== undefined) throw new Error('archived task is read-only')
-        const result = applySetSchedule(this.document.tasks, action.taskId, action.patch, now)
+        const result = applySetSchedule(this.document.tasks, action.taskId, action.patch, now, timeZone())
         if (!result.applied) throw new Error('invalid schedule')
         this.document.tasks = [...result.tasks]
         break
@@ -814,7 +941,7 @@ export class HostTaskLedger {
       case 'run': {
         const task = this.document.tasks.find(item => item.id === action.taskId)
         if (task?.archivedAt !== undefined) throw new Error('archived task is read-only')
-        if (task === undefined || task.status === 'running' || hasOpenExecution(task)) throw new Error('task is already running or missing')
+        if (task === undefined || hasOpenExecution(task)) throw new Error('task is already running or missing')
         // The confirmation gate judges the RESOLVED binding: a subtask that
         // inherits an elevated permission from its parent is exactly as
         // unconfirmed as the parent would be without its own stamp.
@@ -835,10 +962,12 @@ export class HostTaskLedger {
    *
    * A plain cascade launches one session per participant, so every participant
    * carries its own resolved binding and each one gates the run. A team run
-   * launches only the Lead session: the Lead's binding gates it, while a
-   * subtask's OWN above-default pin cannot be applied to a teammate and is
-   * refused instead of being silently dropped (an inherited binding is the
-   * Lead's own and stays allowed once the Lead is confirmed).
+   * launches only the Lead session: the Lead's binding gates it, and a
+   * teammate inherits that session's permission, so a subtask's OWN pin is
+   * refused exactly when the Lead session does not already carry it — the
+   * teammate could never be given that authority, and dropping the pin
+   * silently would misreport the work (an inherited binding is the Lead's own
+   * and stays allowed once the Lead is confirmed).
    * @param root - the task being run.
    * @returns the first refusal, or undefined when the run may start.
    */
@@ -849,12 +978,17 @@ export class HostTaskLedger {
       if (lead !== undefined && requiresPermissionConfirmation(lead, this.sessionDefaultPermission)) {
         return { kind: 'root', title: lead.title }
       }
-      // The raw record carries the subtask's OWN binding: the resolved
-      // participant above already folded the inherited one into its permission.
+      // The Lead session runs at the Lead's own binding, or at the deployment
+      // default when it pins none; a teammate inherits that permission and
+      // cannot be narrowed below it, so it carries a subtask pin when it is
+      // already at least as wide. The raw record carries the subtask's OWN
+      // binding: the resolved participant above already folded an inherited one
+      // into its permission.
+      const leadPermission = effectivePermission(lead ?? root) ?? this.sessionDefaultPermission
       const pinned = participants.find(participant => {
         if (participant.id === root.id) return false
         const raw = this.document.tasks.find(task => task.id === participant.id)
-        return raw !== undefined && requiresPermissionConfirmation(raw, this.sessionDefaultPermission)
+        return raw !== undefined && !permissionCarriedBy(leadPermission, effectivePermission(raw))
       })
       return pinned === undefined ? undefined : { kind: 'subtask-pin', title: pinned.title }
     }
@@ -873,14 +1007,13 @@ export class HostTaskLedger {
     return cascadeTargets(this.document.tasks, rootId, this.maxSubtaskDepth)
       .map(participant => resolveExecutionTargets(participant, this.document.tasks, this.maxSubtaskDepth))
       .filter(participant => participant.archivedAt === undefined
-        && participant.status !== 'running'
         && !hasOpenExecution(participant))
   }
 
   /** Whether a task or any of its subtasks still has an open execution. */
   private subtreeHasOpenExecution(id: string): boolean {
     return cascadeTargets(this.document.tasks, id, this.maxSubtaskDepth)
-      .some(task => task.status === 'running' || hasOpenExecution(task))
+      .some(task => hasOpenExecution(task))
   }
 
   /**
@@ -905,7 +1038,7 @@ export class HostTaskLedger {
     const runs: OpenedRun[] = []
     for (const task of cascadeTargets(before, root.id, this.maxSubtaskDepth)) {
       if (task.archivedAt !== undefined) continue
-      if (task.status === 'running' || hasOpenExecution(task)) continue
+      if (hasOpenExecution(task)) continue
       const base = rerun && task.id === root.id ? withStatus(task, 'todo', now) : task
       const opened = startExecution(base, now, crypto.randomUUID(), initiator, groupId)
       started.set(task.id, opened.task)
@@ -959,6 +1092,95 @@ export class HostTaskLedger {
     return changed
   }
 
+  /**
+   * Close every run that is already decided, and fold every lineage whose
+   * members are all settled. The Host poll calls this on every tick, so a run
+   * can no longer be left in the running column by a settle nobody observed:
+   *
+   * - A team run is governed by its Lead. Once the Lead's own outcome is
+   *   recorded, its still-open members are settled with that verdict. A
+   *   teammate is a durable member of the Team and may never report a turn of
+   *   its own, and without this the whole lineage waits on it forever.
+   * - A cascade parent whose members are all settled is finalized here even
+   *   when the settle that completed the tree happened in another process, or
+   *   was interrupted between its child write and its parent write.
+   *
+   * Idempotent: a run that is already folded is left untouched, so a caller may
+   * invoke it on every tick.
+   * @param persist - false to leave the document for the caller to commit.
+   * @returns whether the document changed.
+   */
+  finalizeReadyRuns(persist = true): boolean {
+    const now = this.now()
+    let changed = false
+    const groups = new Set<string>()
+    for (const task of this.document.tasks) {
+      for (const execution of task.executions) {
+        if (execution.endedAt === undefined && execution.runGroupId !== undefined) groups.add(execution.runGroupId)
+      }
+    }
+    for (const groupId of groups) {
+      const lead = this.document.tasks.find(task => task.teamRun === true
+        && task.executions.some(entry => entry.runGroupId === groupId))
+      const verdict = lead === undefined ? undefined : this.leadVerdict(lead, groupId)
+      if (lead !== undefined && verdict !== undefined
+        && this.closeTeamMembers(lead.id, groupId, verdict.result, verdict.error, now)) changed = true
+      // Fold the lineage: a member may itself be a parent of a deeper member.
+      for (const task of this.document.tasks) {
+        if (this.settleCascade(task.id, groupId, now)) changed = true
+      }
+    }
+    if (changed && persist) this.commit()
+    return changed
+  }
+
+  /**
+   * The verdict a team run's Lead has already recorded: its own turn outcome
+   * once that turn ended, or the folded outcome once its card settled.
+   */
+  private leadVerdict(lead: TaskRecord, groupId: string): { result: ExecutionOutcome; error: string | undefined } | undefined {
+    const execution = lead.executions.find(entry => entry.runGroupId === groupId)
+    const result = execution?.ownResult ?? execution?.result
+    if (result === undefined) return undefined
+    return { result, error: execution?.ownError ?? execution?.error }
+  }
+
+  /**
+   * Settle every still-open member of a team run with the Lead's verdict.
+   * A teammate that already reported its own outcome keeps it: the ordinary
+   * fold still lets a failure dominate.
+   * @param leadId - the Lead card's task id (never settled here).
+   * @param groupId - the team run's group.
+   * @param verdict - the Lead's outcome, inherited by members that never reported.
+   * @param error - the Lead's failure text, inherited with a failed verdict.
+   * @param now - clock instant (ms epoch).
+   * @returns whether the document changed.
+   */
+  private closeTeamMembers(leadId: string, groupId: string, verdict: ExecutionOutcome, error: string | undefined, now: number): boolean {
+    const members: string[] = []
+    let recorded = false
+    this.document.tasks = this.document.tasks.map(task => {
+      if (task.id === leadId) return task
+      const execution = openGroupExecution(task, groupId)
+      if (execution === undefined) return task
+      members.push(task.id)
+      if (execution.ownResult !== undefined) return task
+      recorded = true
+      return {
+        ...task,
+        updatedAt: now,
+        executions: task.executions.map(entry => entry.id === execution.id
+          ? { ...entry, ownResult: verdict, ownError: error }
+          : entry),
+      }
+    })
+    let changed = recorded
+    for (const memberId of members) {
+      if (this.settleCascade(memberId, groupId, now)) changed = true
+    }
+    return changed
+  }
+
   private repairSchedules(skipPast: boolean, persist = true): void {
     const now = this.now()
     let changed = false
@@ -966,7 +1188,7 @@ export class HostTaskLedger {
       const schedule = task.schedule
       if (schedule === undefined || !schedule.enabled) return task
       if (!skipPast && schedule.nextRunAt !== undefined) return task
-      const next = nextRunAtMs(schedule.cron, now)
+      const next = nextRunAtMs(schedule.cron, now, scheduleZone(schedule))
       if (next === undefined) {
         changed = true
         this.document.scheduler.error = `invalid cron disabled for task: ${task.id}`
@@ -984,7 +1206,6 @@ export class HostTaskLedger {
     let changed = false
     const interrupted: Array<{ taskId: string; runGroupId: string | undefined }> = []
     this.document.tasks = this.document.tasks.map(task => {
-      if (task.status !== 'running') return task
       const execution = task.executions.at(-1)
       if (execution === undefined || execution.endedAt !== undefined || execution.sessionId !== undefined) return task
       changed = true
@@ -1003,35 +1224,105 @@ export class HostTaskLedger {
   }
 
   /**
-   * Field-preserving v2 to v3 migration. v3 adds no fields yet, so the
-   * migration reuses the v3 normalization, but it first proves every task
-   * row is structurally valid: a v2 document that would silently drop or
-   * coerce rows fails loudly instead (no quarantined-empty restart).
+   * Field-preserving migration of an older document. It first proves every task
+   * row is structurally valid, so a document that would silently drop or coerce
+   * rows fails loudly instead (no quarantined-empty restart), and then reuses
+   * the current normalization.
+   *
+   * v4 adds `ScheduleRule.timeZone`. A rule written before v4 was evaluated in
+   * whatever zone the Host process happened to report, so the migration stamps
+   * that zone onto every enabled rule: the trigger instant is preserved exactly
+   * (the stored `nextRunAt` already encodes the old zone), but the rule stops
+   * following a later `TZ` change, which is what made an existing schedule
+   * silently move when the Host's zone changed.
+   *
+   * v5 adds the per-execution acceptance block. The migration deliberately does
+   * NOT stamp one: an execution opened before v5 keeps no contract, so it
+   * settles on its own historical verdict and no in-flight run is retroactively
+   * judged by a gate that was never armed for it.
    */
   private migrateLegacyDocument(parsed: ParsedLedgerDocument): LedgerDocument {
     if (!Array.isArray(parsed.tasks) || !parsed.tasks.every(row => isTaskRecord(row))) {
-      throw new Error('v2 document contains structurally invalid task rows')
+      throw new Error(`v${String(parsed.schemaVersion)} document contains structurally invalid task rows`)
+    }
+    // Every row passed `isTaskRecord` above, so the stamped rows are still
+    // task records; the cast only re-narrows the unknown-typed on-disk array.
+    const rows = (parsed.tasks as readonly unknown[]).map((value) => {
+      const row = value as { schedule?: unknown }
+      const schedule = row.schedule
+      if (typeof schedule !== 'object' || schedule === null) return value
+      if (typeof (schedule as { timeZone?: unknown }).timeZone === 'string') return value
+      return { ...(value as object), schedule: { ...(schedule as object), timeZone: timeZone() } }
+    })
+    return this.normalizeDocument({ ...parsed, tasks: rows as TaskRecord[] })
+  }
+
+  /**
+   * Find the still-open execution that ran in one session, with its task.
+   *
+   * The completion gate keys on the session id its tool call arrives from: the
+   * execution record is the only object binding a session to a card, and an
+   * already-settled execution is deliberately not returned (a session the board
+   * no longer owns must not be gated).
+   * @param sessionId - the DSH session the tool call runs in.
+   * @returns the open execution and its task, or undefined.
+   */
+  findOpenExecutionBySession(sessionId: string): { task: TaskRecord; execution: ExecutionRecord } | undefined {
+    if (sessionId === '') return undefined
+    for (const task of this.document.tasks) {
+      for (const execution of task.executions) {
+        if (execution.endedAt !== undefined) continue
+        if (execution.sessionId === sessionId) return { task, execution }
+      }
     }
-    return this.normalizeDocument(parsed)
+    return undefined
+  }
+
+  /**
+   * Replace one execution's acceptance block (creating it when absent).
+   *
+   * A no-op when the serialized value is unchanged, so a coarse caller that
+   * re-writes the same state never bumps the ledger revision. A settled
+   * execution keeps its record: the report of a finished cycle must survive,
+   * and only the board's own settlement moves the card.
+   * @param taskId - the task owning the execution.
+   * @param executionId - the execution to update.
+   * @param verification - the new block.
+   * @returns true when the ledger changed.
+   */
+  setVerification(taskId: string, executionId: string, verification: ExecutionVerification): boolean {
+    const now = this.now()
+    const task = this.document.tasks.find(item => item.id === taskId)
+    const execution = task?.executions.find(entry => entry.id === executionId)
+    if (task === undefined || execution === undefined) return false
+    if (JSON.stringify(execution.verification ?? null) === JSON.stringify(verification)) return false
+    this.document.tasks = this.document.tasks.map(item => item.id !== taskId ? item : {
+      ...item,
+      updatedAt: now,
+      executions: item.executions.map(entry => entry.id === executionId ? { ...entry, verification } : entry),
+    })
+    this.commit()
+    return true
   }
 
   private load(dir: string): LedgerDocument {
     const existed = existsSync(this.file)
-    // schemaVersion stays unknown-typed here: on-disk documents may be v2
-    // (legacy), v3, or any future/invalid value the branches below sort out.
+    // schemaVersion stays unknown-typed here: on-disk documents may be v2 or
+    // v3 (legacy), v4, or any future/invalid value the branches below sort out.
     let parsed: ParsedLedgerDocument
     try {
       parsed = JSON.parse(readFileSync(this.file, 'utf8')) as ParsedLedgerDocument
     } catch (error) {
       return this.recoverCorrupt(dir, existed, error)
     }
-    if (parsed.schemaVersion === TASK_BOARD_LEGACY_SCHEMA_VERSION) {
+    if (typeof parsed.schemaVersion === 'number'
+      && TASK_BOARD_MIGRATABLE_SCHEMA_VERSIONS.includes(parsed.schemaVersion)) {
       try {
         return this.migrateLegacyDocument(parsed)
       } catch (error) {
-        // Migration failure is explicit: the original v2 file stays in place
+        // Migration failure is explicit: the original file stays in place
         // for manual recovery and the ledger refuses to start (fail closed).
-        throw new Error(`ledger v2 to v3 migration failed; original file kept at ${this.file}: ${error instanceof Error ? error.message : String(error)}`)
+        throw new Error(`ledger v${String(parsed.schemaVersion)} to v${TASK_BOARD_SCHEMA_VERSION} migration failed; original file kept at ${this.file}: ${error instanceof Error ? error.message : String(error)}`)
       }
     }
     try {
@@ -1246,4 +1537,4 @@ export class HostTaskLedger {
     }
     throw new Error(`task-board ledger lock could not be acquired: ${this.lockFile}`)
   }
-}
+}