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

package/src/core/subtask.ts

@@ -36,6 +36,31 @@ export function isExecutionOutcome(value: unknown): value is ExecutionOutcome {
   return value === 'succeeded' || value === 'failed' || value === 'cancelled'
 }
 
+/**
+ * Reusable lineage index over ONE task list: the id lookup and the direct
+ * children per parent. A caller that runs several lineage queries over the same
+ * ledger (the link-subtask candidate gate runs one per task) builds this once
+ * instead of rescanning the list per query.
+ */
+export interface LineageIndex {
+  readonly byId: ReadonlyMap<string, TaskRecord>
+  readonly childrenByParent: ReadonlyMap<string, readonly TaskRecord[]>
+}
+
+/** Build the reusable index for a task list (ledger order preserved). */
+export function buildLineageIndex(tasks: readonly TaskRecord[]): LineageIndex {
+  const byId = new Map<string, TaskRecord>()
+  const childrenByParent = new Map<string, TaskRecord[]>()
+  for (const task of tasks) {
+    byId.set(task.id, task)
+    if (task.parentId === undefined) continue
+    const siblings = childrenByParent.get(task.parentId)
+    if (siblings === undefined) childrenByParent.set(task.parentId, [task])
+    else siblings.push(task)
+  }
+  return { byId, childrenByParent }
+}
+
 function indexOf(tasks: readonly TaskRecord[]): Map<string, TaskRecord> {
   return new Map(tasks.map(task => [task.id, task]))
 }
