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

package/src/host-ledger.ts

@@ -5,11 +5,12 @@ 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, hasOpenExecution, 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,
   combineCascadeOutcome,
+  joinsCascadeRun,
   normalizeSubtaskDepth,
   openGroupExecution,
   pendingCascadeChildren,
@@ -17,13 +18,14 @@ import {
 } from './core/subtask.ts'
 import { applyArchiveTask, applyRestoreTask } from './core/use-cases/task-archive.ts'
 import { applyCreateTask } from './core/use-cases/task-create.ts'
+import type { CardDefaults } from './core/card-defaults.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_MIGRATABLE_SCHEMA_VERSIONS, TASK_BOARD_SCHEMA_VERSION, type TaskBoardAction, type TaskBoardSchedulerSnapshot } from './protocol.ts'
-import type { ExecutionVerification } from './core/verification.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 {
@@ -98,7 +100,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
@@ -108,6 +113,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
@@ -125,8 +148,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[]
+/**
+ * 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]
 }
 
 /**
@@ -397,17 +437,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,
       },
     }
   })
@@ -443,11 +490,15 @@ export class HostTaskLedger {
    */
   private depthLimit: number
 
-  constructor(dir: string = join(dshHome(), 'task-board'), private readonly now: () => number = Date.now, options: { sessionDefaultPermission?: TaskPermission | (() => TaskPermission); maxSubtaskDepth?: number } = {}) {
+  /** Live reader of the deployment's new-card defaults (a volatile config read). */
+  private readonly cardDefaults: () => CardDefaults
+
+  constructor(dir: string = join(dshHome(), 'task-board'), private readonly now: () => number = Date.now, options: { sessionDefaultPermission?: TaskPermission | (() => TaskPermission); maxSubtaskDepth?: number; cardDefaults?: () => CardDefaults } = {}) {
     // 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)
+    this.cardDefaults = options.cardDefaults ?? (() => ({}))
     mkdirSync(dir, { recursive: true })
     this.file = join(dir, 'ledger-v2.json')
     this.lockFile = join(dir, 'ledger-v2.lock')
@@ -517,16 +568,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>()
@@ -537,10 +589,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
@@ -555,7 +610,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. */
@@ -594,7 +654,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
   }
@@ -646,38 +712,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 (hasOpenExecution(task)) {
-      rollForward()
+      this.skipOccurrence(taskId, 'busy', triggeredAt)
+      return []
+    }
+
+    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 []
     }
-    return this.startCascade(task, triggeredAt, undefined, false, nextRunAt)
+    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()
   }
@@ -782,7 +950,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]))
@@ -803,15 +973,14 @@ 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 === ''
           ? action.input
           : { ...action.input, freeze: { ...action.input.freeze, frozenBy: initiator } }
-        const result = applyCreateTask(this.document.tasks, input, now, action.id, this.maxSubtaskDepth, timeZone())
+        const result = applyCreateTask(this.document.tasks, input, now, action.id, this.maxSubtaskDepth, timeZone(), this.cardDefaults())
         if (result.task === undefined) throw new Error(result.error ?? 'invalid task')
         this.document.tasks = [...result.tasks]
         break
@@ -873,6 +1042,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')
@@ -901,6 +1101,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)
@@ -957,6 +1183,31 @@ 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.
    *
@@ -1017,17 +1268,20 @@ export class HostTaskLedger {
   }
 
   /**
-   * Open one execution per cascade participant (the requested task and its
-   * on-board descendants, within the depth limit) under a single run group, and
-   * commit the ledger once. The returned runs are ordered root-first, so the
-   * Host launches the parent before its subtasks.
+   * Open one execution per cascade participant that still has work (the
+   * requested task and its on-board descendants, within the depth limit) under
+   * a single run group, and commit the ledger once. A descendant in 'done' is
+   * not a participant ({@link joinsCascadeRun}). The returned runs are ordered
+   * root-first, so the Host launches the parent before its subtasks.
    * @param root - the task the user ran.
    * @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
@@ -1038,6 +1292,11 @@ export class HostTaskLedger {
     const runs: OpenedRun[] = []
     for (const task of cascadeTargets(before, root.id, this.maxSubtaskDepth)) {
       if (task.archivedAt !== undefined) continue
+      // A subtask that already sits in 'done' is left alone: running the parent
+      // repeats the parent, never the work a subtask has already finished. The
+      // rule is the card's column, so it holds for a manual run, a re-run and a
+      // due occurrence alike.
+      if (!joinsCascadeRun(task, root.id)) 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)
@@ -1050,7 +1309,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
@@ -1181,6 +1440,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
@@ -1188,15 +1455,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()
   }
@@ -1245,15 +1529,23 @@ export class HostTaskLedger {
     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[] })
   }
 
@@ -1339,8 +1631,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']
         : []
     })