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

package/src/core/use-cases/task-create.ts

@@ -4,7 +4,7 @@
  * (no persistence or notify - the controller orchestrates those), so it is
  * unit-testable without any runtime face.
  */
-import { isValidCron, nextRunAtMs } from '../schedule.ts'
+import { isValidCron, isValidTimeZone, nextRunAtMs, resolveHostTimeZone } from '../schedule.ts'
 import { DEFAULT_SUBTASK_DEPTH, normalizeSubtaskDepth, taskDepth } from '../subtask.ts'
 import { createTask, withSchedule, type NewTaskInput, type TaskRecord } from '../tasks.ts'
 
@@ -32,6 +32,7 @@ export interface CreateTaskResult {
  * @param now - clock instant (ms epoch).
  * @param id - minted task id.
  * @param maxSubtaskDepth - deployment subtask depth limit.
+ * @param hostTimeZone - zone a rule that stores no zone of its own follows.
  */
 export function applyCreateTask(
   tasks: readonly TaskRecord[],
@@ -39,6 +40,7 @@ export function applyCreateTask(
   now: number,
   id: string,
   maxSubtaskDepth: number = DEFAULT_SUBTASK_DEPTH,
+  hostTimeZone: string = resolveHostTimeZone(),
 ): CreateTaskResult {
   if (input.title.trim() === '') return { task: undefined, tasks, error: 'title is required' }
   const limit = normalizeSubtaskDepth(maxSubtaskDepth)
@@ -71,7 +73,17 @@ export function applyCreateTask(
   const requested = input.schedule
   if (requested?.enabled === true && requested.cron.trim() !== '' && isValidCron(requested.cron)) {
     const cron = requested.cron.trim()
-    task = withSchedule(task, { enabled: true, cron, nextRunAt: nextRunAtMs(cron, now) }, now)
+    const requestedZone = requested.timeZone
+    // An unusable zone is refused rather than silently reinterpreted as the
+    // Host zone: the caller asked for a specific wall clock.
+    if (requestedZone !== undefined && !isValidTimeZone(requestedZone)) {
+      return { task: undefined, tasks, error: 'invalid schedule time zone' }
+    }
+    const zone = requestedZone ?? hostTimeZone
+    const nextRunAt = nextRunAtMs(cron, now, zone)
+    if (nextRunAt !== undefined) {
+      task = withSchedule(task, { enabled: true, cron, timeZone: requestedZone, nextRunAt }, now)
+    }
   }
   return { task, tasks: [...tasks, task] }
 }

package/src/core/use-cases/task-schedule.ts

@@ -4,13 +4,15 @@
  * orchestrates those). Validation and next-run computation live here, sharing
  * the core cron parser (schedule.ts) and the withSchedule transition.
  */
-import { isValidCron, nextRunAtMs } from '../schedule.ts'
+import { isValidCron, isValidTimeZone, nextRunAtMs } from '../schedule.ts'
 import { withSchedule, type TaskRecord } from '../tasks.ts'
 
 /** Fields the schedule use case may change on a rule. */
 export interface SetSchedulePatch {
   enabled?: boolean
   cron?: string
+  /** IANA zone for the cron wall clock; `null` clears it back to the Host zone. */
+  timeZone?: string | null
 }
 
 /** Result of arming/disarming a rule. */
@@ -22,31 +24,40 @@ export interface SetScheduleResult {
 }
 
 /**
- * Set an on-board task's schedule rule. A blank or invalid cron, or an
- * archived task, is rejected (state untouched); an enabled rule computes the
- * next run instant immediately, a disabled one carries no next-run instant.
+ * Set an on-board task's schedule rule. A blank or invalid cron, an unknown or
+ * archived task, or an unusable zone is rejected (state untouched); an enabled
+ * rule computes the next run instant immediately in the rule's own zone, a
+ * disabled one carries no next-run instant.
  * @param tasks - current ledger.
  * @param id - the task to schedule.
  * @param patch - rule fields to change (absent fields keep their current value).
  * @param now - clock instant (ms epoch).
+ * @param hostTimeZone - zone a rule with no stored zone follows.
  */
 export function applySetSchedule(
   tasks: readonly TaskRecord[],
   id: string,
   patch: SetSchedulePatch,
   now: number,
+  hostTimeZone: string,
 ): SetScheduleResult {
   const task = tasks.find(candidate => candidate.id === id)
   if (task === undefined || task.archivedAt !== undefined) return { tasks, applied: false }
   const current = task.schedule
   const cron = (patch.cron ?? current?.cron ?? '').trim()
   if (cron === '' || !isValidCron(cron)) return { tasks, applied: false }
+  // An explicit null clears the stored zone; an absent key keeps it.
+  const requestedZone = patch.timeZone === undefined ? current?.timeZone : patch.timeZone ?? undefined
+  if (requestedZone !== undefined && !isValidTimeZone(requestedZone)) return { tasks, applied: false }
   const enabled = patch.enabled ?? current?.enabled ?? false
-  const nextRunAt = enabled ? nextRunAtMs(cron, now) : undefined
+  const effectiveZone = requestedZone ?? hostTimeZone
+  const nextRunAt = enabled ? nextRunAtMs(cron, now, effectiveZone) : undefined
   if (enabled && nextRunAt === undefined) return { tasks, applied: false }
   return {
     tasks: tasks.map(candidate =>
-      candidate.id === id ? withSchedule(candidate, { enabled, cron, nextRunAt }, now) : candidate),
+      candidate.id === id
+        ? withSchedule(candidate, { enabled, cron, timeZone: requestedZone ?? undefined, nextRunAt }, now)
+        : candidate),
     applied: true,
   }
 }

package/src/core/use-cases/task-update.ts

@@ -16,7 +16,7 @@ import type { TaskHandoverInput } from '../handover.ts'
  * Editable fields on a task (the update patch surface). `freeze` replaces the
  * continuation-card snapshot (restamping frozenAt); an explicit null clears it.
  */
-export type TaskUpdatePatch = Partial<Pick<TaskRecord, 'title' | 'description' | 'prompt' | 'workspaceId' | 'mode' | 'permission' | 'model' | 'reuseSession' | 'teamRun'>> & {
+export type TaskUpdatePatch = Partial<Pick<TaskRecord, 'title' | 'description' | 'prompt' | 'workspaceId' | 'mode' | 'permission' | 'model' | 'reuseSession' | 'teamRun' | 'goalRun'>> & {
   freeze?: FreezeSnapshot & { redacted?: boolean } | null
   /** Replaces the handover bundle (restamping bundledAt); an explicit null clears it. */
   handover?: TaskHandoverInput | null
@@ -108,6 +108,9 @@ export function applyUpdateTask(
     if ('reuseSession' in patch) next.reuseSession = patch.reuseSession === true ? true : undefined
     // Team execution is a boolean opt-in with the same clear-by-false rule.
     if ('teamRun' in patch) next.teamRun = patch.teamRun === true ? true : undefined
+    // The /goal opt-in is default-ON: true (or an explicit null) returns the
+    // card to the default and stores nothing, only false pins a plain turn.
+    if ('goalRun' in patch) next.goalRun = patch.goalRun === false ? false : undefined
     if (workspaceId !== undefined || 'workspaceId' in patch) next.workspaceId = workspaceId
     if (mode !== undefined || 'mode' in patch) next.mode = mode
     if (permission !== undefined || 'permission' in patch) next.permission = permission

package/src/host/agent-tools.ts

@@ -94,6 +94,8 @@ function scheduleView(schedule: ScheduleRule): Record<string, unknown> {
   return {
     enabled: schedule.enabled,
     cron: schedule.cron,
+    // Absent means the rule follows the Host zone, which the board view reports.
+    ...(schedule.timeZone === undefined ? {} : { timeZone: schedule.timeZone }),
     ...(schedule.nextRunAt === undefined ? {} : { nextRunAt: schedule.nextRunAt }),
     ...(schedule.lastTriggeredAt === undefined ? {} : { lastTriggeredAt: schedule.lastTriggeredAt }),
   }
@@ -150,6 +152,8 @@ function taskSummary(
     ...(task.model === undefined ? {} : { model: task.model }),
     ...(task.reuseSession === true ? { reuseSession: true } : {}),
     ...(task.teamRun === true ? { teamRun: true } : {}),
+    // Default-ON switch: only the opt-out is a deviation worth reporting.
+    ...(task.goalRun === false ? { goalRun: false } : {}),
     ...(task.schedule === undefined ? {} : { schedule: scheduleView(task.schedule) }),
     ...(task.freeze === undefined ? {} : { continuationCard: true }),
     ...(task.permissionConfirmedAt === undefined ? {} : { permissionConfirmedAt: task.permissionConfirmedAt }),
@@ -334,18 +338,19 @@ function buildManageTool(host: TaskBoardToolHost): ToolDefinition {
   return defineTool({
     name: 'task_board_manage',
     description: [
-      'Move, archive, restore, or delete one task board card.',
+      'Move, archive, restore, delete, or settle one task board card.',
       'move-todo and move-backlog are the manual column moves; a running card cannot be moved.',
+      'settle force-closes the open execution of a card the board can no longer observe (a stuck running card) and records it cancelled with the caller as the reason, so the card returns to the todo column and can be run again.',
       'archive takes the whole subtask tree off the board and is refused while any member has an unsettled execution; restore brings the task, its ancestors and its subtree back; delete removes one card and is refused while it still has subtasks (detach or delete them first) or while it runs.',
       'It cannot confirm a permission binding: the confirmation gate is a human act performed in the board UI.',
-      'Triggers: 任务看板, task board, 看板, 归档, archive, 删除任务, delete task, 移动任务, move task.',
+      'Triggers: 任务看板, task board, 看板, 归档, archive, 删除任务, delete task, 移动任务, move task, 卡住, stuck, 强制结算, settle.',
     ].join(' '),
     parameters: {
       taskId: { type: 'string', required: true, description: 'The task to act on.' },
       action: {
         type: 'string',
         required: true,
-        enum: ['move-todo', 'move-backlog', 'archive', 'restore', 'delete'],
+        enum: ['move-todo', 'move-backlog', 'archive', 'restore', 'delete', 'settle'],
         description: 'The lifecycle operation to perform.',
       },
     },
@@ -356,6 +361,7 @@ function buildManageTool(host: TaskBoardToolHost): ToolDefinition {
         'move-todo': { kind: 'move', taskId: args.taskId, status: 'todo' },
         'move-backlog': { kind: 'move', taskId: args.taskId, status: 'backlog' },
         archive: { kind: 'archive', taskId: args.taskId },
+        settle: { kind: 'settle', taskId: args.taskId },
         restore: { kind: 'restore', taskId: args.taskId },
         delete: { kind: 'delete', taskId: args.taskId },
       }
@@ -381,7 +387,8 @@ function buildScheduleTool(host: TaskBoardToolHost): ToolDefinition {
   return defineTool({
     name: 'task_board_schedule',
     description: [
-      'Arm, change, or disarm a task scheduled runs (5-field cron in the Host local time zone; day-of-month and day-of-week use OR semantics).',
+      'Arm, change, or disarm a task scheduled runs (5-field cron; day-of-month and day-of-week follow Vixie semantics: both restricted means OR, otherwise AND).',
+      'The cron wall clock is read in the rule stored IANA time zone; omit timeZone to use the Host zone reported by task_board_list/task_board_get. DST gaps are skipped and an ambiguous fall-back time fires once, at the earlier instant.',
       'A due scheduled task runs the same cascade a manual run does, so a root task runs its whole subtask tree.',
       'A schedule whose tree contains an unconfirmed above-default permission is refused and rolls to its next occurrence; the reason is reported in the list board summary as schedulerError.',
       'Missed occurrences during Host downtime are skipped, never queued; a task that is already running skips its occurrence.',
@@ -391,20 +398,27 @@ function buildScheduleTool(host: TaskBoardToolHost): ToolDefinition {
       taskId: { type: 'string', required: true, description: 'The task whose schedule changes.' },
       enabled: { type: 'boolean', description: 'Arm (true) or disarm (false) the schedule.' },
       cron: { type: 'string', description: '5-field cron expression: minute hour day-of-month month day-of-week.' },
+      timeZone: {
+        type: 'string',
+        description: 'IANA zone the cron wall clock is read in (for example Asia/Shanghai). Omit to keep the stored zone, or pass an empty string to clear it back to the Host zone.',
+      },
     },
     output: { schema: { type: 'json' }, render: renderJson },
     async execute(args, exec) {
-      if (args.enabled === undefined && args.cron === undefined) {
-        return refused('nothing-to-change', 'pass enabled and/or cron')
+      if (args.enabled === undefined && args.cron === undefined && args.timeZone === undefined) {
+        return refused('nothing-to-change', 'pass enabled and/or cron and/or timeZone')
       }
       // A missing card must read as a missing card: the ledger reports an
       // unknown id through the same refusal as a malformed cron.
       if (!host.snapshot().tasks.some(task => task.id === args.taskId)) {
         return refused('task-not-found', 'no task with id ' + args.taskId)
       }
-      const patch: { enabled?: boolean; cron?: string } = {
+      const patch: { enabled?: boolean; cron?: string; timeZone?: string | null } = {
         ...(args.enabled === undefined ? {} : { enabled: args.enabled }),
         ...(args.cron === undefined ? {} : { cron: args.cron }),
+        // An empty string is the documented way to clear the stored zone, so
+        // the model never has to emit an explicit null through JSON args.
+        ...(args.timeZone === undefined ? {} : { timeZone: args.timeZone === '' ? null : args.timeZone }),
       }
       try {
         const snapshot = host.apply(crypto.randomUUID(), { kind: 'set-schedule', taskId: args.taskId, patch }, callingSessionId(exec))
@@ -514,6 +528,7 @@ function buildCreateTool(host: TaskBoardToolHost): ToolDefinition {
       model: { type: 'string', description: 'Pinned model as provider/model (or a model id); omit for the host default or the parent value.' },
       reuseSession: { type: 'boolean', description: 'Continue later runs in the previous execution session instead of a fresh conversation.' },
       teamRun: { type: 'boolean', description: 'Run this task as an Agent Team: running it starts one Team Lead session and the Host spawns a teammate per subtask inside it. Omit or false for one independent session per member. Refused when the deployment serves no Agent Teams service.' },
+      goalRun: { type: 'boolean', description: 'Start each run with dsh built-in /goal so the session keeps working continuation rounds until the goal completes. Default true (omit to keep it); pass false for a single plain turn.' },
       tags: {
         type: 'array',
         description: 'Labels: the name renders as a badge and drives the board filter; promptPrefix is injected ahead of the execution prompt on every run.',
@@ -555,6 +570,7 @@ function buildCreateTool(host: TaskBoardToolHost): ToolDefinition {
         ...(args.model === undefined || args.model === '' ? {} : { model: args.model }),
         ...(args.reuseSession === true ? { reuseSession: true } : {}),
         ...(args.teamRun === true ? { teamRun: true } : {}),
+        ...(args.goalRun === false ? { goalRun: false } : {}),
         ...(tags.length === 0 ? {} : { tags }),
         ...(args.schedule === undefined ? {} : { schedule: { enabled: args.schedule.enabled, cron: args.schedule.cron } }),
       }
@@ -587,10 +603,25 @@ function buildUpdateTool(host: TaskBoardToolHost): ToolDefinition {
       prompt: { type: 'string', description: 'New execution prompt.' },
       workspaceId: { type: 'string', description: 'New workspace id; an empty string clears it.' },
       mode: { type: 'string', description: 'New agent preset id; an empty string clears it.' },
-      permission: { type: 'string', enum: [...TASK_PERMISSIONS, ''], description: 'New permission preset; an empty string clears it back to the session default.' },
+      // `enum` with a clearing value would advertise the empty string as a
+      // legal member of the enum. Some OpenAI-compatible gateways forward the
+      // tool schema to Gemini, which rejects an empty enum member outright
+      // ("cannot be empty") and fails the whole request - not just this tool -
+      // even for a plain greeting, because the schema ships with every call
+      // (issue #1748). Splitting the clear value into its own `const` branch
+      // keeps both the real enum intact and the wire representation valid for
+      // those gateways.
+      permission: {
+        oneOf: [
+          { type: 'string', enum: [...TASK_PERMISSIONS] },
+          { type: 'string', const: '' },
+        ],
+        description: 'New permission preset; an empty string clears it back to the session default.',
+      },
       model: { type: 'string', description: 'New pinned model; an empty string clears it.' },
       reuseSession: { type: 'boolean', description: 'Continue later runs in the previous execution session.' },
       teamRun: { type: 'boolean', description: 'Switches this task between a plain cascade (one session per member) and an Agent Team run (Lead session plus a teammate per subtask).' },
+      goalRun: { type: 'boolean', description: 'Whether each run starts with dsh built-in /goal (default true). Pass false to run one plain turn instead.' },
       tags: {
         type: 'array',
         description: 'Replacement label set; an empty array clears all labels.',
@@ -619,6 +650,7 @@ function buildUpdateTool(host: TaskBoardToolHost): ToolDefinition {
       }
       if (has(args, 'reuseSession')) patch.reuseSession = args.reuseSession === true
       if (has(args, 'teamRun')) patch.teamRun = args.teamRun === true
+      if (has(args, 'goalRun')) patch.goalRun = args.goalRun === false ? false : true
       if (has(args, 'tags')) {
         const tags = args.tags ?? []
         patch.tags = tags.length === 0

package/src/host-ledger.ts

@@ -3,7 +3,7 @@ import { createHash } from 'node:crypto'
 import { chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { dshHome } from './dsh-home.ts'
-import { isValidCron, nextRunAtMs } from './core/schedule.ts'
+import { isValidCron, isValidTimeZone, nextRunAtMs, resolveHostTimeZone } from './core/schedule.ts'
 import { isTaskRecord, parseLedger } from './core/store.ts'
 import { canMoveManually, retainRecentExecutions, settleExecution, startExecution, withStatus, type ExecutionOutcome, type ExecutionRecord, type TaskRecord } from './core/tasks.ts'
 import {
@@ -21,7 +21,7 @@ import { applyDeleteTask } from './core/use-cases/task-delete.ts'
 import { applySetSchedule, applyScheduleNextRun } from './core/use-cases/task-schedule.ts'
 import { applySetParent } from './core/use-cases/task-parent.ts'
 import { applyUpdateTask, canEditTaskContent, hasContentPatch } from './core/use-cases/task-update.ts'
-import { TASK_BOARD_LEGACY_SCHEMA_VERSION, TASK_BOARD_SCHEMA_VERSION, type TaskBoardAction, type TaskBoardSchedulerSnapshot } from './protocol.ts'
+import { 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'
 
 interface PersistedScheduler extends TaskBoardSchedulerSnapshot {
@@ -84,12 +84,21 @@ export interface OpenExecutionReference {
   readonly executionId: string
   readonly sessionId: string | undefined
   readonly startedAt: number
+  /**
+   * True for a member of a team-mode run other than its Lead. A teammate is a
+   * durable member of the Team: it stays alive after its turn ends, so the
+   * roster may keep reporting its session as running, and the turn it completed
+   * is the only verdict it exposes.
+   */
+  readonly teamMember: boolean
 }
 
 /** Minimal value copy used by the Host scheduler. */
 export interface DueScheduleReference {
   readonly taskId: string
   readonly cron: string
+  /** Zone this rule's wall clock is read in. */
+  readonly timeZone: string
   readonly nextRunAt: number
 }
 
@@ -106,7 +115,12 @@ interface CachedRequest {
 }
 
 function timeZone(): string {
-  return Intl.DateTimeFormat().resolvedOptions().timeZone || 'local'
+  return resolveHostTimeZone()
+}
+
+/** The zone a schedule is evaluated in: its own, or the Host zone when it stores none. */
+function scheduleZone(schedule: { timeZone?: string }): string {
+  return schedule.timeZone ?? timeZone()
 }
 
 function cloneTasks(tasks: readonly TaskRecord[]): TaskRecord[] {
@@ -381,6 +395,7 @@ function parseHostTasks(values: readonly unknown[]): TaskRecord[] {
       schedule: {
         enabled: false,
         cron: schedule.cron,
+        ...(typeof schedule.timeZone === 'string' && isValidTimeZone(schedule.timeZone) ? { timeZone: schedule.timeZone } : {}),
         nextRunAt: undefined,
         lastTriggeredAt: typeof schedule.lastTriggeredAt === 'number' && Number.isFinite(schedule.lastTriggeredAt)
           ? schedule.lastTriggeredAt
@@ -426,6 +441,10 @@ export class HostTaskLedger {
       }
       this.repairSchedules(true)
       this.reconcileInterruptedStarts()
+      // Boot recovery also folds every already-decided run: a team run whose
+      // Lead recorded its verdict in an earlier process, and a lineage whose
+      // last settle never reached its parent, both leave the running column here.
+      this.finalizeReadyRuns(false)
       // Persist a freshly generated ledger identity and any recovery error
       // immediately, even when there are no tasks to trigger a later action.
       this.commit(false)
@@ -488,6 +507,15 @@ export class HostTaskLedger {
    */
   runtimeView(): LedgerRuntimeView {
     let armedSchedules = 0
+    // Run groups opened by a team-mode card: every other member of those groups
+    // runs as a teammate inside that card's Lead session.
+    const teamGroups = new Set<string>()
+    for (const task of this.document.tasks) {
+      if (task.teamRun !== true) continue
+      for (const execution of task.executions) {
+        if (execution.runGroupId !== undefined) teamGroups.add(execution.runGroupId)
+      }
+    }
     const openExecutions: OpenExecutionReference[] = []
     for (const task of this.document.tasks) {
       if (task.archivedAt === undefined && task.schedule?.enabled === true) armedSchedules += 1
@@ -501,6 +529,9 @@ export class HostTaskLedger {
           executionId: execution.id,
           sessionId: execution.sessionId,
           startedAt: execution.startedAt,
+          teamMember: task.teamRun !== true
+            && execution.runGroupId !== undefined
+            && teamGroups.has(execution.runGroupId),
         })
       }
     }
@@ -543,7 +574,7 @@ export class HostTaskLedger {
       if (task.archivedAt !== undefined) continue
       const schedule = task.schedule
       if (schedule === undefined || !schedule.enabled || schedule.nextRunAt === undefined || schedule.nextRunAt > now) continue
-      due.push({ taskId: task.id, cron: schedule.cron, nextRunAt: schedule.nextRunAt })
+      due.push({ taskId: task.id, cron: schedule.cron, timeZone: scheduleZone(schedule), nextRunAt: schedule.nextRunAt })
     }
     return due
   }
@@ -626,7 +657,7 @@ export class HostTaskLedger {
       const schedule = task.schedule
       if (schedule === undefined || !schedule.enabled || schedule.nextRunAt === undefined || schedule.nextRunAt > now) return task
       changed = true
-      return { ...task, schedule: { ...schedule, nextRunAt: nextRunAtMs(schedule.cron, now) }, updatedAt: now }
+      return { ...task, schedule: { ...schedule, nextRunAt: nextRunAtMs(schedule.cron, now, scheduleZone(schedule)) }, updatedAt: now }
     })
     if (changed) this.commit()
   }
@@ -681,16 +712,26 @@ export class HostTaskLedger {
       })
       changed = true
     }
+    // A team run is governed by its Lead: the Lead's own outcome closes whatever
+    // the Team still holds open, so the tree can never wait on a teammate that
+    // will never report one.
+    if (task.teamRun === true
+      && this.closeTeamMembers(taskId, groupId, execution.ownResult ?? outcome, execution.ownError ?? error, now)) changed = true
     if (this.settleCascade(taskId, groupId, now)) changed = true
     if (changed) this.commit()
   }
 
   attachSession(taskId: string, executionId: string, sessionId: string): void {
     const now = this.now()
-    this.document.tasks = this.document.tasks.map(task => task.id !== taskId ? task : {
-      ...task,
+    const task = this.document.tasks.find(item => item.id === taskId)
+    // A run the Lead's verdict already closed keeps its record: attaching a
+    // session to a settled execution would rewrite history the Host no longer
+    // observes (a teammate spawn that resolved after its Team was closed).
+    if (task?.executions.find(entry => entry.id === executionId)?.endedAt !== undefined) return
+    this.document.tasks = this.document.tasks.map(item => item.id !== taskId ? item : {
+      ...item,
       updatedAt: now,
-      executions: task.executions.map(entry => entry.id === executionId ? { ...entry, sessionId } : entry),
+      executions: item.executions.map(entry => entry.id === executionId ? { ...entry, sessionId } : entry),
     })
     this.commit()
   }
@@ -717,17 +758,22 @@ export class HostTaskLedger {
           : `invalid cron disabled for task(s): ${invalidScheduleIds.join(', ')}`
         this.repairSchedules(true, false)
         this.reconcileInterruptedStarts(false)
+        // An imported document may carry a decided-but-open run; fold it in the
+        // same action (apply() commits once at the end).
+        this.finalizeReadyRuns(false)
         break
       }
       case 'create': {
         if (this.document.tasks.some(task => task.id === action.id)) throw new Error('task id already exists')
-        if (action.input.schedule?.enabled === true && (!isValidCron(action.input.schedule.cron) || nextRunAtMs(action.input.schedule.cron, now) === undefined)) {
+        if (action.input.schedule?.enabled === true && (!isValidCron(action.input.schedule.cron)
+          || !isValidTimeZone(action.input.schedule.timeZone ?? timeZone())
+          || nextRunAtMs(action.input.schedule.cron, now, action.input.schedule.timeZone ?? timeZone()) === undefined)) {
           throw new Error('invalid schedule')
         }
         const input = action.input.freeze === undefined || initiator === undefined || initiator === ''
           ? action.input
           : { ...action.input, freeze: { ...action.input.freeze, frozenBy: initiator } }
-        const result = applyCreateTask(this.document.tasks, input, now, action.id, this.maxSubtaskDepth)
+        const result = applyCreateTask(this.document.tasks, input, now, action.id, this.maxSubtaskDepth, timeZone())
         if (result.task === undefined) throw new Error(result.error ?? 'invalid task')
         this.document.tasks = [...result.tasks]
         break
@@ -786,6 +832,34 @@ export class HostTaskLedger {
         this.document.tasks = [...result.tasks]
         break
       }
+      case 'settle': {
+        const task = this.document.tasks.find(item => item.id === action.taskId)
+        if (task === undefined) throw new Error('task not found')
+        if (task.archivedAt !== undefined) throw new Error('archived task is read-only')
+        if (!task.executions.some(entry => entry.endedAt === undefined)) throw new Error('task has no open execution')
+        // Force-close the executions this card governs. The verdict is
+        // 'cancelled', never 'succeeded': a card whose execution produced no
+        // evidence of a completed turn must not be recorded as finished work,
+        // and a cancelled settlement returns the card to the todo column so the
+        // operator can run it again. Nothing else clears a running card: move,
+        // archive and delete all refuse one, which is what made a stuck card
+        // unrecoverable from the board.
+        const reason = 'execution closed manually by '
+          + (initiator === undefined || initiator === '' ? 'the operator' : initiator)
+          + ': no verdict was recorded'
+        for (const member of cascadeTargets(this.document.tasks, action.taskId, this.maxSubtaskDepth)) {
+          for (const execution of member.executions) {
+            if (execution.endedAt !== undefined) continue
+            this.document.tasks = this.document.tasks.map(item => item.id !== member.id
+              ? item
+              : settleExecution(item, execution.id, 'cancelled', now, reason))
+          }
+        }
+        // Fold whatever became ready in the same action: an ancestor whose last
+        // member this closed leaves the running column with it.
+        this.finalizeReadyRuns(false)
+        break
+      }
       case 'restore': {
         if (this.subtreeHasOpenExecution(action.taskId)) throw new Error('running task cannot be restored')
         const result = applyRestoreTask(this.document.tasks, action.taskId, now, this.maxSubtaskDepth)
@@ -805,7 +879,7 @@ export class HostTaskLedger {
       case 'set-schedule': {
         const task = this.document.tasks.find(task => task.id === action.taskId)
         if (task?.archivedAt !== undefined) throw new Error('archived task is read-only')
-        const result = applySetSchedule(this.document.tasks, action.taskId, action.patch, now)
+        const result = applySetSchedule(this.document.tasks, action.taskId, action.patch, now, timeZone())
         if (!result.applied) throw new Error('invalid schedule')
         this.document.tasks = [...result.tasks]
         break
@@ -959,6 +1033,95 @@ export class HostTaskLedger {
     return changed
   }
 
+  /**
+   * Close every run that is already decided, and fold every lineage whose
+   * members are all settled. The Host poll calls this on every tick, so a run
+   * can no longer be left in the running column by a settle nobody observed:
+   *
+   * - A team run is governed by its Lead. Once the Lead's own outcome is
+   *   recorded, its still-open members are settled with that verdict. A
+   *   teammate is a durable member of the Team and may never report a turn of
+   *   its own, and without this the whole lineage waits on it forever.
+   * - A cascade parent whose members are all settled is finalized here even
+   *   when the settle that completed the tree happened in another process, or
+   *   was interrupted between its child write and its parent write.
+   *
+   * Idempotent: a run that is already folded is left untouched, so a caller may
+   * invoke it on every tick.
+   * @param persist - false to leave the document for the caller to commit.
+   * @returns whether the document changed.
+   */
+  finalizeReadyRuns(persist = true): boolean {
+    const now = this.now()
+    let changed = false
+    const groups = new Set<string>()
+    for (const task of this.document.tasks) {
+      for (const execution of task.executions) {
+        if (execution.endedAt === undefined && execution.runGroupId !== undefined) groups.add(execution.runGroupId)
+      }
+    }
+    for (const groupId of groups) {
+      const lead = this.document.tasks.find(task => task.teamRun === true
+        && task.executions.some(entry => entry.runGroupId === groupId))
+      const verdict = lead === undefined ? undefined : this.leadVerdict(lead, groupId)
+      if (lead !== undefined && verdict !== undefined
+        && this.closeTeamMembers(lead.id, groupId, verdict.result, verdict.error, now)) changed = true
+      // Fold the lineage: a member may itself be a parent of a deeper member.
+      for (const task of this.document.tasks) {
+        if (this.settleCascade(task.id, groupId, now)) changed = true
+      }
+    }
+    if (changed && persist) this.commit()
+    return changed
+  }
+
+  /**
+   * The verdict a team run's Lead has already recorded: its own turn outcome
+   * once that turn ended, or the folded outcome once its card settled.
+   */
+  private leadVerdict(lead: TaskRecord, groupId: string): { result: ExecutionOutcome; error: string | undefined } | undefined {
+    const execution = lead.executions.find(entry => entry.runGroupId === groupId)
+    const result = execution?.ownResult ?? execution?.result
+    if (result === undefined) return undefined
+    return { result, error: execution?.ownError ?? execution?.error }
+  }
+
+  /**
+   * Settle every still-open member of a team run with the Lead's verdict.
+   * A teammate that already reported its own outcome keeps it: the ordinary
+   * fold still lets a failure dominate.
+   * @param leadId - the Lead card's task id (never settled here).
+   * @param groupId - the team run's group.
+   * @param verdict - the Lead's outcome, inherited by members that never reported.
+   * @param error - the Lead's failure text, inherited with a failed verdict.
+   * @param now - clock instant (ms epoch).
+   * @returns whether the document changed.
+   */
+  private closeTeamMembers(leadId: string, groupId: string, verdict: ExecutionOutcome, error: string | undefined, now: number): boolean {
+    const members: string[] = []
+    let recorded = false
+    this.document.tasks = this.document.tasks.map(task => {
+      if (task.id === leadId) return task
+      const execution = openGroupExecution(task, groupId)
+      if (execution === undefined) return task
+      members.push(task.id)
+      if (execution.ownResult !== undefined) return task
+      recorded = true
+      return {
+        ...task,
+        updatedAt: now,
+        executions: task.executions.map(entry => entry.id === execution.id
+          ? { ...entry, ownResult: verdict, ownError: error }
+          : entry),
+      }
+    })
+    let changed = recorded
+    for (const memberId of members) {
+      if (this.settleCascade(memberId, groupId, now)) changed = true
+    }
+    return changed
+  }
+
   private repairSchedules(skipPast: boolean, persist = true): void {
     const now = this.now()
     let changed = false
@@ -966,7 +1129,7 @@ export class HostTaskLedger {
       const schedule = task.schedule
       if (schedule === undefined || !schedule.enabled) return task
       if (!skipPast && schedule.nextRunAt !== undefined) return task
-      const next = nextRunAtMs(schedule.cron, now)
+      const next = nextRunAtMs(schedule.cron, now, scheduleZone(schedule))
       if (next === undefined) {
         changed = true
         this.document.scheduler.error = `invalid cron disabled for task: ${task.id}`
@@ -1003,35 +1166,52 @@ export class HostTaskLedger {
   }
 
   /**
-   * Field-preserving v2 to v3 migration. v3 adds no fields yet, so the
-   * migration reuses the v3 normalization, but it first proves every task
-   * row is structurally valid: a v2 document that would silently drop or
-   * coerce rows fails loudly instead (no quarantined-empty restart).
+   * Field-preserving migration of a pre-v4 document. It first proves every task
+   * row is structurally valid, so a document that would silently drop or coerce
+   * rows fails loudly instead (no quarantined-empty restart), and then reuses
+   * the current normalization.
+   *
+   * v4 adds `ScheduleRule.timeZone`. A rule written before v4 was evaluated in
+   * whatever zone the Host process happened to report, so the migration stamps
+   * that zone onto every enabled rule: the trigger instant is preserved exactly
+   * (the stored `nextRunAt` already encodes the old zone), but the rule stops
+   * following a later `TZ` change, which is what made an existing schedule
+   * silently move when the Host's zone changed.
    */
   private migrateLegacyDocument(parsed: ParsedLedgerDocument): LedgerDocument {
     if (!Array.isArray(parsed.tasks) || !parsed.tasks.every(row => isTaskRecord(row))) {
-      throw new Error('v2 document contains structurally invalid task rows')
+      throw new Error(`v${String(parsed.schemaVersion)} document contains structurally invalid task rows`)
     }
-    return this.normalizeDocument(parsed)
+    // Every row passed `isTaskRecord` above, so the stamped rows are still
+    // task records; the cast only re-narrows the unknown-typed on-disk array.
+    const rows = (parsed.tasks as readonly unknown[]).map((value) => {
+      const row = value as { schedule?: unknown }
+      const schedule = row.schedule
+      if (typeof schedule !== 'object' || schedule === null) return value
+      if (typeof (schedule as { timeZone?: unknown }).timeZone === 'string') return value
+      return { ...(value as object), schedule: { ...(schedule as object), timeZone: timeZone() } }
+    })
+    return this.normalizeDocument({ ...parsed, tasks: rows as TaskRecord[] })
   }
 
   private load(dir: string): LedgerDocument {
     const existed = existsSync(this.file)
-    // schemaVersion stays unknown-typed here: on-disk documents may be v2
-    // (legacy), v3, or any future/invalid value the branches below sort out.
+    // schemaVersion stays unknown-typed here: on-disk documents may be v2 or
+    // v3 (legacy), v4, or any future/invalid value the branches below sort out.
     let parsed: ParsedLedgerDocument
     try {
       parsed = JSON.parse(readFileSync(this.file, 'utf8')) as ParsedLedgerDocument
     } catch (error) {
       return this.recoverCorrupt(dir, existed, error)
     }
-    if (parsed.schemaVersion === TASK_BOARD_LEGACY_SCHEMA_VERSION) {
+    if (parsed.schemaVersion === TASK_BOARD_LEGACY_SCHEMA_VERSION
+      || parsed.schemaVersion === TASK_BOARD_OLDER_SCHEMA_VERSION) {
       try {
         return this.migrateLegacyDocument(parsed)
       } catch (error) {
-        // Migration failure is explicit: the original v2 file stays in place
+        // Migration failure is explicit: the original file stays in place
         // for manual recovery and the ledger refuses to start (fail closed).
-        throw new Error(`ledger v2 to v3 migration failed; original file kept at ${this.file}: ${error instanceof Error ? error.message : String(error)}`)
+        throw new Error(`ledger v${String(parsed.schemaVersion)} to v${TASK_BOARD_SCHEMA_VERSION} migration failed; original file kept at ${this.file}: ${error instanceof Error ? error.message : String(error)}`)
       }
     }
     try {