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

package/src/core/workspace-target.ts

@@ -0,0 +1,59 @@
+/**
+ * Workspace targeting for cards that pin none.
+ *
+ * The Host answers two questions here instead of leaving them to
+ * `session.create`, whose own fallback is the Host process working directory
+ * (the desktop app's profile directory): which workspace a root card inherits
+ * from the session that created it, and which workspace an unpinned run lands
+ * in when nothing could be inherited.
+ *
+ * Structural types only — the Host's `Workspace` entity satisfies them — so the
+ * browser program compiles this module without importing an SDK value.
+ *
+ * @module dsh-task-board/core/workspace-target
+ */
+
+/** The workspace facts these rules read (a `Workspace` entity subset). */
+export interface WorkspaceCandidate {
+  /** Stable workspace record id. */
+  readonly id: string
+  /** ISO-8601 instant of the workspace's last durable mutation. */
+  readonly updatedAt: string
+  /** Header-validated session ids the workspace owns, most recent first. */
+  readonly sessionIds: readonly string[]
+}
+
+/**
+ * The workspace that owns one session.
+ * @param items - the deployment's workspaces.
+ * @param sessionId - the session whose workspace is requested.
+ * @returns the owning workspace id, or undefined when none claims the session.
+ */
+export function workspaceOwningSession(
+  items: readonly WorkspaceCandidate[],
+  sessionId: string,
+): string | undefined {
+  return items.find(item => item.sessionIds.includes(sessionId))?.id
+}
+
+/**
+ * The workspace the board treats as most recently used: the one whose record
+ * changed last. Attaching a session stamps that instant, so the newest stamp
+ * tracks where the user most recently opened or resumed a session. The
+ * deployment's own list order breaks ties, and a stamp that does not parse
+ * never outranks one that does; a registry whose stamps are all unreadable
+ * falls back to list order rather than to "no workspace at all".
+ * @param items - the deployment's workspaces.
+ * @returns the most recently used workspace id, or undefined when there is none.
+ */
+export function mostRecentWorkspaceId(items: readonly WorkspaceCandidate[]): string | undefined {
+  let best: WorkspaceCandidate | undefined
+  let bestAt = Number.NEGATIVE_INFINITY
+  for (const item of items) {
+    const at = Date.parse(item.updatedAt)
+    if (!Number.isFinite(at) || at <= bestAt) continue
+    best = item
+    bestAt = at
+  }
+  return best?.id ?? items[0]?.id
+}

package/src/host/agent-tools.ts

@@ -23,11 +23,13 @@ import {
   TASK_PERMISSIONS,
   type ExecutionRecord,
   type NewTaskInput,
+  type ScheduleMode,
   type ScheduleRule,
   type TaskPermission,
   type TaskRecord,
   type TaskTag,
 } from '../core/tasks.ts'
+import type { SetSchedulePatch } from '../core/use-cases/task-schedule.ts'
 import type { TaskUpdatePatch } from '../core/use-cases/task-update.ts'
 import type { TaskBoardAction, TaskBoardSnapshot } from '../protocol.ts'
 
@@ -39,7 +41,7 @@ export interface TaskBoardToolHost {
   /** Current board snapshot (tasks + scheduler + power + deployment constants). */
   snapshot(): TaskBoardSnapshot
   /** Submit one confirmed Host action; returns the resulting snapshot. */
-  apply(requestId: string, action: TaskBoardAction, initiator?: string): TaskBoardSnapshot
+  apply(requestId: string, action: TaskBoardAction, initiator?: string): TaskBoardSnapshot | Promise<TaskBoardSnapshot>
 }
 
 /** Registered tool names, in registration order. */
@@ -93,11 +95,22 @@ export function callingSessionId(exec: { agent?: unknown }): string | undefined
 function scheduleView(schedule: ScheduleRule): Record<string, unknown> {
   return {
     enabled: schedule.enabled,
-    cron: schedule.cron,
+    mode: schedule.mode,
+    // A one-shot has no cron, and carries its planned instant instead.
+    ...(schedule.cron === undefined ? {} : { cron: schedule.cron }),
+    ...(schedule.at === undefined ? {} : { at: schedule.at }),
     // 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 }),
+    // The run budget: what the scheduler has already opened, its cap (absent =
+    // unlimited), and how the rule stopped or what it last skipped.
+    runCount: schedule.runCount,
+    ...(schedule.maxRuns === undefined ? {} : { maxRuns: schedule.maxRuns }),
+    ...(schedule.endedAt === undefined ? {} : { endedAt: schedule.endedAt }),
+    ...(schedule.endedReason === undefined ? {} : { endedReason: schedule.endedReason }),
+    ...(schedule.skippedAt === undefined ? {} : { skippedAt: schedule.skippedAt }),
+    ...(schedule.skippedReason === undefined ? {} : { skippedReason: schedule.skippedReason }),
   }
 }
 
