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

package/src/host-runner.ts

@@ -60,6 +60,17 @@ function isDefinitionWithdrawn(error: unknown): boolean {
 
 const SERVICE_UNAVAILABLE_ATTEMPTS = 5
 const SERVICE_UNAVAILABLE_BACKOFF_MS = 2_000
+/**
+ * Largest number of history pages one inspection walks back. A session whose
+ * window is wider than this cannot be resolved from its log, which the caller
+ * treats as an unreadable history rather than as pending work.
+ */
+const HISTORY_PAGE_LIMIT = 100
+
+/** One-line text of a gateway or stream failure, for a decideable reason. */
+function failureText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
 
 function delay(ms: number): Promise<void> {
   return new Promise(resolve => { setTimeout(resolve, ms) })
@@ -87,7 +98,14 @@ export interface SessionCommandDispatcher {
 }
 
 export type ExecutionInspection =
-  | { outcome: 'pending' }
+  /**
+   * No verdict yet. `unreadable` separates "the work may still be in progress"
+   * from "this session's history could not be read at all": a reader failure is
+   * not progress, and the caller decides how long to keep waiting before it
+   * reports the execution as undeterminable instead of holding a card open
+   * forever.
+   */
+  | { outcome: 'pending'; unreadable?: true; reason?: string }
   | { outcome: 'succeeded' }
   | { outcome: 'failed'; error: string }
   | { outcome: 'cancelled'; error: string }
@@ -136,6 +154,13 @@ export interface PromptContext {
   peers?: readonly PromptPeer[]
   /** True when those members run as teammates inside this session (Team Lead). */
   team?: boolean
+  /**
+   * Scheduled-run provenance: the instant the cron rule actually fired and the
+   * IANA zone its wall clock was read in. Present only for a cron-triggered
+   * run, so the model can resolve an unqualified date in the run's own terms
+   * instead of guessing from the Host clock (issue #1722).
+   */
+  schedule?: { triggeredAt: number; timeZone: string; cron: string }
 }
 
 /**
@@ -147,13 +172,27 @@ function peerPromptPreamble(context: PromptContext): string | undefined {
   const peers = context.peers ?? []
   if (peers.length === 0) return undefined
   if (context.team === true) {
-    const lines = peers.map(peer => `- ${escapeProvenanceDelimiter(peer.title)}（teammate: ${peer.name ?? teammateName(peer.title, peer.id)}）`)
+    const lines = peers.map(peer => `- ${escapeProvenanceDelimiter(peer.title)}（teammate: ${peer.name ?? teammateName(peer.title, peer.id, peer.id)}）`)
     return `本任务是 Agent Team 的 Lead：本次运行不额外开启独立会话，以下 ${peers.length} 个子任务成员已在本会话中作为 teammate 启动。用 list_agents / send_message / wait_agent 协调它们，用任务看板工具读写它们在看板上的卡片：\n${lines.join('\n')}`
   }
   const lines = peers.map(peer => `- ${escapeProvenanceDelimiter(peer.title)}（任务 ${peer.id}）`)
   return `本次运行同时并发开启 ${peers.length} 个独立 DSH 会话执行下列子任务成员（可用 task_board_* 工具查看它们的进度）：\n${lines.join('\n')}`
 }
 
+/**
+ * The scheduled-run section: this execution was triggered by the card's cron
+ * rule rather than by a person. It states the firing instant, the rule's zone,
+ * and the rule text, so the run's own clock is unambiguous — the board's
+ * scheduler fires on a wall clock in a specific IANA zone, which is not
+ * necessarily the zone of whatever session the run lands in.
+ */
+function schedulePromptPreamble(context: PromptContext): string | undefined {
+  const schedule = context.schedule
+  if (schedule === undefined) return undefined
+  const stamp = new Date(schedule.triggeredAt).toISOString()
+  return `本次执行由任务看板的定时规则自动触发：触发时间 ${stamp}（UTC），规则时区 ${schedule.timeZone}，cron 表达式 ${schedule.cron}。需要判断「今天」「现在」或计算时间窗口时，以该时区的触发时间为准。`
+}
+
 /**
  * Build the execution prompt for one task.
  * @param task - the task being launched.
@@ -167,11 +206,14 @@ export function promptText(task: TaskRecord, context: PromptContext = {}): strin
     ? undefined
     : `交接包引用（来自任务看板续接卡片，冻结于 ${new Date(handover.bundledAt).toISOString()}）：\n${handover.references.map(reference => `- ${reference}`).join('\n')}`
   // Tag prompts come first: they are the run's standing context (business line,
-  // output location), the handover preamble is a per-card note, and the task
-  // body is the instruction itself.
+  // output location), the handover preamble is a per-card note, the scheduled
+  // section states why this run exists, and the task body is the instruction.
   const tagPreamble = tagPromptPreamble(task)
+  const handoverSection = handoverPreamble
+  const schedulePreamble = schedulePromptPreamble(context)
   const runPreamble = peerPromptPreamble(context)
-  const preambles = [tagPreamble, handoverPreamble, runPreamble].filter((part): part is string => part !== undefined)
+  const preambles = [tagPreamble, handoverSection, schedulePreamble, runPreamble]
+    .filter((part): part is string => part !== undefined)
   const preamble = preambles.length === 0 ? undefined : preambles.join('\n\n')
   const freeze = task.freeze
   if (freeze === undefined) {
@@ -182,6 +224,27 @@ export function promptText(task: TaskRecord, context: PromptContext = {}): strin
   return preamble === undefined ? declaration : `${preamble}\n\n${declaration}`
 }
 
+/**
+ * The parts of an objective the built-in `/goal` command reads as an operation
+ * rather than as an objective: an exact `clear`/`pause`/`resume`/`edit`
+ * (case-insensitive) and a leading `edit <objective>`.
+ */
+const GOAL_COMMAND_KEYWORD = /^(?:clear|pause|resume|edit)$|^edit\s/i
+
+/**
+ * Build the objective the built-in `/goal` command receives. A prompt whose
+ * text would be read as a goal operation is prefixed with a neutral label: the
+ * instruction stays intact, and the command arms an objective instead of
+ * clearing, pausing, or editing an unrelated goal (or refusing for a missing
+ * one).
+ * @param prompt - the composed execution prompt.
+ * @returns the objective text for `/goal <objective>`.
+ */
+export function goalObjective(prompt: string): string {
+  const text = prompt.trim()
+  return GOAL_COMMAND_KEYWORD.test(text) ? `Goal: ${text}` : text
+}
+
 /**
  * Build the tag section of the execution prompt (issue #1521). Only tags with
  * a non-blank `promptPrefix` contribute; a task whose tags are all bare names
@@ -393,6 +456,82 @@ export class HostExecutionRunner {
       mode: 'queue' as const,
       content: [{ type: 'text' as const, text: promptText(task, context) }],
     })
+    await this.armGoal(sessionId, task, context)
+  }
+
+  /**
+   * Arm dsh's built-in goal on the session. The task prompt is queued FIRST, so
+   * the session's first turn carries the instruction verbatim; `/goal
+   * <objective>` then turns the same text into a persistent objective, and
+   * dsh's goal-round driver keeps starting continuation rounds until the agent
+   * marks it complete (see {@link goalVerdict} for how the run settles).
+   *
+   * Opt-out: a task whose `goalRun` is an explicit false runs one plain turn.
+   * A refusal (no command dispatcher, no `/goal` command in this cohort, an
+   * objective the command rejects) is reported and the run continues as that
+   * plain turn: the task was asked to run, and a missing goal mode must not
+   * lose the work.
+   */
+  private async armGoal(sessionId: ExecutionSessionId, task: TaskRecord, context: PromptContext): Promise<void> {
+    if (task.goalRun === false) return
+    if (this.commands === undefined) {
+      console.warn('[dsh-task-board] no command dispatcher is available; task ' + task.id + ' runs without /goal')
+      return
+    }
+    try {
+      const command = await this.commands.execute(
+        sessionId,
+        '/goal ' + goalObjective(promptText(task, context)),
+        AbortSignal.timeout(30_000),
+      )
+      if (command === undefined) {
+        console.warn('[dsh-task-board] /goal was not acknowledged for session ' + sessionId + '; the run continues as a plain turn')
+        return
+      }
+      if (command.kind !== 'success') {
+        console.warn('[dsh-task-board] /goal was refused for session ' + sessionId + ': ' + (command.text ?? 'no reason reported') + '; the run continues as a plain turn')
+      }
+    } catch (error) {
+      console.warn('[dsh-task-board] could not arm /goal on session ' + sessionId + '; the run continues as a plain turn', error)
+    }
+  }
+
+  /**
+   * The verdict an armed dsh goal imposes on an otherwise completed turn.
+   *
+   * A goal run is one session working many automatic continuation rounds:
+   * dsh's goal-round driver queues the next round whenever the agent goes
+   * idle, so the first completed `turn/end` is not the execution's result.
+   * Settling there would leave the card in `done` while the session keeps
+   * working, and a scheduled task would fire a second, concurrent session.
+   * The session projection is the authority: an `active` goal keeps the
+   * execution pending, a `blocked` goal fails it with the recorded reason, and
+   * any other phase (complete, paused, or no goal at all) leaves the turn
+   * verdict in place.
+   *
+   * An unreadable projection falls back to that turn verdict: a cohort whose
+   * gateway withdrew `session/projections` must not hang every execution.
+   */
+  private async goalVerdict(sessionId: string): Promise<ExecutionInspection | undefined> {
+    let projections: { values?: { goal?: unknown } } | null
+    try {
+      projections = await this.invoke('session', 'projections', { sessionId }) as { values?: { goal?: unknown } } | null
+    } catch (error) {
+      console.warn('[dsh-task-board] session/projections failed while reading the goal phase; settling from the turn result', error)
+      return undefined
+    }
+    const goal = projections?.values?.goal
+    if (goal === undefined || goal === null) return undefined
+    const view = (goal as { goal?: { phase?: unknown; blockedReason?: { message?: unknown } } }).goal
+    if (view?.phase === 'active') return { outcome: 'pending' }
+    if (view?.phase === 'blocked') {
+      const message = view.blockedReason?.message
+      return {
+        outcome: 'failed',
+        error: 'goal is blocked: ' + (typeof message === 'string' && message !== '' ? message : 'no reason recorded'),
+      }
+    }
+    return undefined
   }
 
   async listRunning(): Promise<{ known: true; count: number; items: SessionSummary[] } | { known: false }> {
@@ -424,8 +563,17 @@ export class HostExecutionRunner {
     }
   }
 
-  /** Resolve an execution outcome from the session list and bounded history pages. */
-  async inspect(sessionId: string, startedAt = 0, sessions?: readonly SessionSummary[]): Promise<ExecutionInspection> {
+  /**
+   * Resolve an execution outcome from the session list and bounded history pages.
+   * @param sessionId - the session the execution runs in.
+   * @param startedAt - instant the execution opened; earlier events are not its own.
+   * @param sessions - roster from the caller's own poll, when it already has one.
+   * @param options.whileRunning - read the first completed turn even while the
+   *   roster reports the session as running. A durable Agent Teams teammate
+   *   stays alive after its turn ends, so `running` never clears for it and the
+   *   turn it completed is the only verdict it will ever expose.
+   */
+  async inspect(sessionId: string, startedAt = 0, sessions?: readonly SessionSummary[], options: { whileRunning?: boolean } = {}): Promise<ExecutionInspection> {
     let items: readonly SessionSummary[]
     if (sessions !== undefined) {
       items = sessions
@@ -455,7 +603,7 @@ export class HostExecutionRunner {
       this.scanMemos.delete(sessionId)
       return { outcome: 'cancelled', error: 'execution session no longer exists' }
     }
-    if (summary.running) return { outcome: 'pending' }
+    if (summary.running && options.whileRunning !== true) return { outcome: 'pending' }
 
     let opening: { cursor: number; records: readonly SessionHistoryRecord[]; hasMore: boolean }
     try {
@@ -465,12 +613,12 @@ export class HostExecutionRunner {
       if (typeof iterator.return === 'function') await iterator.return()
       const follow = next.done === true ? undefined : next.value as { type?: string; cursor?: number; records?: readonly SessionHistoryRecord[]; hasMore?: boolean }
       if (follow === undefined || follow.type !== 'snapshot' || typeof follow.cursor !== 'number' || follow.records === undefined || typeof follow.hasMore !== 'boolean') {
-        return { outcome: 'pending' }
+        return { outcome: 'pending', unreadable: true, reason: 'session/follow returned no opening frame' }
       }
       opening = { cursor: follow.cursor, records: follow.records, hasMore: follow.hasMore }
     } catch (error) {
       console.warn('[dsh-task-board] session/follow failed during execution inspection; keeping the outcome pending', error)
-      return { outcome: 'pending' }
+      return { outcome: 'pending', unreadable: true, reason: 'session/follow failed: ' + failureText(error) }
     }
     const openingEvents = opening.records.map(record => ({ event: recordEvent(record) }))
     const newestSeq = openingEvents.reduce<number | undefined>((newest, entry) => newest === undefined ? entry.event.seq : Math.max(newest, entry.event.seq), undefined)
@@ -478,7 +626,7 @@ export class HostExecutionRunner {
     const events: Array<{ event: { type: string; seq: number; time: number; data: unknown } }> = [...openingEvents]
     let beforeSeq: number | undefined
     let reachedExecutionBoundary = !opening.hasMore
-    for (let page = 0; page < 100 && !reachedExecutionBoundary; page += 1) {
+    for (let page = 0; page < HISTORY_PAGE_LIMIT && !reachedExecutionBoundary; page += 1) {
       let history: SessionPage
       try {
         history = await this.invoke('session', 'page', {
@@ -489,7 +637,7 @@ export class HostExecutionRunner {
         }) as SessionPage
       } catch (error) {
         console.warn('[dsh-task-board] session/page failed during execution inspection; keeping the outcome pending', error)
-        return { outcome: 'pending' }
+        return { outcome: 'pending', unreadable: true, reason: 'session/page failed: ' + failureText(error) }
       }
       const pageEntries = pageEvents(history)
       events.push(...pageEntries)
@@ -502,7 +650,9 @@ export class HostExecutionRunner {
       if (oldestSeq === undefined || oldestSeq === beforeSeq) return { outcome: 'pending' }
       beforeSeq = oldestSeq
     }
-    if (!reachedExecutionBoundary) return { outcome: 'pending' }
+    if (!reachedExecutionBoundary) {
+      return { outcome: 'pending', unreadable: true, reason: 'history scan did not reach the execution start within ' + HISTORY_PAGE_LIMIT + ' pages' }
+    }
     const turnEnd = events
       .filter(entry => entry.event.type === 'turn/end' && (startedAt <= 0 || entry.event.time >= startedAt))
       .sort((a, b) => a.event.seq - b.event.seq)[0]
@@ -512,7 +662,7 @@ export class HostExecutionRunner {
     }
     this.scanMemos.delete(sessionId)
     const reason = nonCompletedTurnEnd(turnEnd.event.data)
-    if (reason === undefined) return { outcome: 'succeeded' }
+    if (reason === undefined) return await this.goalVerdict(sessionId) ?? { outcome: 'succeeded' }
     // `error` keeps its historical wording; every other non-completed reason
     // (aborted / blocked / max-tokens / interrupted) now reports instead of
     // silently counting as success.

package/src/host-service.ts

@@ -50,6 +50,26 @@ const SESSION_POLL_MS = 5_000
 const RECOVERY_TOLERANCE_MS = 60_000
 /** Largest delay a Node timer represents without clamping; longer targets re-arm in segments. */
 const MAX_TIMER_DELAY_MS = 2_147_483_647
+/**
+ * Consecutive polls that may report one execution's session history as
+ * unreadable before it is reported failed. The roster poll runs every 5 s, so
+ * this is two minutes of a session that is NOT running: no turn is executing
+ * there and its history cannot be read, which means no verdict will ever
+ * arrive. Reporting that as a failure keeps a card — and every ancestor of it —
+ * out of the running column, which nothing else can rescue.
+ */
+const UNREADABLE_SETTLE_POLLS = 24
+
+/**
+ * Provenance of one cron-triggered cascade: when the rule fired and the zone
+ * its wall clock was read in. Passed into every launched prompt of that run so
+ * a scheduled job knows its own clock rather than inferring one.
+ */
+export interface ScheduledRunContext {
+  triggeredAt: number
+  timeZone: string
+  cron: string
+}
 
 /**
  * Actions that can move an armed trigger. Only these re-arm the native timer;
@@ -102,6 +122,12 @@ export class TaskBoardHostService {
    * conversation instead of prompting into a session it cannot see.
    */
   private idleSessionIds: ReadonlySet<string> | undefined
+  /**
+   * Consecutive unreadable-history polls per open execution (see
+   * {@link noteUnreadableInspection}). Cleared as soon as an inspection
+   * resolves, so a transient reader failure never fails a card.
+   */
+  private readonly unreadablePolls = new Map<string, number>()
   private preventIdleSleep = false
   private readonly team: TaskBoardTeamDispatcher | undefined
   private readonly timers: HostTimerFace
@@ -239,7 +265,7 @@ export class TaskBoardHostService {
     this.listeners.clear()
   }
 
-  private async launch(opened: OpenedRun, others: readonly OpenedRun[] = []): Promise<void> {
+  private async launch(opened: OpenedRun, others: readonly OpenedRun[] = [], schedule?: ScheduledRunContext): Promise<void> {
     try {
       // A team run always mints a fresh Lead session: teammates are immutable
       // children of that session, so reusing an older one would collide on
@@ -248,13 +274,17 @@ export class TaskBoardHostService {
       const reuseSessionId = team ? undefined : reusableSessionId(opened.task, this.idleSessionIds)
       // Both modes tell the launched agent what else this run opens; only a team
       // run names teammates, because only then does this session own them.
-      const promptContext = others.length === 0 ? undefined : {
-        peers: others.map(other => ({
-          id: other.task.id,
-          title: other.task.title,
-          ...(team ? { name: teammateName(other.task.title, other.execution.runGroupId ?? other.task.id) } : {}),
-        })),
+      const peers = others.length === 0 ? undefined : others.map(other => ({
+        id: other.task.id,
+        title: other.task.title,
+        ...(team ? { name: teammateName(other.task.title, other.execution.runGroupId ?? other.task.id, other.task.id) } : {}),
+      }))
+      // A cron-triggered run additionally states its own firing instant and
+      // rule zone, so a scheduled job can resolve "today" without guessing.
+      const promptContext = peers === undefined && schedule === undefined ? undefined : {
+        ...(peers === undefined ? {} : { peers }),
         ...(team ? { team: true } : {}),
+        ...(schedule === undefined ? {} : { schedule }),
       }
       const sessionId = await this.runner.launch(opened.task, {
         ...(reuseSessionId === undefined ? {} : { reuseSessionId }),
@@ -292,7 +322,7 @@ export class TaskBoardHostService {
     try {
       const member = await team.spawn({
         leadSessionId,
-        name: teammateName(opened.task.title, opened.execution.runGroupId ?? opened.task.id),
+        name: teammateName(opened.task.title, opened.execution.runGroupId ?? opened.task.id, opened.task.id),
         description: opened.task.title,
         prompt: promptText(opened.task),
       })
@@ -321,6 +351,10 @@ export class TaskBoardHostService {
       return
     }
     this.idleSessionIds = new Set(running.items.filter(item => !item.running).map(item => item.sessionId))
+    // Fold whatever the board can already decide before spending inspection
+    // RPCs: a team run whose Lead recorded its verdict, and any lineage whose
+    // members are all settled. Idempotent, so an already folded board is free.
+    this.ledger.finalizeReadyRuns()
     // Read after the RPC so executions attached while it was in flight are
     // included in this pass, matching the former full-state snapshot timing.
     const runtime = this.ledger.runtimeView()
@@ -342,13 +376,53 @@ export class TaskBoardHostService {
     for (const execution of executions) {
       if (execution.sessionId === undefined) continue
       try {
-        const result = await this.runner.inspect(execution.sessionId, execution.startedAt, sessions)
-        if (result.outcome === 'pending') continue
+        // A team member's turn is read even while the roster calls its session
+        // running: a durable teammate never goes idle for good.
+        const result = await this.runner.inspect(execution.sessionId, execution.startedAt, sessions, {
+          whileRunning: execution.teamMember,
+        })
+        if (result.outcome === 'pending') {
+          if (result.unreadable === true) this.noteUnreadableInspection(execution, result.reason)
+          else this.unreadablePolls.delete(execution.executionId)
+          continue
+        }
+        this.unreadablePolls.delete(execution.executionId)
         this.ledger.settle(execution.taskId, execution.executionId, result.outcome, 'error' in result ? result.error : undefined)
       } catch {
         // A transient inspection failure never settles a running execution.
       }
     }
+    const open = new Set(executions.map(execution => execution.executionId))
+    for (const executionId of [...this.unreadablePolls.keys()]) {
+      if (!open.has(executionId)) this.unreadablePolls.delete(executionId)
+    }
+  }
+
+  /**
+   * Count one poll whose session history could not be read. A reader failure is
+   * not progress: the session is not running (the runner only reads history for
+   * one that is idle), so nothing will ever change that verdict. After
+   * {@link UNREADABLE_SETTLE_POLLS} consecutive polls the execution is reported
+   * failed with the recorded reason, instead of holding its card — and every
+   * ancestor of it — in the running column with no way out. The first poll of
+   * each streak is logged, so the Host log names the session.
+   */
+  private noteUnreadableInspection(execution: OpenExecutionReference, reason: string | undefined): void {
+    const polls = (this.unreadablePolls.get(execution.executionId) ?? 0) + 1
+    this.unreadablePolls.set(execution.executionId, polls)
+    const detail = reason ?? 'no reason reported'
+    if (polls === 1) {
+      safeConsoleError('[dsh-task-board] execution session ' + (execution.sessionId ?? 'unknown')
+        + ' history is unreadable; it stays pending for up to ' + UNREADABLE_SETTLE_POLLS + ' polls: ' + detail)
+    }
+    if (polls < UNREADABLE_SETTLE_POLLS) return
+    this.unreadablePolls.delete(execution.executionId)
+    this.ledger.settle(
+      execution.taskId,
+      execution.executionId,
+      'failed',
+      'execution session history is unreadable (' + UNREADABLE_SETTLE_POLLS + ' consecutive polls); the outcome cannot be determined: ' + detail,
+    )
   }
 
   /** Drop the armed schedule timer and forget its target. */
@@ -411,8 +485,11 @@ export class TaskBoardHostService {
       return
     }
     for (const schedule of this.ledger.dueSchedules(now)) {
-      const next = nextRunAtMs(schedule.cron, schedule.nextRunAt)
-      this.dispatchRuns(this.ledger.openScheduled(schedule.taskId, next, now))
+      const next = nextRunAtMs(schedule.cron, schedule.nextRunAt, schedule.timeZone)
+      this.dispatchRuns(
+        this.ledger.openScheduled(schedule.taskId, next, now),
+        { triggeredAt: now, timeZone: schedule.timeZone, cron: schedule.cron },
+      )
     }
     // The launched run (or the rolled-forward target) moved every due schedule,
     // so the next nearest target has to be recomputed from the ledger.
@@ -430,18 +507,18 @@ export class TaskBoardHostService {
    * others back. A team run's members are spawned inside the root's Lead
    * session instead, once that session exists.
    */
-  private dispatchRuns(runs: readonly OpenedRun[]): void {
+  private dispatchRuns(runs: readonly OpenedRun[], schedule?: ScheduledRunContext): void {
     if (runs.length === 0) return
     const root = runs.find(run => run.dispatch !== 'teammate') ?? runs[0]
     const others = runs.filter(run => run !== root)
-    this.scheduleLaunch(root, others)
+    this.scheduleLaunch(root, others, schedule)
     for (const run of others) {
-      if (run.dispatch !== 'teammate') this.scheduleLaunch(run)
+      if (run.dispatch !== 'teammate') this.scheduleLaunch(run, [], schedule)
     }
   }
 
-  private scheduleLaunch(opened: OpenedRun, others: readonly OpenedRun[] = []): void {
-    void this.launch(opened, others).catch(error => {
+  private scheduleLaunch(opened: OpenedRun, others: readonly OpenedRun[] = [], schedule?: ScheduledRunContext): void {
+    void this.launch(opened, others, schedule).catch(error => {
       safeConsoleError('[dsh-task-board] execution launch settlement failed', error)
     })
   }

package/src/protocol.ts

@@ -1,15 +1,18 @@
 import type { TaskUpdatePatch } from './core/use-cases/task-update.ts'
 import { isTaskPermission, isTaskStatus, isTaskTagList, type NewTaskInput, type TaskPermission, type TaskRecord, type TaskStatus } from './core/tasks.ts'
 import { parseLedger } from './core/store.ts'
+import { isValidTimeZone } from './core/schedule.ts'
 import { sanitizeFreezeSnapshot, type FreezeSnapshot } from './core/freeze-snapshot.ts'
 import { sanitizeHandover, type TaskHandoverInput } from './core/handover.ts'
 
 /** Freeze payload carried by create/update actions after the gate (redacted in place). */
 type FreezePayload = FreezeSnapshot & { redacted?: boolean; frozenBy?: string }
 
-export const TASK_BOARD_SCHEMA_VERSION = 3 as const
-/** Ledger documents written before v3; loaded once and migrated on startup. */
-export const TASK_BOARD_LEGACY_SCHEMA_VERSION = 2 as const
+export const TASK_BOARD_SCHEMA_VERSION = 4 as const
+/** Ledger documents written before v4; loaded once and migrated on startup. */
+export const TASK_BOARD_LEGACY_SCHEMA_VERSION = 3 as const
+/** Ledger documents written before v3; migrated through the v3 normalization too. */
+export const TASK_BOARD_OLDER_SCHEMA_VERSION = 2 as const
 export const TASK_BOARD_API_PREFIX = '/api/task-board'
 
 export type PowerPhase = 'disabled' | 'idle' | 'acquiring' | 'active' | 'error' | 'unsupported'
@@ -101,7 +104,8 @@ export type TaskBoardAction =
   | { kind: 'move'; taskId: string; status: TaskStatus }
   | { kind: 'archive'; taskId: string }
   | { kind: 'restore'; taskId: string }
-  | { kind: 'set-schedule'; taskId: string; patch: { enabled?: boolean; cron?: string } }
+  | { kind: 'settle'; taskId: string }
+  | { kind: 'set-schedule'; taskId: string; patch: { enabled?: boolean; cron?: string; timeZone?: string | null } }
   | { kind: 'run'; taskId: string }
   | { kind: 'rerun'; taskId: string }
   | { kind: 'confirm-permission'; taskId: string }
@@ -154,6 +158,8 @@ function validImportedKnownFields(value: Record<string, unknown>): boolean {
     const schedule = record(value.schedule)
     if (schedule === undefined || typeof schedule.enabled !== 'boolean' || typeof schedule.cron !== 'string') return false
     if (!optionalFiniteNumber(schedule.nextRunAt) || !optionalFiniteNumber(schedule.lastTriggeredAt)) return false
+    if (schedule.timeZone !== undefined
+      && (typeof schedule.timeZone !== 'string' || !isValidTimeZone(schedule.timeZone))) return false
   }
   if (value.executions !== undefined) {
     if (!Array.isArray(value.executions)) return false
@@ -199,6 +205,7 @@ function importedTask(value: unknown): TaskRecord | undefined {
       schedule: {
         enabled: task.schedule.enabled,
         cron: task.schedule.cron,
+        ...(task.schedule.timeZone === undefined ? {} : { timeZone: task.schedule.timeZone }),
         nextRunAt: task.schedule.nextRunAt,
         lastTriggeredAt: task.schedule.lastTriggeredAt,
       },
@@ -210,6 +217,7 @@ function importedTask(value: unknown): TaskRecord | undefined {
     ...(task.mode === undefined ? {} : { mode: task.mode }),
     ...(task.permission === undefined ? {} : { permission: task.permission }),
     ...(task.reuseSession === undefined ? {} : { reuseSession: task.reuseSession }),
+    ...(task.goalRun === undefined ? {} : { goalRun: task.goalRun }),
     ...(task.archivedAt === undefined ? {} : { archivedAt: task.archivedAt }),
     ...(task.freeze === undefined ? {} : { freeze: task.freeze }),
     ...(task.handover === undefined ? {} : { handover: task.handover }),
@@ -247,30 +255,36 @@ function handoverPayload(value: unknown): TaskHandoverInput | undefined {
 
 function createInput(value: unknown): value is NewTaskInput {
   const input = record(value)
-  if (input === undefined || !exactKeys(input, ['title', 'description', 'prompt', 'parentId', 'workspaceId', 'mode', 'permission', 'schedule', 'freeze', 'handover', 'model', 'reuseSession', 'teamRun', 'tags'])) return false
+  if (input === undefined || !exactKeys(input, ['title', 'description', 'prompt', 'parentId', 'workspaceId', 'mode', 'permission', 'schedule', 'freeze', 'handover', 'model', 'reuseSession', 'teamRun', 'goalRun', 'tags'])) return false
   if (input.parentId !== undefined && (typeof input.parentId !== 'string' || input.parentId.trim() === '')) return false
   if (typeof input.title !== 'string' || typeof input.description !== 'string' || typeof input.prompt !== 'string') return false
   if (!optionalString(input.workspaceId) || !optionalString(input.mode) || !optionalString(input.model)) return false
   if (input.reuseSession !== undefined && typeof input.reuseSession !== 'boolean') return false
   if (input.teamRun !== undefined && typeof input.teamRun !== 'boolean') return false
+  if (input.goalRun !== undefined && typeof input.goalRun !== 'boolean') return false
   if (input.permission !== undefined && !isTaskPermission(input.permission)) return false
   if (input.tags !== undefined && !isTaskTagList(input.tags)) return false
   if (input.freeze !== undefined && freezePayload(input.freeze) === undefined) return false
   if (input.handover !== undefined && handoverPayload(input.handover) === undefined) return false
   if (input.schedule !== undefined) {
     const schedule = record(input.schedule)
-    if (schedule === undefined || !exactKeys(schedule, ['enabled', 'cron'])) return false
+    if (schedule === undefined || !exactKeys(schedule, ['enabled', 'cron', 'timeZone'])) return false
     if (typeof schedule.enabled !== 'boolean' || typeof schedule.cron !== 'string') return false
+    if (schedule.timeZone !== undefined
+      && (typeof schedule.timeZone !== 'string' || !isValidTimeZone(schedule.timeZone))) return false
   }
   return true
 }
 
 function updatePatch(value: unknown): boolean {
   const patch = record(value)
-  if (patch === undefined || !exactKeys(patch, ['title', 'description', 'prompt', 'workspaceId', 'mode', 'permission', 'freeze', 'handover', 'model', 'reuseSession', 'teamRun', 'tags'])) return false
+  if (patch === undefined || !exactKeys(patch, ['title', 'description', 'prompt', 'workspaceId', 'mode', 'permission', 'freeze', 'handover', 'model', 'reuseSession', 'teamRun', 'goalRun', 'tags'])) return false
   // null (or false) clears the reuse opt-in; only a real boolean is accepted.
   if (patch.reuseSession !== undefined && patch.reuseSession !== null && typeof patch.reuseSession !== 'boolean') return false
   if (patch.teamRun !== undefined && patch.teamRun !== null && typeof patch.teamRun !== 'boolean') return false
+  // The goal opt-in is tri-state: null/true return the card to its default
+  // (goal run), false pins a single plain turn.
+  if (patch.goalRun !== undefined && patch.goalRun !== null && typeof patch.goalRun !== 'boolean') return false
   for (const key of ['title', 'description', 'prompt', 'workspaceId', 'mode', 'model'] as const) {
     if (!optionalString(patch[key])) return false
   }
@@ -286,9 +300,13 @@ function updatePatch(value: unknown): boolean {
 function schedulePatch(value: unknown): boolean {
   const patch = record(value)
   return patch !== undefined
-    && exactKeys(patch, ['enabled', 'cron'])
+    && exactKeys(patch, ['enabled', 'cron', 'timeZone'])
     && (patch.enabled === undefined || typeof patch.enabled === 'boolean')
     && (patch.cron === undefined || typeof patch.cron === 'string')
+    // `null` clears the stored zone back to the Host zone; an unknown name is
+    // rejected here so the Host never has to guess at an unusable zone.
+    && (patch.timeZone === undefined || patch.timeZone === null
+      || (typeof patch.timeZone === 'string' && isValidTimeZone(patch.timeZone)))
 }
 
 export function parseActionEnvelope(value: unknown): TaskBoardActionEnvelope | undefined {
@@ -364,6 +382,7 @@ function parseEnvelopeAction(value: unknown): TaskBoardActionEnvelope | undefine
     case 'delete':
     case 'archive':
     case 'restore':
+    case 'settle':
     case 'run':
     case 'rerun':
       if (!exactKeys(action, ['kind', 'taskId'])) return undefined

package/lib/types/host/run-guarded.d.ts

@@ -1,39 +0,0 @@
-/**
- * Async-boundary guard shared by the plugin family's Host halves: every
- * fire-and-forget promise chain and callback the host runtime does not own
- * (route handlers, timers, event listeners, spawned work) funnels through
- * these helpers. The dsh host installs a process-level fail-loud guard that
- * turns ANY unhandled promise rejection into a whole-process exit — one
- * plugin's stray rejection would otherwise take every plugin down. These
- * helpers exist so that failure mode is structurally impossible in family
- * code: the rejection becomes a logged error at the plugin boundary instead.
- *
- * Complements the aggregate's shell isolation (packages/dsh-web-all): the
- * shell contains import/activation failures at boot; runGuarded contains
- * run-time failures after activation.
- * @module dsh-web-shared/host/run-guarded
- */
-/**
- * Run one async operation, logging (never propagating) a rejection. Use for
- * promises whose lifecycle the caller does not await: spawned work, retry
- * loops, background flushes. Returns the original promise so callers can
- * still chain when they want to.
- * @param promise - the work to shield; any thenable.
- * @param label - log prefix naming the work site.
- * @param log - error sink; defaults to console.error.
- * @returns the input promise (rejection already consumed).
- */
-export declare function runGuarded<T>(promise: PromiseLike<T>, label: string, log?: (error: unknown) => void): PromiseLike<T>;
-/**
- * Wrap one callback so every invocation is individually guarded: a rejection
- * inside one call is logged and swallowed instead of escaping into whatever
- * infrastructure invoked the callback (HTTP server, EventEmitter, interval).
- * Sync throws are caught identically; a returned promise is replaced by
- * `undefined` after guarding (callers that need the original rejection should
- * await inside their own try/catch instead).
- * @param label - log prefix naming the callback site.
- * @param handler - the work to guard.
- * @param log - error sink; defaults to console.error.
- * @returns a wrapped callback with the same parameter list.
- */
-export declare function guardedHandler<A extends unknown[]>(label: string, handler: (...args: A) => unknown, log?: (error: unknown) => void): (...args: A) => unknown;