@linxin666/dsh-client-ui-task-board 0.4.4 → 0.4.6

package/src/host-ledger.ts

@@ -5,7 +5,7 @@ import { dirname, join } from 'node:path'
 import { dshHome } from './dsh-home.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, scheduleExhausted, scheduleRunBudget, settleExecution, settledStatus, startExecution, withSchedule, withStatus, type ExecutionOutcome, type ExecutionRecord, type ScheduleMode, type ScheduleStopReason, type TaskRecord } from './core/tasks.ts'
 import {
   DEFAULT_SUBTASK_DEPTH,
   cascadeTargets,
@@ -18,11 +18,13 @@ import {
 import { applyArchiveTask, applyRestoreTask } from './core/use-cases/task-archive.ts'
 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 { applySetSchedule, applyScheduleProgress, applyScheduleRefund, type ScheduleProgress } 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_OLDER_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, TASK_BOARD_ZONE_STAMP_SCHEMA_VERSION, type TaskBoardAction, type TaskBoardSchedulerSnapshot } from './protocol.ts'
+import { withoutAcceptanceAnomalies, 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') {
@@ -96,7 +98,10 @@ export interface OpenExecutionReference {
 /** Minimal value copy used by the Host scheduler. */
 export interface DueScheduleReference {
   readonly taskId: string
-  readonly cron: string
+  /** Whether this due rule is a recurring cron rule or a single planned instant. */
+  readonly mode: ScheduleMode
+  /** Cron expression of a recurring rule; absent on a one-shot. */
+  readonly cron?: string
   /** Zone this rule's wall clock is read in. */
   readonly timeZone: string
   readonly nextRunAt: number
@@ -106,6 +111,24 @@ export interface DueScheduleReference {
 export interface LedgerRuntimeView {
   readonly armedSchedules: number
   readonly openExecutions: readonly OpenExecutionReference[]
+  /**
+   * Session ids of every open execution, including the ones
+   * {@link openExecutions} skips because their own outcome is already
+   * recorded. A caller that asks whether the board still observes any session
+   * must use this list: a deferred cascade parent is settled by its members,
+   * but it is still an open execution.
+   */
+  readonly openSessionIds: readonly string[]
+  /**
+   * Whether this document holds anything the session roster can still decide:
+   * an open execution that needs inspecting, or a card in the running column
+   * whose verdict may arrive from a settle this process never saw.
+   *
+   * A board with no running card, no open execution and no armed schedule has
+   * no use for the roster at all, which is what lets the Host poll stand down
+   * instead of re-reading every persisted session forever.
+   */
+  readonly needsSessionState: boolean
 }
 
 const MAX_REQUEST_CACHE = 256
@@ -123,12 +146,25 @@ function scheduleZone(schedule: { timeZone?: string }): string {
   return schedule.timeZone ?? timeZone()
 }
 
-function cloneTasks(tasks: readonly TaskRecord[]): TaskRecord[] {
-  return JSON.parse(JSON.stringify(tasks)) as TaskRecord[]
-}
-
-function hasOpenExecution(task: TaskRecord): boolean {
-  return task.executions.some(execution => execution.endedAt === undefined)
+/**
+ * The task collection one board read hands out.
+ *
+ * A read must not hand a consumer the ledger's own array: the state route, every
+ * action response and the agent tools all receive this value in-process, so an
+ * in-place rewrite of that array (splice, sort, push, `length = 0`) would edit
+ * the authoritative document from outside the write path. One level of copying
+ * is what that contract needs, and it is all it needs: every write in this class
+ * replaces the document's array (`this.document.tasks = ...`) and replaces the
+ * records it changes rather than mutating them, so the records a caller receives
+ * are stable values. Copying them as well only rebuilt the entire document on
+ * every board read - measured at 0.43 ms per read for 400 cards with 2
+ * executions each and 2.72 ms for 400 cards with 20 - and bought nothing a
+ * consumer relies on. Callers still must not mutate a record in place; that is
+ * what the shared record objects now make possible, and no consumer in this
+ * package does it.
+ */
+function tasksForRead(tasks: readonly TaskRecord[]): TaskRecord[] {
+  return [...tasks]
 }
 
 /**
@@ -341,7 +377,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) }
 }
 
@@ -389,17 +435,24 @@ function parseHostTasks(values: readonly unknown[]): TaskRecord[] {
     const rawSchedule = rawById.get(task.id)?.schedule
     if (typeof rawSchedule !== 'object' || rawSchedule === null) return task
     const schedule = rawSchedule as Record<string, unknown>
+    // A one-shot carries no cron; its instant is validated by the wire gate and
+    // the store repair, so there is nothing to salvage here.
+    if (schedule.mode === 'once') return task
     if (typeof schedule.cron !== 'string' || isValidCron(schedule.cron)) return task
     return {
       ...task,
       schedule: {
         enabled: false,
+        mode: 'cron',
         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
           : undefined,
+        runCount: typeof schedule.runCount === 'number' && Number.isInteger(schedule.runCount) && schedule.runCount >= 0
+          ? schedule.runCount
+          : 0,
       },
     }
   })
@@ -416,8 +469,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
@@ -425,8 +488,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')
@@ -497,16 +562,17 @@ export class HostTaskLedger {
 
   state(): LedgerState {
     const { revision, scheduler } = this.summary()
-    return { revision, tasks: cloneTasks(this.document.tasks), scheduler }
+    return { revision, tasks: tasksForRead(this.document.tasks), scheduler }
   }
 
   /**
-   * Runtime-only projection for the 5 s Host poll. It copies just primitive
+   * Runtime-only projection for the Host poll. It copies just primitive
    * identifiers and timestamps, never the complete task/execution history or
    * an authoritative mutable object from the ledger.
    */
   runtimeView(): LedgerRuntimeView {
     let armedSchedules = 0
+    let runningCards = 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>()
@@ -517,10 +583,13 @@ export class HostTaskLedger {
       }
     }
     const openExecutions: OpenExecutionReference[] = []
+    const openSessionIds: string[] = []
     for (const task of this.document.tasks) {
       if (task.archivedAt === undefined && task.schedule?.enabled === true) armedSchedules += 1
+      if (task.status === 'running') runningCards += 1
       for (const execution of task.executions) {
         if (execution.endedAt !== undefined) continue
+        if (execution.sessionId !== undefined) openSessionIds.push(execution.sessionId)
         // A deferred cascade parent already knows its own outcome; the monitor
         // has nothing left to inspect, and its children's settles finalize it.
         if (execution.ownResult !== undefined) continue
@@ -535,7 +604,12 @@ export class HostTaskLedger {
         })
       }
     }
-    return { armedSchedules, openExecutions }
+    return {
+      armedSchedules,
+      openExecutions,
+      openSessionIds,
+      needsSessionState: openExecutions.length > 0 || runningCards > 0,
+    }
   }
 
   /** Count armed, non-archived schedules without cloning task histories. */
@@ -574,7 +648,13 @@ 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, timeZone: scheduleZone(schedule), nextRunAt: schedule.nextRunAt })
+      due.push({
+        taskId: task.id,
+        mode: schedule.mode,
+        ...(schedule.cron === undefined ? {} : { cron: schedule.cron }),
+        timeZone: scheduleZone(schedule),
+        nextRunAt: schedule.nextRunAt,
+      })
     }
     return due
   }