@@ -114,8 +127,11 @@ function executionView(execution: ExecutionRecord): Record<string, unknown> {
     ...(execution.result === undefined ? {} : { result: execution.result }),
     ...(execution.error === undefined ? {} : { error: execution.error }),
     // The session that asked for the run (audit only; client-asserted by the
-    // browser, the calling session here).
+    // browser, the calling session here). On an external record it names the
+    // outside agent instead, which is what distinguishes it in the history.
     ...(execution.initiatedBy === undefined ? {} : { initiatedBy: execution.initiatedBy }),
+    // Set only by record-external-outcome: the Host observed no session for it.
+    ...(execution.external === true ? { external: true } : {}),
     ...(execution.runGroupId === undefined ? {} : { cascade: true }),
     // A deferred cascade parent has settled its own turn but still waits for
     // its subtasks; that is not a stuck card and the model must not retry it.
@@ -152,8 +168,10 @@ 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 } : {}),
+    // Default-OFF opt-in: only a card that asked for the goal run reports it.
+    ...(task.goalRun === true ? { goalRun: true } : {}),
+    // Default-OFF opt-out: the deviation is what a reader must be told.
+    ...(task.skipVerification === true ? { skipVerification: true } : {}),
     ...(task.schedule === undefined ? {} : { schedule: scheduleView(task.schedule) }),
     ...(task.freeze === undefined ? {} : { continuationCard: true }),
     ...(task.permissionConfirmedAt === undefined ? {} : { permissionConfirmedAt: task.permissionConfirmedAt }),
