@linxin666/dsh-client-ui-task-board 0.1.1

package/src/core/schedule.ts

@@ -0,0 +1,140 @@
+/**
+ * Minimal 5-field cron parsing and next-run computation for scheduled task
+ * runs. Framework-free and dependency-free so the scheduler and controller
+ * share one tiny pure module.
+ *
+ * Grammar: five whitespace-separated fields, 分 时 日 月 周. Every field
+ * supports the wildcard, step (wildcard or range + "/n"), single value,
+ * inclusive range a-b, and comma lists mixing any of those. Ranges: minutes
+ * 0-59, hours 0-23, days 1-31, months 1-12, weekdays 0-7 (0 and 7 both mean
+ * Sunday). When both the day and weekday fields are restricted they combine
+ * with OR semantics (standard cron). Invalid expressions parse to null and
+ * are rejected by the UI/controller.
+ */
+
+/** The parsed match sets of one cron expression. */
+export interface CronSchedule {
+  minutes: ReadonlySet<number>
+  hours: ReadonlySet<number>
+  days: ReadonlySet<number>
+  months: ReadonlySet<number>
+  /** Weekdays 0-6, 0 = Sunday (input 7 normalized to 0). */
+  weekdays: ReadonlySet<number>
+  /** Whether the day-of-month field was the literal '*' (unrestricted). */
+  dayWildcard: boolean
+  /** Whether the weekday field was the literal '*' (unrestricted). */
+  weekdayWildcard: boolean
+}
+
+/** Inclusive ranges per field, in cron order. */
+const FIELD_RANGES: ReadonlyArray<readonly [number, number]> = [
+  [0, 59], // minutes
+  [0, 23], // hours
+  [1, 31], // days
+  [1, 12], // months
+  [0, 7], // weekdays (7 = Sunday, normalized below)
+]
+
+/**
+ * Parse a 5-field cron expression.
+ * @returns the match sets, or null when the expression is invalid.
+ */
+export function parseCron(expr: string): CronSchedule | null {
+  const fields = expr.trim().split(/\s+/)
+  if (fields.length !== 5) return null
+  const sets: Set<number>[] = []
+  for (let index = 0; index < 5; index++) {
+    const [min, max] = FIELD_RANGES[index]
+    const set = new Set<number>()
+    if (!parseField(fields[index], min, max, set)) return null
+    sets.push(set)
+  }
+  const weekdays = new Set<number>()
+  for (const day of sets[4]) weekdays.add(day === 7 ? 0 : day)
+  return {
+    minutes: sets[0],
+    hours: sets[1],
+    days: sets[2],
+    months: sets[3],
+    weekdays,
+    // Only the literal '*' marks a field unrestricted: an explicit full
+    // enumeration such as '1-31' is a restricted field and must not collapse
+    // into the wildcard (it participates in day/weekday OR semantics).
+    dayWildcard: fields[2] === '*',
+    weekdayWildcard: fields[4] === '*',
+  }
+}
+
+/** Whether the expression parses. */
+export function isValidCron(expr: string): boolean {
+  return parseCron(expr) !== null
+}
+
+/**
+ * Compute the next matching instant after `fromMs` (ms epoch), in local time,
+ * at minute granularity, strictly greater than `fromMs`. Returns the ms epoch
+ * of the matching minute's start, or undefined when nothing matches within
+ * 366 days (e.g. `0 0 30 2 *`).
+ */
+export function nextRunAtMs(expr: string, fromMs: number): number | undefined {
+  const schedule = parseCron(expr)
+  if (schedule === null) return undefined
+  const from = new Date(fromMs)
+  // Scan from the next minute; Date rolls overflow (Feb 30 → Mar 2) for free.
+  const scan = new Date(from.getFullYear(), from.getMonth(), from.getDate(), from.getHours(), from.getMinutes() + 1, 0, 0)
+  const limitMs = fromMs + 366 * 24 * 60 * 60 * 1000
+  while (scan.getTime() <= limitMs) {
+    if (matches(schedule, scan)) return scan.getTime()
+    scan.setMinutes(scan.getMinutes() + 1)
+  }
+  return undefined
+}
+
+/** Parse one comma-list field into the match set. */
+function parseField(field: string, min: number, max: number, out: Set<number>): boolean {
+  if (field === '*') {
+    for (let value = min; value <= max; value++) out.add(value)
+    return true
+  }
+  for (const part of field.split(',')) {
+    if (part === '') return false
+    const [range, stepRaw] = part.split('/')
+    let low: number
+    let high: number
+    if (range === '*') {
+      low = min
+      high = max
+    } else if (range.includes('-')) {
+      const [a, b] = range.split('-')
+      if (a === '' || b === '' || !isDigits(a) || !isDigits(b)) return false
+      low = Number(a)
+      high = Number(b)
+    } else if (isDigits(range)) {
+      low = Number(range)
+      high = Number(range)
+    } else {
+      return false
+    }
+    if (low < min || high > max || low > high) return false
+    const step = stepRaw === undefined ? 1 : isDigits(stepRaw) ? Number(stepRaw) : NaN
+    if (!Number.isInteger(step) || step < 1) return false
+    for (let value = low; value <= high; value += step) out.add(value)
+  }
+  return true
+}
+
+/** Day/weekday OR semantics: a restricted day field alone gates, and vice versa. */
+function matches(schedule: CronSchedule, date: Date): boolean {
+  if (!schedule.minutes.has(date.getMinutes())) return false
+  if (!schedule.hours.has(date.getHours())) return false
+  if (!schedule.months.has(date.getMonth() + 1)) return false
+  const dayMatches = schedule.days.has(date.getDate())
+  const weekdayMatches = schedule.weekdays.has(date.getDay())
+  if (schedule.dayWildcard) return weekdayMatches
+  if (schedule.weekdayWildcard) return dayMatches
+  return dayMatches || weekdayMatches
+}
+
+function isDigits(value: string): boolean {
+  return /^\d+$/.test(value)
+}