@@ -46,8 +71,8 @@ function indexOf(tasks: readonly TaskRecord[]): Map<string, TaskRecord> {
  * under a larger limit survives that limit being lowered, and restore and
  * inheritance must still see all of it.
  */
-export function ancestorChain(tasks: readonly TaskRecord[], task: TaskRecord): TaskRecord[] {
-  const index = indexOf(tasks)
+export function ancestorChain(tasks: readonly TaskRecord[], task: TaskRecord, lineage?: LineageIndex): TaskRecord[] {
+  const index = lineage?.byId ?? indexOf(tasks)
   const chain: TaskRecord[] = []
   const seen = new Set<string>([task.id])
   let current = task.parentId === undefined ? undefined : index.get(task.parentId)
@@ -61,13 +86,14 @@ export function ancestorChain(tasks: readonly TaskRecord[], task: TaskRecord): T
 }
 
 /** Root-to-task depth: a root task is 0, its subtask 1, and so on. */
-export function taskDepth(tasks: readonly TaskRecord[], id: string): number {
-  const task = indexOf(tasks).get(id)
-  return task === undefined ? 0 : ancestorChain(tasks, task).length
+export function taskDepth(tasks: readonly TaskRecord[], id: string, lineage?: LineageIndex): number {
+  const task = (lineage?.byId ?? indexOf(tasks)).get(id)
+  return task === undefined ? 0 : ancestorChain(tasks, task, lineage).length
 }
 
 /** Direct subtasks of a task, in ledger order. */
-export function directSubtasks(tasks: readonly TaskRecord[], id: string): TaskRecord[] {
+export function directSubtasks(tasks: readonly TaskRecord[], id: string, lineage?: LineageIndex): TaskRecord[] {
+  if (lineage !== undefined) return [...(lineage.childrenByParent.get(id) ?? [])]
   return tasks.filter(task => task.parentId === id)
 }
 
@@ -75,15 +101,18 @@ export function directSubtasks(tasks: readonly TaskRecord[], id: string): TaskRe
  * Descendants of a task in breadth-first order, bounded by maxSubtaskDepth
  * total depth. The visited set keeps a malformed ledger from looping.
  */
-export function descendantTasks(tasks: readonly TaskRecord[], id: string, maxSubtaskDepth: number): TaskRecord[] {
+export function descendantTasks(tasks: readonly TaskRecord[], id: string, maxSubtaskDepth: number, lineage?: LineageIndex): TaskRecord[] {
   const visited = new Set<string>([id])
   const found: TaskRecord[] = []
   let frontier = [id]
   for (let depth = 1; depth <= maxSubtaskDepth && frontier.length > 0; depth += 1) {
     const next: string[] = []
     for (const parentId of frontier) {
-      for (const task of tasks) {
-        if (task.parentId !== parentId || visited.has(task.id)) continue
+      const children = lineage === undefined
+        ? tasks.filter(task => task.parentId === parentId)
+        : lineage.childrenByParent.get(parentId) ?? []
+      for (const task of children) {
+        if (visited.has(task.id)) continue
         visited.add(task.id)
         found.push(task)
         next.push(task.id)
@@ -99,13 +128,13 @@ export function descendantTasks(tasks: readonly TaskRecord[], id: string, maxSub
  * The visited set makes the walk terminate on a cyclic hand-edited ledger
  * instead of recursing until the stack overflows.
  */
-export function subtreeHeight(tasks: readonly TaskRecord[], id: string, visited: ReadonlySet<string> = new Set<string>()): number {
+export function subtreeHeight(tasks: readonly TaskRecord[], id: string, visited: ReadonlySet<string> = new Set<string>(), lineage?: LineageIndex): number {
   if (visited.has(id)) return 0
   const seen = new Set([...visited, id])
-  const children = directSubtasks(tasks, id)
+  const children = directSubtasks(tasks, id, lineage)
   if (children.length === 0) return 0
   let height = 0
-  for (const child of children) height = Math.max(height, 1 + subtreeHeight(tasks, child.id, seen))
+  for (const child of children) height = Math.max(height, 1 + subtreeHeight(tasks, child.id, seen, lineage))
   return Math.min(height, SUBTASK_DEPTH_MAX)
 }
 
@@ -137,16 +166,17 @@ export function checkParentLink(
   childId: string,
   parentId: string | null,
   maxSubtaskDepth: number,
+  lineage?: LineageIndex,
 ): ParentLinkCheck {
-  const child = tasks.find(task => task.id === childId)
+  const child = lineage === undefined ? tasks.find(task => task.id === childId) : lineage.byId.get(childId)
   if (child === undefined) return { ok: false, reason: 'unknown-task' }
   if (parentId === null || parentId === '') return { ok: true }
   if (parentId === childId) return { ok: false, reason: 'self-parent' }
-  const parent = tasks.find(task => task.id === parentId)
+  const parent = lineage === undefined ? tasks.find(task => task.id === parentId) : lineage.byId.get(parentId)
   if (parent === undefined) return { ok: false, reason: 'unknown-parent' }
   if (parent.archivedAt !== undefined) return { ok: false, reason: 'archived-parent' }
-  if (descendantTasks(tasks, childId, SUBTASK_DEPTH_MAX).some(task => task.id === parentId)) return { ok: false, reason: 'cycle' }
-  const depth = taskDepth(tasks, parentId) + 1 + subtreeHeight(tasks, childId)
+  if (descendantTasks(tasks, childId, SUBTASK_DEPTH_MAX, lineage).some(task => task.id === parentId)) return { ok: false, reason: 'cycle' }
+  const depth = taskDepth(tasks, parentId, lineage) + 1 + subtreeHeight(tasks, childId, new Set<string>(), lineage)
   if (depth > maxSubtaskDepth) return { ok: false, reason: 'depth-exceeded' }
   return { ok: true }
 }
@@ -241,18 +271,43 @@ export function effectiveTaskPermission(task: TaskRecord): TaskRecord['permissio
  */
 /**
  * The immutable teammate name for one team-mode member. Teammate names are
- * lower-kebab-case and must stay unique for the lifetime of the Team, so the
- * run-group token is appended: two runs of the same tree never collide. A title
- * with no ASCII word characters (a CJK title, for example) keeps a stable
- * generic prefix and is still distinguished by the token.
+ * lower-kebab-case and must stay unique for the lifetime of the Team: the
+ * run-group token separates two runs of the same tree, and the member
+ * discriminator separates two members of one run that reduce to the same slug.
+ *
+ * The discriminator is not cosmetic. A title with no ASCII word characters (a
+ * CJK title, for example) carries no slug at all, so every such title of one
+ * run group collides on the generic prefix; Agent Teams answers every member
+ * after the first with `teammate name "..." was already used in this Team`,
+ * and those subtasks never start. Two ASCII titles that share a slug
+ * (`AI 强度预测` next to `AI 配比优化`) collide the same way.
  * @param title - the member task's title.
  * @param token - the run group id (the task id when no group is recorded).
+ * @param memberId - the member task's id, which makes the name unique in the run.
  * @returns the teammate name handed to the Agent Teams service.
  */
-export function teammateName(title: string, token: string): string {
+export function teammateName(title: string, token: string, memberId?: string): string {
   const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 32).replace(/-+$/g, '')
   const suffix = token.replace(/[^a-z0-9]/gi, '').slice(0, 8).toLowerCase()
-  return `${slug === '' ? 'subtask' : slug}-${suffix === '' ? 'run' : suffix}`
+  const member = memberId === undefined || memberId === '' ? undefined : stableTag(memberId)
+  return [slug === '' ? 'subtask' : slug, member, suffix === '' ? 'run' : suffix]
+    .filter((part): part is string => part !== undefined)
+    .join('-')
+}
+
+/**
+ * A stable 4-hex tag for one member id. The name is derived twice for the same
+ * member — once for the Lead's prompt and once for the spawn request — so the
+ * tag must be a pure function of the id, never of a clock or a counter. FNV-1a
+ * keeps it dependency-free in `core/`, which both halves compile.
+ */
+function stableTag(value: string): string {
+  let hash = 0x811c9dc5
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index)
+    hash = Math.imul(hash, 0x01000193) >>> 0
+  }
+  return hash.toString(16).padStart(8, '0').slice(0, 4)
 }
 
 export function resolveExecutionTargets(

package/src/core/tasks.ts

@@ -87,6 +87,13 @@ export interface ScheduleRule {
   enabled: boolean
   /** 5-field cron expression: `分 时 日 月 周`. */
   cron: string
+  /**
+   * IANA zone the cron wall clock is read in (issue #1722). Absent means the
+   * Host process zone, which is what a rule written before zones were
+   * persisted keeps using; the Host stamps its own zone at ledger migration so
+   * a later `TZ` change cannot silently move an existing rule.
+   */
+  timeZone?: string
   /** Next due instant (ms epoch); maintained by the scheduler/controller. */
   nextRunAt: number | undefined
   /** Instant of the latest scheduled trigger (ms epoch). */
@@ -278,6 +285,16 @@ export interface TaskRecord {
    * and a subtask's own permission pin cannot be honored in this mode.
    */
   teamRun?: boolean
+  /**
+   * Start every execution of this task with dsh's built-in `/goal` command,
+   * armed with the composed execution prompt as its objective. The session then
+   * keeps working automatic continuation rounds until the agent marks the goal
+   * complete, and this board settles the execution on the goal's own end
+   * instead of at the first turn end. Absent means ON — the option is checked
+   * by default, so only an explicit `false` runs the task as a single plain
+   * turn. A session whose `/goal` command is refused still runs the prompt.
+   */
+  goalRun?: boolean
   /**
    * Frozen context snapshot for a continuation card; absent on plain tasks.
    * Sanitized before it enters the ledger (redaction, slash-command taint,
@@ -354,12 +371,18 @@ export interface NewTaskInput {
   reuseSession?: boolean
   /** Run the subtree as an Agent Team (Team Lead session plus one teammate per direct subtask). */
   teamRun?: boolean
+  /**
+   * Start the execution with dsh's built-in `/goal`. Absent/true keeps the
+   * default (goal run); an explicit false requests a single plain turn.
+   */
+  goalRun?: boolean
   /**
    * Optional scheduled-run rule requested at creation time (the new-task
-   * dialog): an enable flag plus a 5-field cron expression. The create use
-   * case arms it only when enabled and the expression is valid.
+   * dialog): an enable flag, a 5-field cron expression, and the IANA zone its
+   * wall clock is read in (absent means the Host zone). The create use case
+   * arms it only when enabled and the expression is valid.
    */
-  schedule?: { enabled: boolean; cron: string }
+  schedule?: { enabled: boolean; cron: string; timeZone?: string }
   /**
    * Optional frozen context snapshot (goal/progress/next, sanitized by the
    * protocol gate) turning the new task into a continuation card.
@@ -449,7 +472,11 @@ export function createTask(input: NewTaskInput, now: number, id: string): TaskRe
     permission: isTaskPermission(input.permission) ? input.permission : undefined,
     model: normalizeTargetId(input.model),
     reuseSession: input.reuseSession === true ? true : undefined,
-  teamRun: input.teamRun === true ? true : undefined,
+    teamRun: input.teamRun === true ? true : undefined,
+    // Default ON: only an explicit false is stored, so a card that never
+    // touched the option (and every card written before the field existed)
+    // keeps starting its runs with /goal.
+    goalRun: input.goalRun === false ? false : undefined,
     ...(input.freeze === undefined ? {} : { freeze: freezeOf(input.freeze, now) }),
     ...(input.handover === undefined ? {} : { handover: { ...input.handover, bundledAt: now } }),
     ...(tags === undefined ? {} : { tags }),
@@ -476,11 +503,18 @@ export function withSchedule(
   const schedule: ScheduleRule = {
     enabled: current?.enabled ?? false,
     cron: current?.cron ?? '',
+    ...(current?.timeZone === undefined ? {} : { timeZone: current.timeZone }),
     nextRunAt: current?.nextRunAt,
     lastTriggeredAt: current?.lastTriggeredAt,
   }
   if ('enabled' in patch) schedule.enabled = patch.enabled ?? false
   if ('cron' in patch) schedule.cron = patch.cron ?? ''
+  // An explicit `undefined` drops the stored zone (back to the Host zone);
+  // an absent key keeps it.
+  if ('timeZone' in patch) {
+    if (patch.timeZone === undefined) delete schedule.timeZone
+    else schedule.timeZone = patch.timeZone
+  }
   if ('nextRunAt' in patch) schedule.nextRunAt = patch.nextRunAt
   if ('lastTriggeredAt' in patch) schedule.lastTriggeredAt = patch.lastTriggeredAt
   return { ...task, updatedAt: now, schedule }

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