@@ -260,7 +278,6 @@ function buildSetParentTool(host: TaskBoardToolHost): ToolDefinition {
       'Pass an empty parentId to detach.',
       'The Host refuses the link when the parent is unknown or archived, when the moved task is one of its own descendants, when the resulting depth exceeds the deployment subtask limit (default one level, maximum three), or while the task has an unsettled execution (its link may still be a running cascade parent pointer).',
       'Running a task runs its whole subtree concurrently; a parent card settles only after its own turn and every direct subtask settle.',
-      'Triggers: 任务看板, task board, 看板, 子任务, subtask, 关联任务, link task, 解除关联, detach.',
     ].join(' '),
     parameters: {
       taskId: { type: 'string', required: true, description: 'The task whose parent link changes.' },
@@ -269,7 +286,7 @@ function buildSetParentTool(host: TaskBoardToolHost): ToolDefinition {
     output: { schema: { type: 'json' }, render: renderJson },
     async execute(args, exec) {
       try {
-        const snapshot = host.apply(
+        const snapshot = await host.apply(
           crypto.randomUUID(),
           { kind: 'set-parent', taskId: args.taskId, parentId: args.parentId === '' ? null : args.parentId },
           callingSessionId(exec),
@@ -294,7 +311,6 @@ function buildRunTool(host: TaskBoardToolHost): ToolDefinition {
       'A card whose effective permission is above the deployment session default is refused with confirmation-required until a HUMAN confirms the binding in the board UI; this tool cannot confirm it.',
       'A card whose task carries teamRun instead starts ONE Team Lead session and the Host spawns a teammate per subtask inside it, so those cards run as an Agent Team rather than as independent sessions; that mode needs the deployment Agent Teams service and is refused when it is missing.',
       'Executions consume real API quota. Sessions are created asynchronously, so read their ids and outcomes back with task_board_get.',
-      'Triggers: 任务看板, task board, 看板, 执行任务, run task, 重新执行, rerun, 子任务, subtask.',
     ].join(' '),
     parameters: {
       taskId: { type: 'string', required: true, description: 'The task to run; running a root task runs its whole subtree.' },
@@ -304,7 +320,7 @@ function buildRunTool(host: TaskBoardToolHost): ToolDefinition {
     async execute(args, exec) {
       const before = host.snapshot()
       try {
-        const snapshot = host.apply(
+        const snapshot = await host.apply(
           crypto.randomUUID(),
           { kind: args.rerun === true ? 'rerun' : 'run', taskId: args.taskId },
           callingSessionId(exec),
@@ -339,29 +355,81 @@ function buildManageTool(host: TaskBoardToolHost): ToolDefinition {
     name: 'task_board_manage',
     description: [
       '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.',
+      'move-backlog, move-todo, move-running, move-done and move-failed are the manual column moves and cover every column; a card the runner is executing (one with an open execution) cannot be moved.',
+      'A manual move writes the card column only and never fabricates an execution record, so the card reports a declaration rather than evidence of a run: done/failed declare work finished (or failed) outside a Host-run execution — human work, an external system, a decision made elsewhere — and running says the work is under way without a tracked session. Use task_board_run when the work should actually run in a session here.',
+      'record-external-outcome is the record-backed version of move-done and move-failed: use it when YOU, or another agent outside this Host, actually finished or failed the card with your own model, so the terminal column and the run history both derive from one execution record. It takes result (succeeded or failed) and initiatedBy (who completed it, for example your own agent name) plus an optional summary, and it is refused while the card still has an open execution: the Host stays the only authority over a run it is executing. It cannot record running or cancelled — those remain Host-only.',
       '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.',
+      'reset-verification clears the acceptance anomalies (timeouts, authentication failures, an unresolvable judge route, or an attempt the time budget ended) recorded on a card open execution, so the next update_goal(action: complete) runs a fresh acceptance. It is refused unless that execution really carries such anomalies, it never clears a quality verdict, and a spent anomaly budget otherwise HOLDS the card open instead of failing it: tell the user the acceptance environment is unusable and that this action is how they clear it once they have fixed it.',
       '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, 卡住, 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', 'settle'],
+        enum: ['move-todo', 'move-backlog', 'move-running', 'move-done', 'move-failed', 'archive', 'restore', 'delete', 'settle', 'reset-verification', 'record-external-outcome'],
         description: 'The lifecycle operation to perform.',
       },
+      // Only record-external-outcome reads these two; every other action
+      // ignores them, so the model can pass them without a second tool call.
+      result: {
+        type: 'string',
+        enum: ['succeeded', 'failed'],
+        description: 'record-external-outcome only: the verdict the outside agent actually reached.',
+      },
+      initiatedBy: {
+        type: 'string',
+        description: 'record-external-outcome only: who finished the work outside this Host (for example your own agent name).',
+      },
+      summary: {
+        type: 'string',
+        description: 'record-external-outcome only: optional free-text note stored with the recorded outcome.',
+      },
     },
     output: { schema: { type: 'json' }, render: renderJson },
     async execute(args, exec) {
       const initiator = callingSessionId(exec)
+      if (args.action === 'record-external-outcome') {
+        const result = args.result
+        const by = typeof args.initiatedBy === 'string' ? args.initiatedBy.trim() : ''
+        if (result !== 'succeeded' && result !== 'failed') {
+          return refused('missing-result', 'record-external-outcome needs result=succeeded or result=failed')
+        }
+        if (by === '') {
+          return refused('missing-initiator', 'record-external-outcome needs initiatedBy naming who completed the work outside this Host')
+        }
+        if (!host.snapshot().tasks.some(task => task.id === args.taskId)) {
+          return refused('task-not-found', 'no task with id ' + args.taskId)
+        }
+        try {
+          const snapshot = await host.apply(crypto.randomUUID(), {
+            kind: 'record-external-outcome',
+            taskId: args.taskId,
+            result,
+            initiatedBy: by,
+            ...(typeof args.summary === 'string' && args.summary.trim() !== '' ? { summary: args.summary } : {}),
+          }, initiator)
+          const task = snapshot.tasks.find(item => item.id === args.taskId)
+          return json({
+            ok: true,
+            action: args.action,
+            ...(task === undefined ? {} : { task: taskSummary(task, snapshot.tasks, snapshot.sessionDefaultPermission) }),
+            note: 'The outcome is recorded as its own execution, so the terminal column and the run history agree. Read it back with task_board_get.',
+          })
+        } catch (error) {
+          return refused('refused', messageOf(error))
+        }
+      }
       const actions: Record<string, TaskBoardAction> = {
         'move-todo': { kind: 'move', taskId: args.taskId, status: 'todo' },
         'move-backlog': { kind: 'move', taskId: args.taskId, status: 'backlog' },
+        'move-running': { kind: 'move', taskId: args.taskId, status: 'running' },
+        'move-done': { kind: 'move', taskId: args.taskId, status: 'done' },
+        'move-failed': { kind: 'move', taskId: args.taskId, status: 'failed' },
         archive: { kind: 'archive', taskId: args.taskId },
         settle: { kind: 'settle', taskId: args.taskId },
+        'reset-verification': { kind: 'reset-verification', taskId: args.taskId },
         restore: { kind: 'restore', taskId: args.taskId },
         delete: { kind: 'delete', taskId: args.taskId },
       }
@@ -371,7 +439,7 @@ function buildManageTool(host: TaskBoardToolHost): ToolDefinition {
         return refused('task-not-found', 'no task with id ' + args.taskId)
       }
       try {
-        const snapshot = host.apply(crypto.randomUUID(), action, initiator)
+        const snapshot = await host.apply(crypto.randomUUID(), action, initiator)
         if (args.action === 'delete') return json({ ok: true, action: args.action, taskId: args.taskId })
         const task = snapshot.tasks.find(item => item.id === args.taskId)
         if (task === undefined) return refused('task-not-found', 'no task with id ' + args.taskId)
@@ -387,41 +455,49 @@ function buildScheduleTool(host: TaskBoardToolHost): ToolDefinition {
   return defineTool({
     name: 'task_board_schedule',
     description: [
-      '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.',
+      'Arm, change, or disarm a task scheduled runs. Two kinds of plan exist: a recurring 5-field cron rule (day-of-month and day-of-week follow Vixie semantics: both restricted means OR, otherwise AND), and a one-shot that runs once at a future instant.',
+      'For a one-shot pass mode "once" with at (the planned instant, ms since epoch UTC). For a recurring rule pass mode "cron" (or omit mode) with a cron expression, optionally capped by maxRuns (a positive whole number of scheduled executions; omit for unlimited, pass 0 to clear a cap).',
+      'The 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.',
-      'Triggers: 任务看板, task board, 看板, 定时任务, schedule, cron, 每天执行.',
+      'The scheduler counts executions it actually starts; once a rule reaches its run budget it stops itself in the ledger, and a manual run never consumes the budget. A schedule whose tree contains an unconfirmed above-default permission is refused and does not consume the budget; the reason is reported in the list board summary as schedulerError.',
+      'Missed occurrences during Host downtime are skipped, never queued (a one-shot whose instant passed while the Host was down is stopped as missed); a task that is already running skips its occurrence without consuming the budget.',
     ].join(' '),
     parameters: {
       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.' },
+      mode: { type: 'string', enum: ['cron', 'once'], description: 'The kind of plan: "cron" for a recurring rule, "once" for a single future instant. Omit to keep the stored kind.' },
+      cron: { type: 'string', description: '5-field cron expression of a recurring rule: minute hour day-of-month month day-of-week.' },
+      at: { type: 'integer', description: 'Planned instant of a one-shot, in milliseconds since the Unix epoch (UTC). Must be in the future.' },
       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.',
+        description: 'IANA zone the 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.',
       },
+      maxRuns: { type: 'integer', description: 'Maximum scheduled executions of a recurring rule (positive whole number). Omit to keep the stored cap; pass 0 to clear it back to unlimited.' },
     },
     output: { schema: { type: 'json' }, render: renderJson },
     async execute(args, exec) {
-      if (args.enabled === undefined && args.cron === undefined && args.timeZone === undefined) {
-        return refused('nothing-to-change', 'pass enabled and/or cron and/or timeZone')
+      if (args.enabled === undefined && args.mode === undefined && args.cron === undefined && args.at === undefined
+        && args.timeZone === undefined && args.maxRuns === undefined) {
+        return refused('nothing-to-change', 'pass enabled, mode, cron, at, timeZone and/or maxRuns')
       }
       // 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; timeZone?: string | null } = {
+      const patch: SetSchedulePatch = {
         ...(args.enabled === undefined ? {} : { enabled: args.enabled }),
+        ...(args.mode === undefined ? {} : { mode: args.mode as ScheduleMode }),
         ...(args.cron === undefined ? {} : { cron: args.cron }),
+        ...(args.at === undefined ? {} : { at: args.at }),
         // 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 }),
+        // 0 is the documented way to clear a run cap back to unlimited.
+        ...(args.maxRuns === undefined ? {} : { maxRuns: args.maxRuns <= 0 ? null : args.maxRuns }),
       }
       try {
-        const snapshot = host.apply(crypto.randomUUID(), { kind: 'set-schedule', taskId: args.taskId, patch }, callingSessionId(exec))
+        const snapshot = await host.apply(crypto.randomUUID(), { kind: 'set-schedule', taskId: args.taskId, patch }, callingSessionId(exec))
         const task = snapshot.tasks.find(item => item.id === args.taskId)
         if (task === undefined) return refused('task-not-found', 'no task with id ' + args.taskId)
         return json({
@@ -445,7 +521,6 @@ function buildListTool(host: TaskBoardToolHost): ToolDefinition {
       'Filters: status column, parentId (direct subtasks), rootsOnly, tag, free-text query, and archived inclusion.',
       'Returns each task id, title, column, parent/subtask link, execution targets, schedule and latest run outcome, plus the board summary (revision, time zone, subtask depth limit, session-default permission).',
       'Use task_board_get for one task in full, task_board_create to add work, and task_board_run to execute it.',
-      'Triggers: 任务看板, task board, 看板, 子任务, subtask, task list, 定时任务, scheduled task.',
     ].join(' '),
     parameters: {
       status: { type: 'string', enum: ['backlog', 'todo', 'running', 'done', 'failed'], description: 'Only cards in this column.' },
@@ -491,7 +566,6 @@ function buildGetTool(host: TaskBoardToolHost): ToolDefinition {
     description: [
       'Read one task board card in full: prompt, description, labels, column, parent link, direct subtasks, execution targets, schedule, permission gate state, and the last ten execution attempts with their session ids and outcomes.',
       'Use it before running or editing a card, and after a run to read the settled outcome.',
-      'Triggers: 任务看板, task board, 看板, 子任务, subtask, task detail.',
     ].join(' '),
     parameters: {
       taskId: { type: 'string', required: true, description: 'Task id, as reported by task_board_list or task_board_create.' },
@@ -515,20 +589,20 @@ function buildCreateTool(host: TaskBoardToolHost): ToolDefinition {
       'A subtask inherits every execution target it does not override (workspace, agent preset, permission, model) from its parent, and inherits the parent human permission confirmation together with an inherited binding.',
       'The deployment caps subtask depth (default one level, maximum three): a subtask of a subtask is refused unless the board is configured deeper.',
       'The task lands in the todo column and does NOT run; call task_board_run to execute it.',
-      'Triggers: 任务看板, task board, 看板, 新建任务, create task, 子任务, subtask, 定时任务.',
     ].join(' '),
     parameters: {
       title: { type: 'string', required: true, description: 'Short display title (one line).' },
       description: { type: 'string', description: 'Longer human description shown in the detail view.' },
       prompt: { type: 'string', description: 'The instruction sent to the execution agent; the title is used when blank.' },
       parentId: { type: 'string', description: 'Parent task id, making this a subtask. Omit for a root task.' },
-      workspaceId: { type: 'string', description: 'Workspace id the execution must run in; omit to inherit the parent value or use the most recent workspace.' },
+      workspaceId: { type: 'string', description: 'Workspace id the execution must run in; omit to inherit the workspace this session is in (root task) or the parent value (subtask).' },
       mode: { type: 'string', description: 'Agent preset id the execution session is composed from; omit for the deployment default or the parent value.' },
       permission: { type: 'string', enum: [...TASK_PERMISSIONS], description: 'Permission preset for the execution session. Omit to inherit the parent binding; a value above the session default needs a human confirmation in the board UI before the card can run.' },
       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.' },
+      goalRun: { type: 'boolean', description: 'Start each run with dsh built-in /goal so the session keeps working continuation rounds until the goal completes. Off by default: omit (or pass false) for a single plain turn, and pass true to opt this card in. It only takes effect while the deployment global native /goal switch is on.' },
+      skipVerification: { type: 'boolean', description: 'Run this task without the board acceptance gate: update_goal may mark the goal complete without a passing acceptance, and the execution record is marked skipped. Default false (omit to inherit the board-wide acceptance switch). Only affects executions started afterwards.' },
       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.',
@@ -544,10 +618,13 @@ function buildCreateTool(host: TaskBoardToolHost): ToolDefinition {
       schedule: {
         type: 'object',
         additionalProperties: false,
-        description: 'Arm a 5-field cron schedule at creation time (Host local time zone).',
+        description: 'Arm a schedule at creation time. Use mode "once" with at for a single future run, or mode "cron" (or omit mode) with a 5-field cron expression, optionally capped by maxRuns.',
         properties: {
           enabled: { type: 'boolean', required: true, description: 'Whether the schedule is armed.' },
-          cron: { type: 'string', required: true, description: '5-field cron: minute hour day-of-month month day-of-week.' },
+          mode: { type: 'string', enum: ['cron', 'once'], description: 'The kind of plan: "cron" for a recurring rule, "once" for a single future instant.' },
+          cron: { type: 'string', description: '5-field cron of a recurring rule: minute hour day-of-month month day-of-week.' },
+          at: { type: 'integer', description: 'Planned instant of a one-shot, in milliseconds since the Unix epoch (UTC). Must be in the future.' },
+          maxRuns: { type: 'integer', description: 'Maximum scheduled executions of a recurring rule (positive whole number); omit for unlimited.' },
         },
       },
     },
@@ -570,12 +647,21 @@ 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 } : {}),
+        ...(args.goalRun === true ? { goalRun: true } : {}),
+    ...(args.skipVerification === true ? { skipVerification: true } : {}),
         ...(tags.length === 0 ? {} : { tags }),
-        ...(args.schedule === undefined ? {} : { schedule: { enabled: args.schedule.enabled, cron: args.schedule.cron } }),
+        ...(args.schedule === undefined ? {} : {
+          schedule: {
+            enabled: args.schedule.enabled,
+            ...(args.schedule.mode === undefined ? {} : { mode: args.schedule.mode as ScheduleMode }),
+            ...(args.schedule.cron === undefined ? {} : { cron: args.schedule.cron }),
+            ...(args.schedule.at === undefined ? {} : { at: args.schedule.at }),
+            ...(args.schedule.maxRuns === undefined ? {} : { maxRuns: args.schedule.maxRuns }),
+          },
+        }),
       }
       try {
-        const snapshot = host.apply(crypto.randomUUID(), { kind: 'create', id, input }, callingSessionId(exec))
+        const snapshot = await host.apply(crypto.randomUUID(), { kind: 'create', id, input }, callingSessionId(exec))
         const task = snapshot.tasks.find(item => item.id === id)
         if (task === undefined) return refused('create-failed', 'the Host did not confirm the new task')
         return json({ ok: true, task: taskDetail(task, snapshot.tasks, snapshot.sessionDefaultPermission) })
@@ -594,7 +680,6 @@ function buildUpdateTool(host: TaskBoardToolHost): ToolDefinition {
       'Only the fields you pass change; pass an empty string to clear a target, or an empty labels array to clear the labels.',
       'Title, description and prompt freeze once the task has started executing; the execution targets stay editable because they only affect future runs.',
       'Changing the pinned permission re-arms the permission confirmation gate.',
-      'Triggers: 任务看板, task board, 看板, 修改任务, edit task, 子任务, 标签, tags.',
     ].join(' '),
     parameters: {
       taskId: { type: 'string', required: true, description: 'Task id to edit.' },
@@ -621,7 +706,8 @@ function buildUpdateTool(host: TaskBoardToolHost): ToolDefinition {
       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.' },
+      goalRun: { type: 'boolean', description: 'Whether each run starts with dsh built-in /goal (default false, one plain turn). Pass true to opt this card in, or false to return it to the default.' },
+      skipVerification: { type: 'boolean', description: 'Whether this task runs without the board acceptance gate (default false, inherit the board-wide switch). Pass true to opt out; pass false to opt back in. Only affects executions started afterwards.' },
       tags: {
         type: 'array',
         description: 'Replacement label set; an empty array clears all labels.',
@@ -650,7 +736,8 @@ 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, 'goalRun')) patch.goalRun = args.goalRun === true ? true : false
+      if (has(args, 'skipVerification')) patch.skipVerification = args.skipVerification === true ? true : false
       if (has(args, 'tags')) {
         const tags = args.tags ?? []
         patch.tags = tags.length === 0
@@ -662,7 +749,7 @@ function buildUpdateTool(host: TaskBoardToolHost): ToolDefinition {
       }
       if (Object.keys(patch).length === 0) return refused('nothing-to-change', 'pass at least one field to update')
       try {
-        const snapshot = host.apply(crypto.randomUUID(), { kind: 'update', taskId: args.taskId, patch }, callingSessionId(exec))
+        const snapshot = await host.apply(crypto.randomUUID(), { kind: 'update', taskId: args.taskId, patch }, callingSessionId(exec))
         const task = snapshot.tasks.find(item => item.id === args.taskId)
         if (task === undefined) return refused('task-not-found', 'no task with id ' + args.taskId)
         return json({ ok: true, task: taskDetail(task, snapshot.tasks, snapshot.sessionDefaultPermission) })