package/src/core/scheduler.ts

@@ -0,0 +1,104 @@
+/**
+ * Browser-side scheduler: the heartbeat behind scheduled task runs.
+ *
+ * The board is a pure client plugin with no server channel, so "定时任务"
+ * lives in the tab: a timer ticks every minute (plus immediately on tab
+ * visibility recovery) and triggers any task whose `schedule.nextRunAt` is
+ * due, rolling the schedule forward to the next cron match before triggering
+ * so the same tick never double-fires. Missed runs are skipped, never queued:
+ * a task still running at its due instant is skipped by the controller's
+ * runTask guard and simply waits for the next cron match.
+ *
+ * Framework-free: all runtime access flows through the injected deps
+ * (structural faces), so tests drive ticks directly without timers.
+ */
+import { nextRunAtMs } from './schedule.ts'
+import type { TaskRecord } from './tasks.ts'
+
+/** Everything the scheduler needs from its host (the board controller). */
+export interface SchedulerDeps {
+  /** Read the current task ledger (the controller snapshot). */
+  tasks(): readonly TaskRecord[]
+  /** Clock; defaults to Date.now in the controller wiring. */
+  now(): number
+  /** Trigger one task's real execution (the controller's runTask); resolves
+   *  true when the run was accepted, false when rejected (e.g. the task is
+   *  already running). */
+  runTask(id: string): Promise<boolean>
+  /** Persist a rolled-forward schedule (next due + this trigger instant). */
+  applySchedule(id: string, nextRunAt: number | undefined, lastTriggeredAt: number | undefined): void
+  /** Tick cadence; defaults to 60_000 ms. */
+  tickMs?: number
+  /**
+   * Gate: while false the tick no-ops (e.g. the session list baseline has not
+   * arrived on page load, so executions would fail). Defaults to always ready.
+   */
+  ready?: () => boolean
+  /** Environment listeners for tab-visibility recovery (browser only). */
+  environment?: {
+    addEventListener(type: 'visibilitychange', listener: () => void): void
+    removeEventListener(type: 'visibilitychange', listener: () => void): void
+  }
+}
+
+/**
+ * The schedule heartbeat (see module doc). `tick` is public so tests and
+ * callers can drive a check without waiting for the interval.
+ */
+export class SchedulerService {
+  private timer: ReturnType<typeof setInterval> | undefined
+  private disposed = false
+
+  /** @param deps - tasks/clock/trigger/apply faces (see {@link SchedulerDeps}). */
+  constructor(private readonly deps: SchedulerDeps) {}
+
+  /** Start ticking: one immediate check (catch-up after reload) + the interval. */
+  start(): void {
+    if (this.disposed) return
+    // Immediate catch-up tick: schedules whose due instant passed while the
+    // tab was closed are triggered as soon as the runtime is ready.
+    this.tick()
+    this.timer = setInterval(() => { this.tick() }, this.deps.tickMs ?? 60_000)
+    this.deps.environment?.addEventListener('visibilitychange', this.onVisibility)
+  }
+
+  /** Stop ticking and drop listeners (idempotent). */
+  dispose(): void {
+    this.disposed = true
+    if (this.timer !== undefined) clearInterval(this.timer)
+    this.timer = undefined
+    this.deps.environment?.removeEventListener('visibilitychange', this.onVisibility)
+  }
+
+  /**
+   * Check every enabled schedule and trigger the due ones. Idempotent per
+   * task per tick: the schedule is rolled forward only after runTask accepts
+   * the run, so a rejected run keeps its due slot and is retried on the next
+   * tick instead of being silently dropped.
+   */
+  async tick(): Promise<void> {
+    if (this.disposed) return
+    if (this.deps.ready !== undefined && !this.deps.ready()) return
+    const now = this.deps.now()
+    for (const task of this.deps.tasks()) {
+      const schedule = task.schedule
+      if (schedule === undefined || !schedule.enabled) continue
+      if (schedule.nextRunAt === undefined) {
+        // Missing next-run instant (repaired/legacy data): recompute from the
+        // cron expression and wait; an unparseable expression is skipped.
+        const repaired = nextRunAtMs(schedule.cron, now)
+        if (repaired === undefined) continue
+        this.deps.applySchedule(task.id, repaired, undefined)
+        continue
+      }
+      if (schedule.nextRunAt > now) continue
+      // Advance from the due instant (not this tick's wall-clock) and only
+      // after the run is accepted: a rejected run keeps its due slot.
+      const next = nextRunAtMs(schedule.cron, schedule.nextRunAt)
+      const accepted = await this.deps.runTask(task.id)
+      if (accepted) this.deps.applySchedule(task.id, next, now)
+    }
+  }
+
+  private readonly onVisibility = (): void => { this.tick() }
+}