@@ -626,38 +706,140 @@ export class HostTaskLedger {
   /**
    * Open the cascade one due schedule triggers: an empty array means nothing
    * ran (already running, or a participant whose elevated permission is still
-   * unconfirmed), and the rule rolls to its next occurrence either way.
+   * unconfirmed, a one-shot whose instant was missed, or an exhausted budget),
+   * and the rule's own state says which.
+   *
+   * The run budget is enforced HERE, inside the single ledger writer: a rule
+   * whose counter already reached its cap is stopped instead of opened, so no
+   * restart, repeated timer fire or re-arm can overrun it.
+   * @param taskId - the task whose rule came due.
+   * @param triggeredAt - the instant the occurrence came due.
+   * @returns the executions this occurrence opened.
    */
-  openScheduled(taskId: string, nextRunAt: number | undefined, triggeredAt: number): OpenedRun[] {
+  openScheduled(taskId: string, triggeredAt: number): OpenedRun[] {
     const task = this.document.tasks.find(item => item.id === taskId)
     if (task === undefined || task.archivedAt !== undefined) return []
-    const rollForward = (): void => {
-      this.document.tasks = [...applyScheduleNextRun(this.document.tasks, taskId, nextRunAt, task.schedule?.lastTriggeredAt, triggeredAt)]
-      this.commit()
+    const schedule = task.schedule
+    if (schedule === undefined || !schedule.enabled) return []
+
+    // A rule that has spent its budget never opens another run. The stop is
+    // recorded here rather than trusted to the firing timer, so a rule that
+    // was hand-edited into an exhausted state still terminates visibly.
+    if (scheduleExhausted(schedule)) {
+      this.progressSchedule(taskId, {
+        consumed: 0,
+        endedReason: schedule.mode === 'once' ? 'fired' : 'limit',
+      }, triggeredAt)
+      return []
     }
+
     const refusal = this.bindingRefusal(task)
     if (refusal !== undefined) {
       // An unconfirmed above-default permission must never run unattended: the
-      // whole tree is refused and the schedule rolls to the next occurrence,
-      // exactly like the already-running refusal.
+      // whole tree is refused and the occurrence is skipped without consuming
+      // the run budget, exactly like the already-running refusal.
       this.document.scheduler.error = `scheduled run refused for task ${taskId}: ${bindingRefusalMessage(refusal, this.sessionDefaultPermission, 'schedule')}`
-      rollForward()
+      this.skipOccurrence(taskId, 'permission', triggeredAt)
       return []
     }
-    if (task.status === 'running' || hasOpenExecution(task)) {
-      rollForward()
+    if (hasOpenExecution(task)) {
+      this.skipOccurrence(taskId, 'busy', triggeredAt)
       return []
     }
-    return this.startCascade(task, triggeredAt, undefined, false, nextRunAt)
+
+    if (schedule.mode === 'once') {
+      // The single planned instant is due: open its one run and stop the rule
+      // in the same commit, so the budget can never produce a second one.
+      return this.startCascade(task, triggeredAt, undefined, false, {
+        consumed: 1,
+        lastTriggeredAt: triggeredAt,
+        endedReason: 'fired',
+      })
+    }
+
+    const next = nextRunAtMs(schedule.cron ?? '', schedule.nextRunAt ?? triggeredAt, scheduleZone(schedule))
+    if (next === undefined) {
+      this.progressSchedule(taskId, { consumed: 0, endedReason: 'no-target' }, triggeredAt)
+      return []
+    }
+    const consumed = schedule.runCount + 1
+    const budget = scheduleRunBudget(schedule)
+    const spent = budget !== undefined && consumed >= budget
+    return this.startCascade(task, triggeredAt, undefined, false, {
+      consumed: 1,
+      nextRunAt: spent ? undefined : next,
+      lastTriggeredAt: triggeredAt,
+      ...(spent ? { endedReason: 'limit' as const } : {}),
+    })
   }
 
+  /**
+   * Record a due occurrence that opened no execution: roll a recurring rule to
+   * its next occurrence (budget untouched), or stop it when there is none. A
+   * one-shot has no second occurrence, so it always stops here with the reason.
+   */
+  private skipOccurrence(taskId: string, reason: ScheduleStopReason, now: number): void {
+    const task = this.document.tasks.find(item => item.id === taskId)
+    const schedule = task?.schedule
+    if (schedule === undefined) return
+    if (schedule.mode === 'once') {
+      this.progressSchedule(taskId, { consumed: 0, endedReason: reason }, now)
+      return
+    }
+    const next = nextRunAtMs(schedule.cron ?? '', schedule.nextRunAt ?? now, scheduleZone(schedule))
+    if (next === undefined) this.progressSchedule(taskId, { consumed: 0, endedReason: 'no-target' }, now)
+    else this.progressSchedule(taskId, { consumed: 0, nextRunAt: next, skippedReason: reason }, now)
+  }
+
+  /** Apply a schedule-occurrence transition and persist it atomically. */
+  private progressSchedule(taskId: string, progress: ScheduleProgress, now: number): void {
+    this.document.tasks = [...applyScheduleProgress(this.document.tasks, taskId, progress, now)]
+    this.commit()
+  }
+
+  /**
+   * Refund the one scheduled run an occurrence consumed before its launch
+   * failed without creating a session (see
+   * {@link applyScheduleRefund}). Called by the service on the failed-launch
+   * path only; a manual run and a launch that did reach a session are never
+   * refunded. A no-op for a task with no rule, so a failed cascade member does
+   * not touch anything.
+   * @param taskId - the task whose occurrence is being refunded.
+   * @param now - clock instant (ms epoch).
+   */
+  refundScheduledOccurrence(taskId: string, now: number): void {
+    const before = this.document.tasks.find(item => item.id === taskId)?.schedule
+    if (before === undefined) return
+    const next = applyScheduleRefund(this.document.tasks, taskId, now, timeZone())
+    const after = next.find(item => item.id === taskId)?.schedule
+    if (JSON.stringify(before) === JSON.stringify(after)) return
+    this.document.tasks = [...next]
+    this.commit()
+  }
+
+  /**
+   * Boot / resume recovery: skip every occurrence that came due while the board
+   * was not running through it. A recurring rule rolls to its next future
+   * target; a one-shot whose instant has passed is stopped as missed, because
+   * there is no later occurrence left to run. Rendering the missed occurrence
+   * is deliberately not attempted: the ACL of a card that fired hours ago is
+   * stale, and the board's own recovery contract is "missed triggers are
+   * skipped, never replayed".
+   */
   skipMissed(now: number): void {
     let changed = false
     this.document.tasks = this.document.tasks.map(task => {
       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, scheduleZone(schedule)) }, updatedAt: now }
+      if (schedule.mode === 'once') {
+        return withSchedule(task, { enabled: false, nextRunAt: undefined, endedAt: now, endedReason: 'missed' }, now)
+      }
+      const next = nextRunAtMs(schedule.cron ?? '', now, scheduleZone(schedule))
+      if (next === undefined) {
+        return withSchedule(task, { enabled: false, nextRunAt: undefined, endedAt: now, endedReason: 'no-target' }, now)
+      }
+      return withSchedule(task, { nextRunAt: next, skippedAt: now, skippedReason: 'missed' }, now)
     })
     if (changed) this.commit()
   }
@@ -736,6 +918,24 @@ export class HostTaskLedger {
     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
@@ -744,7 +944,9 @@ export class HostTaskLedger {
         const sources = new Set(this.document.scheduler.importedSources ?? [])
         if (sources.has(action.sourceId)) return { state: this.state() }
         const invalidScheduleIds = action.tasks
-          .filter(task => task.schedule !== undefined && !isValidCron(task.schedule.cron))
+          .filter(task => task.schedule !== undefined
+            && task.schedule.mode !== 'once'
+            && !isValidCron(task.schedule.cron ?? ''))
           .map(task => task.id)
         const incoming = parseHostTasks(action.tasks)
         const merged = new Map(this.document.tasks.map(task => [task.id, task]))
@@ -765,9 +967,8 @@ export class HostTaskLedger {
       }
       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)
-          || !isValidTimeZone(action.input.schedule.timeZone ?? timeZone())
-          || nextRunAtMs(action.input.schedule.cron, now, action.input.schedule.timeZone ?? timeZone()) === undefined)) {
+        const requested = action.input.schedule
+        if (requested?.enabled === true && !this.validScheduleRequest(requested, now)) {
           throw new Error('invalid schedule')
         }
         const input = action.input.freeze === undefined || initiator === undefined || initiator === ''
@@ -801,7 +1002,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)) {
@@ -820,7 +1021,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
@@ -832,6 +1036,37 @@ export class HostTaskLedger {
         this.document.tasks = [...result.tasks]
         break
       }
+      case 'record-external-outcome': {
+        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')
+        // The one guardrail that matters: while the Host still owns a run it is
+        // the only authority on the card, so an outside agent may not write the
+        // terminal verdict over it. This is also what keeps a stale report from
+        // racing the session it claims to have replaced.
+        if (hasOpenExecution(task)) throw new Error('running task cannot receive an external outcome')
+        const execution: ExecutionRecord = {
+          // A fresh id, exactly like a Host-launched run: the external work is a
+          // new attempt in the history, never an overwrite of an earlier record.
+          id: crypto.randomUUID(),
+          sessionId: undefined,
+          startedAt: now,
+          endedAt: now,
+          result: action.result,
+          error: action.summary,
+          initiatedBy: action.initiatedBy,
+          external: true,
+        }
+        this.document.tasks = this.document.tasks.map(item => item.id !== action.taskId
+          ? item
+          : {
+            ...item,
+            status: settledStatus(item, action.result),
+            updatedAt: now,
+            executions: retainRecentExecutions([...item.executions, execution]),
+          })
+        break
+      }
       case 'settle': {
         const task = this.document.tasks.find(item => item.id === action.taskId)
         if (task === undefined) throw new Error('task not found')
@@ -860,6 +1095,32 @@ export class HostTaskLedger {
         this.finalizeReadyRuns(false)
         break
       }
+      case 'reset-verification': {
+        // The explicit user reset of the acceptance anomaly counter (issue
+        // #1828). It clears the attempts the ENVIRONMENT produced — timeouts,
+        // authentication failures, unresolvable routes, and attempts the time
+        // budget ended — and nothing else: a quality verdict is the board's own
+        // judgement of the work and survives every reset. Only the open
+        // execution is addressable, because the reset exists to unblock a
+        // completion claim on a run that is still going.
+        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')
+        const execution = [...task.executions].reverse().find(entry => entry.endedAt === undefined)
+        if (execution === undefined) throw new Error('task has no open execution')
+        const verification = execution.verification
+        if (verification === undefined || verification.applicability !== 'enforced') {
+          throw new Error('this execution is not gated by task acceptance')
+        }
+        const cleared = withoutAcceptanceAnomalies(verification)
+        if (cleared === undefined) throw new Error('this execution has no acceptance anomaly to reset')
+        this.document.tasks = this.document.tasks.map(item => item.id !== action.taskId ? item : {
+          ...item,
+          updatedAt: now,
+          executions: item.executions.map(entry => entry.id === execution.id ? { ...entry, verification: cleared } : entry),
+        })
+        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)
@@ -876,6 +1137,18 @@ 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')
@@ -888,7 +1161,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.
@@ -904,15 +1177,42 @@ export class HostTaskLedger {
     return { state: this.state(), ...(runs === undefined ? {} : { runs }) }
   }
 
+  /**
+   * Whether a creation-time schedule request is usable. A one-shot must carry
+   * a whole-millisecond instant in the future; a recurring rule must carry a
+   * valid expression with a reachable occurrence and, when capped, a positive
+   * whole run budget. An unusable zone is refused rather than reinterpreted as
+   * the Host zone.
+   */
+  private validScheduleRequest(request: {
+    readonly enabled: boolean
+    readonly mode?: ScheduleMode
+    readonly cron?: string
+    readonly at?: number
+    readonly timeZone?: string
+    readonly maxRuns?: number
+  }, now: number): boolean {
+    if (request.timeZone !== undefined && !isValidTimeZone(request.timeZone)) return false
+    if (request.mode === 'once') {
+      return typeof request.at === 'number' && Number.isInteger(request.at) && request.at > now
+    }
+    const cron = (request.cron ?? '').trim()
+    if (cron === '' || !isValidCron(cron)) return false
+    if (request.maxRuns !== undefined && (!Number.isInteger(request.maxRuns) || request.maxRuns < 1)) return false
+    return nextRunAtMs(cron, now, request.timeZone ?? timeZone()) !== undefined
+  }
+
   /**
    * The binding that makes a run illegal, if any.
    *
    * 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.
    */
@@ -923,12 +1223,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 }
     }