package/src/core/store.ts

@@ -0,0 +1,183 @@
+/**
+ * Task persistence: a small storage seam with a localStorage backend.
+ *
+ * The task-board client plugin runs in the browser, and dsh exposes no
+ * browser-writable file channel (same conclusion the skin-center research
+ * reached for cordis.patch.yml), so tasks persist in the browser's
+ * localStorage under a versioned key — the same persistence mechanism dsh's
+ * own client snapshot stores use (`createSnapshotStore` persist). Data
+ * survives page refreshes and dsh restarts (same origin), and survives
+ * plugin uninstall (the key is simply left in place).
+ *
+ * The seam keeps the backend swappable (e.g. an IndexedDB or a host-file
+ * channel later); tests run against the in-memory backend and a jsdom
+ * localStorage backend.
+ */
+import { isValidCron } from './schedule.ts'
+import type { ScheduleRule, TaskRecord, TaskStatus } from './tasks.ts'
+import { isTaskStatus } from './tasks.ts'
+
+/** Persistence seam for the task ledger. */
+export interface TaskStore {
+  /** Read the persisted ledger (empty when nothing is stored yet). */
+  load(): TaskRecord[]
+  /** Persist the whole ledger (replaces the stored document). */
+  save(tasks: readonly TaskRecord[]): void
+  /** Drop the persisted ledger (leaves the in-memory state alone). */
+  clear(): void
+}
+
+/** Storage key for the task ledger document. */
+export const DEFAULT_STORAGE_KEY = 'dsh.taskBoard.v1'
+
+/**
+ * Structural row check with the status left unvalidated (see {@link parseLedger}).
+ * The `schedule` field is deliberately NOT checked here: a malformed schedule
+ * never drops the task row — {@link normalizeSchedule} repairs or drops the
+ * schedule alone.
+ */
+function isTaskRecordShape(value: unknown): value is Omit<TaskRecord, 'status'> & { status: unknown } {
+  if (typeof value !== 'object' || value === null) return false
+  const record = value as Record<string, unknown>
+  if (typeof record.id !== 'string' || record.id === '') return false
+  if (typeof record.title !== 'string') return false
+  if (typeof record.description !== 'string') return false
+  if (typeof record.prompt !== 'string') return false
+  if (typeof record.createdAt !== 'number') return false
+  if (typeof record.updatedAt !== 'number') return false
+  if (!Array.isArray(record.executions)) return false
+  for (const execution of record.executions) {
+    if (typeof execution !== 'object' || execution === null) return false
+    const entry = execution as Record<string, unknown>
+    if (typeof entry.id !== 'string') return false
+    if (entry.sessionId !== undefined && typeof entry.sessionId !== 'string') return false
+    if (typeof entry.startedAt !== 'number') return false
+    if (entry.endedAt !== undefined && typeof entry.endedAt !== 'number') return false
+    if (entry.result !== undefined && entry.result !== 'succeeded' && entry.result !== 'failed' && entry.result !== 'cancelled') return false
+    if (entry.error !== undefined && typeof entry.error !== 'string') return false
+  }
+  return true
+}
+
+/** A task record is structurally valid if it round-trips through the UI. */
+export function isTaskRecord(value: unknown): value is TaskRecord {
+  return isTaskRecordShape(value) && isTaskStatus(value.status)
+}
+
+/** Normalize an unknown persisted status back into the closed status union. */
+function normalizeStatus(status: unknown): TaskStatus {
+  return isTaskStatus(status) ? status : 'todo'
+}
+
+/**
+ * Repair a persisted schedule rule: drop rules without a usable cron string,
+ * coerce booleans/numbers, and leave `nextRunAt`/`lastTriggeredAt` undefined
+ * when missing (a fresh recompute or the next tick fixes them).
+ */
+function normalizeSchedule(schedule: unknown): ScheduleRule | undefined {
+  if (typeof schedule !== 'object' || schedule === null) return undefined
+  const rule = schedule as Record<string, unknown>
+  // Reject (drop) a schedule whose cron is not a well-formed 5-field
+  // expression: a malformed rule would otherwise linger as a never-firing
+  // schedule instead of being dropped for later repair.
+  if (typeof rule.cron !== 'string') return undefined
+  if (rule.cron.trim() === '' || !isValidCron(rule.cron)) return undefined
+  return {
+    enabled: rule.enabled === true,
+    cron: rule.cron,
+    nextRunAt: typeof rule.nextRunAt === 'number' ? rule.nextRunAt : undefined,
+    lastTriggeredAt: typeof rule.lastTriggeredAt === 'number' ? rule.lastTriggeredAt : undefined,
+  }
+}
+
+/** Parse + validate a persisted ledger document; invalid rows are dropped. */
+export function parseLedger(raw: string | null): TaskRecord[] {
+  if (raw === null) return []
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch (error) {
+    console.error('[dsh-task-board] persisted task ledger is not valid JSON; starting empty', error)
+    return []
+  }
+  if (!Array.isArray(parsed)) {
+    console.error('[dsh-task-board] persisted task ledger is not an array; starting empty')
+    return []
+  }
+  const tasks: TaskRecord[] = []
+  for (const row of parsed) {
+    // Status is normalized (an unknown status from a future version lands in
+    // todo instead of dropping the row); the schedule is repaired field by
+    // field; every other field must be valid.
+    if (!isTaskRecordShape(row)) {
+      console.warn('[dsh-task-board] dropping invalid task row from persisted ledger', row)
+      continue
+    }
+    // Always (re)assign the schedule: a repair that returns undefined must
+    // clear a malformed persisted rule rather than leave it in the row.
+    const task: TaskRecord = { ...row, status: normalizeStatus(row.status) }
+    task.schedule = normalizeSchedule(row.schedule)
+    tasks.push(task)
+  }
+  return tasks
+}
+
+/** localStorage-backed store (the browser backend). */
+export class LocalStorageTaskStore implements TaskStore {
+  /**
+   * @param key - storage key for the ledger document.
+   * @param storage - storage backend (defaults to the global localStorage; tests inject fakes).
+   */
+  constructor(
+    private readonly key: string = DEFAULT_STORAGE_KEY,
+    private readonly storage: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'> | undefined = globalThis.localStorage,
+  ) {}
+
+  load(): TaskRecord[] {
+    if (this.storage === undefined) return []
+    try {
+      return parseLedger(this.storage.getItem(this.key))
+    } catch (error) {
+      // Storage read failures (private mode, quota) degrade to an empty ledger,
+      // never break the board.
+      console.error('[dsh-task-board] task ledger read failed; starting empty', error)
+      return []
+    }
+  }
+
+  save(tasks: readonly TaskRecord[]): void {
+    if (this.storage === undefined) return
+    try {
+      this.storage.setItem(this.key, JSON.stringify(tasks))
+    } catch (error) {
+      // Write failures only skip persistence; in-memory state stays live.
+      console.error('[dsh-task-board] task ledger write failed (persistence skipped)', error)
+    }
+  }
+
+  clear(): void {
+    if (this.storage === undefined) return
+    try {
+      this.storage.removeItem(this.key)
+    } catch (error) {
+      console.error('[dsh-task-board] task ledger clear failed', error)
+    }
+  }
+}
+
+/** In-memory backend (tests, and a fallback when storage is unavailable). */
+export class InMemoryTaskStore implements TaskStore {
+  private ledger: TaskRecord[] = []
+
+  load(): TaskRecord[] {
+    return this.ledger.map(task => ({ ...task, executions: [...task.executions] }))
+  }
+
+  save(tasks: readonly TaskRecord[]): void {
+    this.ledger = tasks.map(task => ({ ...task, executions: [...task.executions] }))
+  }
+
+  clear(): void {
+    this.ledger = []
+  }
+}