@@ -947,14 +1252,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))
   }
 
   /**
@@ -966,9 +1270,11 @@ export class HostTaskLedger {
    * @param now - clock instant (ms epoch).
    * @param initiator - the DSH session that asked for the run (audit only).
    * @param rerun - true to reset the root to 'todo' before starting it.
-   * @param nextRunAt - when set, the root's schedule also rolls forward.
+   * @param progress - when set, this run was a due occurrence and the root's
+   *   rule is advanced (counter, next target, stop/skip record) in the same
+   *   atomic commit that opened the executions.
    */
-  private startCascade(root: TaskRecord, now: number, initiator?: string, rerun = false, nextRunAt?: number): OpenedRun[] {
+  private startCascade(root: TaskRecord, now: number, initiator?: string, rerun = false, progress?: ScheduleProgress): OpenedRun[] {
     const before = this.document.tasks
     const groupId = crypto.randomUUID()
     // A team-mode root runs as the Team Lead: every other member of the same
@@ -979,7 +1285,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)
@@ -991,7 +1297,7 @@ export class HostTaskLedger {
     }
     if (runs.length === 0) return []
     let tasks: readonly TaskRecord[] = before.map(task => started.get(task.id) ?? task)
-    if (nextRunAt !== undefined) tasks = applyScheduleNextRun(tasks, root.id, nextRunAt, now, now)
+    if (progress !== undefined) tasks = applyScheduleProgress(tasks, root.id, progress, now)
     this.document.tasks = [...tasks]
     this.commit()
     return runs
@@ -1122,6 +1428,14 @@ export class HostTaskLedger {
     return changed
   }
 
+  /**
+   * Re-align every armed rule at load/import. A recurring rule is recomputed
+   * from the current instant; a one-shot is armed at its planned instant when
+   * that is still in the future, and stopped as missed once it has passed
+   * (there is no later occurrence to run). A recurring rule recomputed past an
+   * occurrence records the skip, so the board can show that a fire was passed
+   * over rather than silently rewinding.
+   */
   private repairSchedules(skipPast: boolean, persist = true): void {
     const now = this.now()
     let changed = false
@@ -1129,15 +1443,32 @@ 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, scheduleZone(schedule))
+      if (schedule.mode === 'once') {
+        const at = schedule.at
+        if (at === undefined) {
+          changed = true
+          return withSchedule(task, { enabled: false, nextRunAt: undefined, endedAt: now, endedReason: 'no-target' }, now)
+        }
+        if (at <= now) {
+          changed = true
+          return withSchedule(task, { enabled: false, nextRunAt: undefined, endedAt: now, endedReason: 'missed' }, now)
+        }
+        if (schedule.nextRunAt === at) return task
+        changed = true
+        return withSchedule(task, { nextRunAt: at }, 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}`
-        return { ...task, schedule: { ...schedule, enabled: false, nextRunAt: undefined }, updatedAt: now }
+        return withSchedule(task, { enabled: false, nextRunAt: undefined, endedAt: now, endedReason: 'no-target' }, now)
       }
-      if (schedule.nextRunAt === next) return task
+      const passed = schedule.nextRunAt !== undefined && schedule.nextRunAt <= now
+      if (schedule.nextRunAt === next && !passed) return task
       changed = true
-      return { ...task, schedule: { ...schedule, nextRunAt: next }, updatedAt: now }
+      return withSchedule(task, passed
+        ? { nextRunAt: next, skippedAt: now, skippedReason: 'missed' }
+        : { nextRunAt: next }, now)
     })
     if (changed && persist) this.commit()
   }
@@ -1147,7 +1478,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
@@ -1166,7 +1496,7 @@ export class HostTaskLedger {
   }
 
   /**
-   * Field-preserving migration of a pre-v4 document. It first proves every task
+   * 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.
@@ -1177,23 +1507,84 @@ export class HostTaskLedger {
    * (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(`v${String(parsed.schemaVersion)} document contains structurally invalid task rows`)
     }
+    // Only generations before the stored zone was introduced (plus the one that
+    // introduced it) get the Host zone stamped: a v5 rule either carries its own
+    // zone or deliberately follows the Host, and re-stamping it would freeze it
+    // to the zone in effect at this load.
+    const stampZone = typeof parsed.schemaVersion === 'number'
+      && parsed.schemaVersion <= TASK_BOARD_ZONE_STAMP_SCHEMA_VERSION
     // 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() } }
-    })
+    const rows = stampZone
+      ? (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() } }
+        })
+      : parsed.tasks
     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 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 or
@@ -1204,8 +1595,8 @@ export class HostTaskLedger {
     } catch (error) {
       return this.recoverCorrupt(dir, existed, error)
     }
-    if (parsed.schemaVersion === TASK_BOARD_LEGACY_SCHEMA_VERSION
-      || parsed.schemaVersion === TASK_BOARD_OLDER_SCHEMA_VERSION) {
+    if (typeof parsed.schemaVersion === 'number'
+      && TASK_BOARD_MIGRATABLE_SCHEMA_VERSIONS.includes(parsed.schemaVersion)) {
       try {
         return this.migrateLegacyDocument(parsed)
       } catch (error) {
@@ -1228,8 +1619,14 @@ export class HostTaskLedger {
       if (typeof value !== 'object' || value === null) return []
       const row = value as { id?: unknown; schedule?: unknown }
       if (typeof row.schedule !== 'object' || row.schedule === null) return []
-      const cron = (row.schedule as { cron?: unknown }).cron
-      return typeof cron !== 'string' || !isValidCron(cron)
+      const rule = row.schedule as { cron?: unknown; mode?: unknown; at?: unknown }
+      // A one-shot has no cron: its instant is what must be usable.
+      if (rule.mode === 'once') {
+        return typeof rule.at === 'number' && Number.isFinite(rule.at)
+          ? []
+          : [typeof row.id === 'string' ? row.id : 'unknown']
+      }
+      return typeof rule.cron !== 'string' || !isValidCron(rule.cron)
         ? [typeof row.id === 'string' ? row.id : 'unknown']
         : []
     })
@@ -1426,4 +1823,4 @@ export class HostTaskLedger {
     }
     throw new Error(`task-board ledger lock could not be acquired: ${this.lockFile}`)
   }
-}
+}