package/src/core/tasks.ts

@@ -0,0 +1,204 @@
+/**
+ * Task board domain model: task lifecycle statuses, the task record shape,
+ * and the pure transition functions the controller and tests share.
+ * Framework-free (no cordis, no runtime imports) so the state machine is
+ * unit-testable in isolation.
+ */
+
+/** Task lifecycle status, one per kanban column. */
+export type TaskStatus = 'backlog' | 'todo' | 'running' | 'done' | 'failed'
+
+/**
+ * One real execution attempt: the run's own id, the dsh session that ran it
+ * (filled once the session is created), and the settled outcome once the
+ * session's turn ended.
+ */
+export interface ExecutionRecord {
+  /** Execution attempt id (uuid). */
+  id: string
+  /** The dsh session that ran this attempt; absent until creation resolves. */
+  sessionId: string | undefined
+  /** When the run started (ms epoch). */
+  startedAt: number
+  /** When the run settled; absent while still running. */
+  endedAt: number | undefined
+  /** Outcome once settled. */
+  result: 'succeeded' | 'failed' | 'cancelled' | undefined
+  /** Human failure text when the run failed (prompt rejection or agent error). */
+  error: string | undefined
+}
+
+/**
+ * A scheduled-run rule attached to a task. The browser-side scheduler ticks
+ * every minute and triggers the task when `nextRunAt` is due; the rule is
+ * persisted with the task (localStorage), so scheduling survives refreshes.
+ */
+export interface ScheduleRule {
+  /** Whether the schedule is armed. */
+  enabled: boolean
+  /** 5-field cron expression: `分 时 日 月 周`. */
+  cron: string
+  /** Next due instant (ms epoch); maintained by the scheduler/controller. */
+  nextRunAt: number | undefined
+  /** Instant of the latest scheduled trigger (ms epoch). */
+  lastTriggeredAt: number | undefined
+}
+
+/** One task on the board. */
+export interface TaskRecord {
+  /** Stable task id (uuid). */
+  id: string
+  /** Short display title. */
+  title: string
+  /** Longer human description shown in the detail view. */
+  description: string
+  /** The prompt sent to dsh when this task is executed. */
+  prompt: string
+  /** Current column. */
+  status: TaskStatus
+  /** Creation instant (ms epoch). */
+  createdAt: number
+  /** Last mutation instant (ms epoch). */
+  updatedAt: number
+  /** Every execution attempt, most recent last. */
+  executions: ExecutionRecord[]
+  /** Optional scheduled-run rule (absent on tasks without a schedule). */
+  schedule?: ScheduleRule
+}
+
+/** Input for creating a task. */
+export interface NewTaskInput {
+  title: string
+  description: string
+  prompt: string
+}
+
+/** The five kanban columns, in display order. */
+export const COLUMNS: readonly { status: TaskStatus; label: string }[] = [
+  { status: 'backlog', label: '待规划' },
+  { status: 'todo', label: '待办' },
+  { status: 'running', label: '进行中' },
+  { status: 'done', label: '已完成' },
+  { status: 'failed', label: '已失败' },
+]
+
+/** Statuses a user may move a card to manually (execution states are owned by the runner). */
+export const MANUAL_STATUSES: readonly TaskStatus[] = ['backlog', 'todo']
+
+/** Statuses the runner may move a card to from 'running'. */
+export const RUNNER_SETTLE_STATUSES: readonly TaskStatus[] = ['done', 'failed']
+
+/** All valid statuses (closed union guard). */
+export const ALL_STATUSES: readonly TaskStatus[] = [
+  'backlog', 'todo', 'running', 'done', 'failed',
+]
+
+/** Brand an unknown string as a status; undefined when it is not one. */
+export function isTaskStatus(value: unknown): value is TaskStatus {
+  return typeof value === 'string' && (ALL_STATUSES as readonly string[]).includes(value)
+}
+
+/** Whether a manual move target is allowed from the given status. */
+export function canMoveManually(_from: TaskStatus, to: TaskStatus): boolean {
+  return (MANUAL_STATUSES as readonly TaskStatus[]).includes(to)
+}
+
+/** Create a task from user input. */
+export function createTask(input: NewTaskInput, now: number, id: string): TaskRecord {
+  return {
+    id,
+    title: input.title.trim(),
+    description: input.description.trim(),
+    prompt: input.prompt.trim(),
+    status: 'todo',
+    createdAt: now,
+    updatedAt: now,
+    executions: [],
+  }
+}
+
+/** Clone a task with an updated status and a fresh updatedAt. */
+export function withStatus(task: TaskRecord, status: TaskStatus, now: number): TaskRecord {
+  return { ...task, status, updatedAt: now }
+}
+
+/**
+ * Merge a schedule patch into a task's schedule rule (creating it when
+ * absent), with a fresh updatedAt. Keys present in the patch overwrite the
+ * current value — including explicit `undefined`, which clears a field (used
+ * to disarm `nextRunAt`); absent keys keep their current value.
+ */
+export function withSchedule(
+  task: TaskRecord,
+  patch: Partial<ScheduleRule>,
+  now: number,
+): TaskRecord {
+  const current = task.schedule
+  const schedule: ScheduleRule = {
+    enabled: current?.enabled ?? false,
+    cron: current?.cron ?? '',
+    nextRunAt: current?.nextRunAt,
+    lastTriggeredAt: current?.lastTriggeredAt,
+  }
+  if ('enabled' in patch) schedule.enabled = patch.enabled ?? false
+  if ('cron' in patch) schedule.cron = patch.cron ?? ''
+  if ('nextRunAt' in patch) schedule.nextRunAt = patch.nextRunAt
+  if ('lastTriggeredAt' in patch) schedule.lastTriggeredAt = patch.lastTriggeredAt
+  return { ...task, updatedAt: now, schedule }
+}
+
+/**
+ * Open a fresh execution on a task: move it to 'running' and append a
+ * running execution record. Returns the new task and the new execution.
+ */
+export function startExecution(
+  task: TaskRecord,
+  now: number,
+  executionId: string,
+): { task: TaskRecord; execution: ExecutionRecord } {
+  const execution: ExecutionRecord = {
+    id: executionId,
+    sessionId: undefined,
+    startedAt: now,
+    endedAt: undefined,
+    result: undefined,
+    error: undefined,
+  }
+  return {
+    task: { ...task, status: 'running', updatedAt: now, executions: [...task.executions, execution] },
+    execution,
+  }
+}
+
+/**
+ * Settle a running execution: record the outcome and move the task into the
+ * matching column. No-op (returns the input task) when the execution is not
+ * the task's latest or is already settled.
+ */
+export function settleExecution(
+  task: TaskRecord,
+  executionId: string,
+  outcome: 'succeeded' | 'failed' | 'cancelled',
+  now: number,
+  error: string | undefined,
+): TaskRecord {
+  const index = task.executions.findIndex(execution => execution.id === executionId)
+  if (index === -1) return task
+  const execution = task.executions[index]
+  if (execution.endedAt !== undefined) return task
+  const settled: ExecutionRecord = { ...execution, endedAt: now, result: outcome, error }
+  const executions = [...task.executions]
+  executions[index] = settled
+  const status: TaskStatus = outcome === 'succeeded' ? 'done'
+    : outcome === 'failed' ? 'failed'
+      : task.status === 'running' ? 'todo' : task.status
+  return { ...task, status, updatedAt: now, executions }
+}
+
+/** A settled-execution summary string for the detail view. */
+export function executionLabel(execution: ExecutionRecord): string {
+  if (execution.result === 'succeeded') return 'succeeded'
+  if (execution.result === 'failed') return 'failed'
+  if (execution.result === 'cancelled') return 'cancelled'
+  return 'running'
+}