dsh-taskboard 0.7.2 → 0.7.4

package/src/client/i18n/zh.ts

@@ -282,6 +282,11 @@ export const zh = {
   'form.field.mode': '执行方式',
   'form.mode.claim': '🤝 认领制',
   'form.mode.claimHint': '项目内会话认领',
+  'form.mode.once': '⏰ 定时执行',
+  'form.mode.onceHint': '指定时间只跑一次',
+  'form.mode.periodic': '🔁 定期执行',
+  'form.mode.periodicHint': '按 cron 到点重复开跑',
+  'form.field.runAt': '触发时间',
   'form.mode.scheduled': '⏰ 定时执行',
   'form.mode.scheduledHint': '到点自动开跑',
   'form.field.cron': 'Cron 表达式',
@@ -316,7 +321,9 @@ export const zh = {
   'form.hint.needTitle': '请填写标题',
   'form.hint.needProject': '请选择项目',
   'form.hint.cronBad': 'Cron 表达式无效（分 时 日 月 周）',
+  'form.hint.runAtBad': '请选择未来的触发时间',
   'form.hint.nextRun': '下次运行 {time}',
+  'form.hint.onceAt': '将于 {time} 触发一次',
   'form.hint.saveVersion': '保存后版本 v{v} → v{next}',
   'form.hint.createClaim': '创建后项目内会话可认领执行',
   'form.action.runBlockedTitle': '任务正在执行中，不能重复发起',
@@ -490,6 +497,9 @@ export const zh = {
   'sys.sessionError': '[系统] 会话执行异常：{error}；任务已退回待办。',
   'sys.sessionDone': '[系统] 会话执行完毕，已自动进入待验收。',
   'sys.cronDead': '[系统] 定时表达式 {cron} 在 4 年内没有可触发时间，已停用定时；请修正 cron 后重新开启。',
+  'sys.periodicHandoff': '[系统] 定期任务本轮执行完毕，定时已由新待办卡 {nextTaskId} 承接，请审查本卡后验收。',
+  'sys.spawnedFrom': '[系统] 定期任务上一轮执行完毕（执行 {executionId}），本卡承接定时继续下一轮；上一轮成果见 {sourceId} 的待验收。',
+  'sys.runAtMissed': '[系统] 定时执行错过触发时间（主机当时未运行），本次不再补跑；可手动执行或修改定时。',
   'sys.mergeSingle': '[系统] 分支 {branch} 已合并到主工作区（--no-ff）。',
   'sys.mergeMulti': '[系统] 分支已按仓库合并（--no-ff）：{summary}',
 } as const

package/src/client/styles.ts

@@ -609,6 +609,11 @@ button.dsh-atb-chip2.dsh-atb-chip-btn:hover {
 .dsh-atb-urgency-opt[data-on="true"][data-urgency="relaxed"] { border-color: rgba(62,99,221,.65); background: rgba(62,99,221,.1); }
 
 .dsh-atb-mode-picker { display: grid; grid-template-columns: 1fr 1fr; gap: 7px; }
+/* Execution mode has THREE options (认领 / 定时 / 定期): keep them on one row. */
+.dsh-atb-mode-picker[data-exec="true"] { grid-template-columns: repeat(3, 1fr); }
+.dsh-atb-mode-picker[data-exec="true"] .dsh-atb-mode-opt { padding: 7px 8px; }
+.dsh-atb-mode-picker[data-exec="true"] .dsh-atb-mode-name { font-size: 12px; }
+.dsh-atb-mode-picker[data-exec="true"] .dsh-atb-mode-hint { font-size: 10px; }
 .dsh-atb-mode-opt {
   display: flex; flex-direction: column; align-items: flex-start; gap: 3px;
   padding: 8px 10px; border-radius: 9px; cursor: pointer;

package/src/host/execution.ts

@@ -17,7 +17,10 @@ import {
   effectivePrompt,
   newCommentId,
   newExecutionId,
+  nextCronTime,
   normalizeBody,
+  parseCron,
+  spawnNextCycle,
   type ExecutionRecord,
   type ExecutionRepoEvidence,
   type IsolationMode,
@@ -381,6 +384,16 @@ export class ExecutionService {
         gate = `no task ${taskId}`
         return undefined
       }
+      // A status may change after the scheduler selected/advanced the task.
+      // Recheck at the atomic execution gate so terminal tasks cannot be
+      // revived by that race. Only todo fires scheduled (periodic or one-
+      // shot); an in_review card is finished work and never refires — a
+      // periodic run's successor todo card carries the schedule onward.
+      // Manual reruns keep their existing semantics.
+      if (trigger === 'scheduled' && target.status !== 'todo') {
+        gate = `scheduled task is not actionable (${target.status})`
+        return undefined
+      }
       if (target.status === 'in_progress' || target.executions.some(e => e.outcome === 'running')
         || [...this.runs.values()].some(e => target.executions.some(x => x.sessionId === e.sessionId))) {
         gate = 'task is already in progress'
@@ -655,6 +668,38 @@ export class ExecutionService {
             t.status = 'in_review'
             t.updatedAt = now
             t.updatedBy = { kind: 'system' }
+            // Periodic scheduled success (定期执行): the finished card stays
+            // here for acceptance while a fresh todo card minted from it
+            // carries the cron onward. The cron is consumed either way so
+            // the in_review card can never refire.
+            if (execution.trigger === 'scheduled' && t.execution.cron !== undefined) {
+              const match = parseCron(t.execution.cron)
+              const next = match === null ? undefined : nextCronTime(match, now) ?? undefined
+              if (next !== undefined) {
+                const successor = spawnNextCycle(t, executionId, now)
+                t.execution = { mode: 'claim' }
+                t.comments.push({
+                  id: newCommentId(),
+                  body: normalizeBody(`[系统] 定期任务本轮执行完毕，定时已由新待办卡 ${successor.id} 承接，请审查本卡后验收。`),
+                  systemKey: 'sys.periodicHandoff',
+                  systemParams: { nextTaskId: successor.id },
+                  version: 1,
+                  createdAt: now,
+                })
+                ledger.tasks.push(successor)
+                return [t, successor]
+              }
+              // Dead cron (no match within the scan window): consume it with
+              // a comment instead of letting the handoff die silently.
+              t.execution = { mode: 'claim' }
+              t.comments.push({
+                id: newCommentId(),
+                body: normalizeBody('[系统] 定期表达式已无未来触发时间，本轮结束后定时停用；如需继续请重新设置。'),
+                systemKey: 'sys.cronDead',
+                version: 1,
+                createdAt: now,
+              })
+            }
           }
           return [t]
         }

package/src/host/routes.ts

@@ -139,7 +139,7 @@ function normalizeTemplateSpec(raw: unknown, now: number): TaskTemplate['task']
   if (presetId !== undefined && presetId.trim().length > 0) spec.presetId = presetId.trim()
   if (permission !== undefined && permission.trim().length > 0) spec.permission = asPermission(permission)
   if (e.execution !== undefined) {
-    spec.execution = normalizeExecution(e.execution as { mode?: string; cron?: string }, now)
+    spec.execution = normalizeExecution(e.execution as { mode?: string; cron?: string; runAt?: unknown }, now)
   }
   if (e.model !== undefined) spec.model = normalizeModel(e.model)
   if (e.checklist !== undefined) {
@@ -651,7 +651,7 @@ export function registerTaskboardRoutes(ctx: Context, options: TaskboardRoutesOp
           if (status !== 'backlog' && status !== 'todo') {
             throw new Error('Error: invalid_transition: a new task must start as backlog or todo')
           }
-          const execution = normalizeExecution((body.execution as { mode?: string; cron?: string } | undefined) ?? {}, options.now())
+          const execution = normalizeExecution((body.execution as { mode?: string; cron?: string; runAt?: unknown } | undefined) ?? {}, options.now())
           const model = body.model === undefined ? undefined : checkModel(body.model, options.modelProviders)
           const isolationRaw = str(body, 'isolation')
           // 0.5.0: an omitted isolation is MATERIALIZED from the board
@@ -747,7 +747,7 @@ export function registerTaskboardRoutes(ctx: Context, options: TaskboardRoutesOp
               }
               if (typeof body.blocked === 'boolean') next.blocked = body.blocked
               // The GUI (task owner surface) may edit model/execution; null clears the model.
-              if (body.execution !== undefined) next.execution = normalizeExecution(body.execution as { mode?: string; cron?: string }, options.now())
+              if (body.execution !== undefined) next.execution = normalizeExecution(body.execution as { mode?: string; cron?: string; runAt?: unknown }, options.now())
               if (body.model === null) next.model = undefined
               else if (body.model !== undefined) next.model = checkModel(body.model, options.modelProviders)
               // Isolation may change only before the first execution (分支与基线
@@ -821,6 +821,7 @@ export function registerTaskboardRoutes(ctx: Context, options: TaskboardRoutesOp
             await store.mutate('task-moved', ledger => {
               const { index, task } = liveTaskAt(ledger, id)
               if (ifVersion !== task.version) throw new Error(`Error: version_conflict: stale version ${ifVersion} (current ${task.version})`)
+              if (task.status !== 'in_review') throw new Error(`Error: invalid_transition: reject requires in_review (current ${task.status})`)
               if (!canTransition(task.status, 'todo')) throw new Error(`Error: invalid_transition: illegal transition ${task.status} → todo`)
               next = structuredClone(task)
               next.status = 'todo'

package/src/host/scheduler.ts

@@ -92,28 +92,77 @@ export class SchedulerService {
     const now = this.deps.now()
     const ledger: TaskLedger = this.deps.store.snapshot()
     for (const task of ledger.tasks) {
-      if (task.execution.mode !== 'scheduled' || task.execution.cron === undefined) continue
-      if (task.execution.nextRunAt === undefined) continue
-      if (task.status === 'in_progress' || task.trashedAt !== undefined) continue
-      if (task.execution.nextRunAt > now) continue
+      if (task.execution.mode !== 'scheduled' || task.trashedAt !== undefined) continue
+      // Only todo fires. A finished periodic run settles in review (its cron
+      // moves to a freshly minted successor todo card), and terminal/parked
+      // states retain their config so an explicit reopen can resume — none
+      // of these ever refire from here.
+      if (task.status !== 'todo') continue
       // At the concurrency cap (S4: checked FRESH per task — runs register
       // only after agent creation, so a once-per-tick snapshot under-counted
-      // the startup window): leave nextRunAt in the past and retry next tick
-      // — advancing here would silently burn this window.
+      // the startup window): leave the due time in place and retry next tick
+      // — advancing/consuming here would silently burn this window.
       if (this.deps.execution.inFlight() >= (this.deps.maxConcurrent ?? DEFAULT_MAX_CONCURRENT)) continue
-      const missed = now - task.execution.nextRunAt > SKIP_AFTER_MS
 
-      // Advance the schedule AND record the trigger in ONE mutation (S13:
-      // one revision bump, one broadcast, and the two writes can no longer
-      // straddle a status change), then run unless the window was missed.
-      await this.advanceAndMark(task.id, now, missed ? undefined : task.execution.nextRunAt)
-      if (missed) continue
-      await this.deps.execution.run(task.id, 'scheduled').catch(error => {
-        console.error('[dsh-taskboard] scheduled run failed:', error)
-      })
+      if (task.execution.cron !== undefined) {
+        // Periodic (定期执行): refire at every cron match.
+        if (task.execution.nextRunAt === undefined) continue
+        if (task.execution.nextRunAt > now) continue
+        const missed = now - task.execution.nextRunAt > SKIP_AFTER_MS
+
+        // Advance the schedule AND record the trigger in ONE mutation (S13:
+        // one revision bump, one broadcast, and the two writes can no longer
+        // straddle a status change), then run unless the window was missed.
+        await this.advanceAndMark(task.id, now, missed ? undefined : task.execution.nextRunAt)
+        if (missed) continue
+        await this.deps.execution.run(task.id, 'scheduled').catch(error => {
+          console.error('[dsh-taskboard] scheduled run failed:', error)
+        })
+      } else if (task.execution.runAt !== undefined) {
+        // One-shot (定时执行): fire once at the instant, then consume it.
+        const due = task.execution.runAt
+        if (due > now) continue
+        const missed = now - due > SKIP_AFTER_MS
+
+        // Consume the one-shot AND record the trigger in ONE mutation, so a
+        // failure can never re-fire it (the settle path returns the card to
+        // todo with a comment, and the gone runAt keeps it there).
+        await this.consumeRunAt(task.id, now, missed ? due : undefined)
+        if (missed) continue
+        await this.deps.execution.run(task.id, 'scheduled').catch(error => {
+          console.error('[dsh-taskboard] scheduled run failed:', error)
+        })
+      }
     }
   }
 
+  /**
+   * Consume a one-shot task's runAt in one serial-queue mutation: the field
+   * and nextRunAt are cleared the moment the trigger fires, so the task can
+   * never fire twice. A window missed while the host was down is consumed
+   * too, with a system comment instead of a silent drop.
+   */
+  private async consumeRunAt(taskId: string, now: number, missedDue: number | undefined): Promise<void> {
+    await this.deps.store.mutate('task-updated', (ledger) => {
+      const task = ledger.tasks.find(t => t.id === taskId)
+      if (task === undefined || task.execution.runAt === undefined) return undefined
+      if (task.status !== 'todo' || task.trashedAt !== undefined) return undefined
+      delete task.execution.runAt
+      task.execution.nextRunAt = undefined
+      task.execution.lastTriggeredAt = now
+      if (missedDue !== undefined) {
+        task.comments.push({
+          id: newCommentId(),
+          body: normalizeBody('[系统] 定时执行错过触发时间（主机当时未运行），本次不再补跑；可手动执行或修改定时。'),
+          systemKey: 'sys.runAtMissed',
+          version: 1,
+          createdAt: now,
+        })
+      }
+      return [task]
+    })
+  }
+
   /**
    * Recompute the next run and record the trigger instant for one scheduled
    * task, in one serial-queue mutation. S12: a cron that can no longer match
@@ -126,7 +175,7 @@ export class SchedulerService {
     await this.deps.store.mutate('task-updated', (ledger) => {
       const task = ledger.tasks.find(t => t.id === taskId)
       if (task === undefined || task.execution.cron === undefined) return undefined
-      if (task.status === 'in_progress' || task.trashedAt !== undefined) return undefined
+      if (task.status !== 'todo' || task.trashedAt !== undefined) return undefined
       const match = parseCron(task.execution.cron)
       const next = match === null ? undefined : nextCronTime(match, now) ?? undefined
       if (next === undefined) {

package/src/host/session-sync.ts

@@ -15,8 +15,11 @@ import {
   newCommentId,
   newExecutionId,
   newTaskId,
+  nextCronTime,
   normalizeBody,
   normalizeTitle,
+  parseCron,
+  spawnNextCycle,
   type TaskRecord,
 } from '../shared/protocol.ts'
 import type { EventsFace } from './execution.ts'
@@ -604,8 +607,10 @@ export class ExternalSessionSyncService {
       if (task === undefined || task.trashedAt !== undefined) return undefined
 
       // Settle running execution
+      let scheduledTrigger = false
       for (const exec of task.executions) {
         if (exec.sessionId === sessionId && exec.outcome === 'running') {
+          scheduledTrigger = exec.trigger === 'scheduled'
           exec.endedAt = now
           if (isFailure) {
             exec.outcome = 'failed'
@@ -645,6 +650,35 @@ export class ExternalSessionSyncService {
             version: 1,
             createdAt: now,
           })
+          // Periodic scheduled success (定期执行): same handoff as the
+          // execution service — the finished card stays in review while a
+          // fresh todo card carries the cron onward.
+          if (scheduledTrigger && task.execution.cron !== undefined) {
+            const match = parseCron(task.execution.cron)
+            const next = match === null ? undefined : nextCronTime(match, now) ?? undefined
+            if (next !== undefined) {
+              const successor = spawnNextCycle(task, undefined, now)
+              task.execution = { mode: 'claim' }
+              task.comments.push({
+                id: newCommentId(),
+                body: normalizeBody(`[系统] 定期任务本轮执行完毕，定时已由新待办卡 ${successor.id} 承接，请审查本卡后验收。`),
+                systemKey: 'sys.periodicHandoff',
+                systemParams: { nextTaskId: successor.id },
+                version: 1,
+                createdAt: now,
+              })
+              ledger.tasks.push(successor)
+              return [task, successor]
+            }
+            task.execution = { mode: 'claim' }
+            task.comments.push({
+              id: newCommentId(),
+              body: normalizeBody('[系统] 定期表达式已无未来触发时间，本轮结束后定时停用；如需继续请重新设置。'),
+              systemKey: 'sys.cronDead',
+              version: 1,
+              createdAt: now,
+            })
+          }
         }
       }
       return [task]

package/src/host/tools.ts

@@ -27,11 +27,13 @@ import { defineTool } from './sdk.ts'
 import {
   MAX_CHECKLIST_ITEMS,
   asIsolation,
+  asPermission,
   asStatus,
   asUrgency,
   canTransition,
   checklistFromTexts,
   defaultIsolationOf,
+  defaultPermissionOf,
   effectivePrompt,
   isClaim,
   isClaimedBy,
@@ -87,7 +89,7 @@ function taskDetail(t: TaskRecord & { effectivePrompt?: string }): string {
   const lines: string[] = [
     `任务 ${t.id} 「${t.title}」`,
     `状态: ${t.status} (v${t.version}) · 紧急度: ${t.urgency} · 项目: ${t.workspaceId}${t.blocked ? ' · 受阻' : ''}`,
-    `执行方式: ${t.execution.mode}${t.execution.cron !== undefined ? ` cron=${t.execution.cron}` : ''}`,
+    `执行方式: ${t.execution.mode}${t.execution.cron !== undefined ? ` 定期 cron=${t.execution.cron}` : ''}${t.execution.runAt !== undefined ? ` 定时(一次) runAt=${new Date(t.execution.runAt).toISOString()}` : ''}`,
     `隔离: ${t.isolation === 'none' ? '关闭（原目录执行）' : 'Git Worktree'}${t.branch !== undefined ? `（分支 ${t.branch}）` : ''}${t.branches !== undefined ? `（多仓库镜像 ${Object.keys(t.branches).length + (t.branch !== undefined ? 1 : 0)} 个仓库）` : ''}`,
   ]
   const holder = isClaimedBy(t)
@@ -377,7 +379,7 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
     description:
       'Create a task on the board. Required: title, workspaceId (project), urgency (urgent/normal/relaxed). '
       + 'Optional: description, prompt (sent to a fresh session on execution), status (default todo), '
-      + 'execution mode (claim|scheduled + cron), model {provider, model} to pin executions to a model. '
+      + 'execution mode (claim | scheduled+cron 定期重复 | scheduled+runAt 定时一次), model {provider, model} to pin executions to a model. '
       + 'Do not track trivial requests as tasks.',
     parameters: {
       title: { type: 'string', required: true, description: 'Short imperative line (1..200 chars).' },
@@ -389,10 +391,11 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
       execution: {
         type: 'object',
         additionalProperties: false,
-        description: 'Execution config: { mode: "claim" } (default) or { mode: "scheduled", cron: "m h dom mon dow" }.',
+        description: 'Execution config: { mode: "claim" } (default) | { mode: "scheduled", cron } periodic (定期, repeats) | { mode: "scheduled", runAt } one-shot (定时, fires once).',
         properties: {
           mode: { type: 'string', description: 'claim | scheduled.' },
-          cron: { type: 'string', description: 'Five-field cron expression (scheduled only).' },
+          cron: { type: 'string', description: 'Five-field cron expression (scheduled periodic only).' },
+          runAt: { type: 'string', description: 'One-shot trigger time: epoch ms or ISO string (scheduled one-shot only; must be in the future).' },
         },
       },
       model: {
@@ -409,6 +412,10 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
         type: 'string',
         description: 'Code isolation for executions: "worktree" (each run gets a fresh git worktree on branch task/<标题>+<taskId>) or "none" (run in the project directory, zero git interaction). Omitted → the board default (看板设置 → 默认执行隔离; factory default "none").',
       },
+      permission: {
+        type: 'string',
+        description: 'Execution permission: "read-only", "workspace-write", or "danger-full-access". Omitted → the board default (看板设置 → 默认权限; factory default "workspace-write").',
+      },
       presetId: {
         type: 'string',
         description: 'Agent preset the execution session is composed from (its tool set / persona); default = the deployment default preset. Optional.',
@@ -434,9 +441,10 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
       status?: string
       description?: string
       prompt?: string
-      execution?: { mode?: string; cron?: string }
+      execution?: { mode?: string; cron?: string; runAt?: string | number }
       model?: { provider?: string; model?: string }
       isolation?: string
+      permission?: string
       presetId?: string
       checklist?: string[]
     }, exec: unknown) {
@@ -457,6 +465,9 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
         // (看板设置) at creation, so later setting changes never rewrite
         // existing tasks.
         const isolation = args.isolation === undefined ? defaultIsolationOf(store.snapshot().settings) : asIsolation(args.isolation)
+        // Match the GUI create route: freeze the current board default onto
+        // the task so later settings changes do not silently alter a schedule.
+        const permission = args.permission === undefined ? defaultPermissionOf(store.snapshot().settings) : asPermission(args.permission)
         const presetId = args.presetId?.trim() || undefined
         // T9: match the GUI create route — trim and drop blank lines instead
         // of failing the whole call over one empty string.
@@ -475,6 +486,7 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
           execution,
           model,
           isolation,
+          permission,
           ...(presetId !== undefined ? { presetId } : {}),
           ...(checklist !== undefined ? { checklist } : {}),
           version: 1,
@@ -498,7 +510,7 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
   disposers.push(register(defineTool({
     name: 'taskboard_update',
     description:
-      'Update a task\'s title/description/prompt/urgency/blocked. Requires ifVersion (read first). '
+      'Update a task\'s title/description/prompt/urgency/blocked/permission. Requires ifVersion (read first). '
       + 'The model and execution config are read-only through this tool (they belong to the task owner/user).',
     parameters: {
       id: { type: 'string', required: true, description: 'Task id.' },
@@ -508,6 +520,7 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
       prompt: { type: 'string', description: 'New execution prompt.' },
       urgency: { type: 'string', description: 'urgent | normal | relaxed.' },
       blocked: { type: 'boolean', description: 'Blocked marker (work cannot continue right now).' },
+      permission: { type: 'string', description: 'Execution permission: read-only | workspace-write | danger-full-access.' },
     },
     output: {
       schema: JSON_OUT,
@@ -525,6 +538,7 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
       prompt?: string
       urgency?: string
       blocked?: boolean
+      permission?: string
     }, exec: unknown) {
       try {
         const { actor } = caller(exec as ToolRunContext)
@@ -542,6 +556,7 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
           if (args.prompt !== undefined) next.prompt = normalizePrompt(args.prompt)
           if (args.urgency !== undefined) next.urgency = asUrgency(args.urgency)
           if (args.blocked !== undefined) next.blocked = args.blocked
+          if (args.permission !== undefined) next.permission = asPermission(args.permission)
           next.version = task.version + 1
           next.updatedAt = deps.now()
           next.updatedBy = actor

package/src/shared/api.ts

@@ -54,7 +54,7 @@ export type CreateTaskBody = {
   urgency: string
   description?: string
   prompt?: string
-  execution?: { mode?: string; cron?: string }
+  execution?: { mode?: string; cron?: string; runAt?: string | number }
   model?: TaskModel
   /** Code isolation for executions ('worktree' | 'none'); omitted = default. */
   isolation?: string
@@ -76,7 +76,7 @@ export type UpdateTaskBody = {
   blocked?: boolean
   /** Rebind the task to another project (GUI owner surface only). */
   workspaceId?: string
-  execution?: { mode?: string; cron?: string }
+  execution?: { mode?: string; cron?: string; runAt?: string | number }
   model?: TaskModel | null
   /** Change isolation; locked once the task has execution history. */
   isolation?: string
@@ -170,7 +170,7 @@ export type TaskTemplateSpec = {
   description?: string
   prompt?: string
   urgency?: string
-  execution?: { mode?: string; cron?: string }
+  execution?: { mode?: string; cron?: string; runAt?: string | number }
   model?: TaskModel
   isolation?: string
   presetId?: string

package/src/shared/protocol.ts

@@ -52,7 +52,7 @@ const TRANSITIONS: Readonly<Record<TaskStatus, readonly TaskStatus[]>> = {
   todo: ['in_progress', 'backlog', 'canceled'],
   in_progress: ['in_review', 'todo', 'canceled'],
   in_review: ['in_progress', 'todo', 'done', 'canceled'],
-  done: ['archived'],
+  done: ['archived', 'todo'],
   canceled: ['archived', 'todo'],
   archived: [],
 }
@@ -220,8 +220,18 @@ export type ExecutionMode = 'claim' | 'scheduled'
  */
 export interface ExecutionConfig {
   mode: ExecutionMode
-  /** Five-field cron expression (minute hour day month weekday); required for `scheduled`. */
+  /**
+   * Five-field cron expression (minute hour day month weekday). Present on
+   * PERIODIC scheduled tasks (定期执行): the scheduler refires the task each
+   * time it comes due while the card sits in todo.
+   */
   cron?: string
+  /**
+   * One-shot trigger time (epoch ms). Present on ONE-SHOT scheduled tasks
+   * (定时执行): the scheduler fires the task once when due and consumes the
+   * field. Mutually exclusive with {@link cron}.
+   */
+  runAt?: number
   /** Next due time (epoch ms); maintained by the host scheduler. */
   nextRunAt?: number
   /** Last time the scheduler triggered this task (epoch ms). */
@@ -573,6 +583,13 @@ export type TaskRecord = {
   executions: ExecutionRecord[]
   /** How many older execution records were pruned by the retention cap. */
   executionsPruned?: number
+  /**
+   * Id of the task this card continues (0.7.x periodic execution): when a
+   * PERIODIC scheduled task succeeds, the finished card moves to in_review
+   * and a fresh todo card carrying the cron is minted to keep the cycle
+   * going. Absent on originally created tasks.
+   */
+  spawnedFrom?: string
   /** Soft-delete marker set by agent `taskboard_delete`; user confirms the purge. */
   trashedAt?: number
 }
@@ -593,6 +610,60 @@ export function pruneExecutions(task: TaskRecord): void {
   task.executionsPruned = (task.executionsPruned ?? 0) + dropped
 }
 
+/**
+ * Mint the successor card of a PERIODIC scheduled task that just succeeded
+ * (0.7.x): the finished card goes to in_review for acceptance while this
+ * fresh todo card carries the cron onward, keeping the cycle alive. The
+ * next run is recomputed from `now` (no compensating catch-up burst).
+ * Pure: the caller pushes the returned record into the ledger.
+ * @param source - the finished periodic task (still carrying its cron).
+ * @param prevExecutionId - id of the execution that just succeeded.
+ * @param now - current epoch ms.
+ * @returns the successor task record.
+ */
+export function spawnNextCycle(source: TaskRecord, prevExecutionId: string | undefined, now: number): TaskRecord {
+  const cron = source.execution.cron
+  if (cron === undefined) throw new Error('spawnNextCycle: source task has no cron')
+  const match = parseCron(cron)
+  const next = match === null ? undefined : nextCronTime(match, now) ?? undefined
+  if (next === undefined) throw new Error('spawnNextCycle: cron has no upcoming match within 4 years')
+  return {
+    id: newTaskId(),
+    title: source.title,
+    description: source.description,
+    prompt: source.prompt,
+    workspaceId: source.workspaceId,
+    urgency: source.urgency,
+    status: 'todo',
+    blocked: false,
+    execution: { mode: 'scheduled', cron, nextRunAt: next },
+    ...(source.model !== undefined ? { model: structuredClone(source.model) } : {}),
+    ...(source.isolation !== undefined ? { isolation: source.isolation } : {}),
+    ...(source.presetId !== undefined ? { presetId: source.presetId } : {}),
+    ...(source.permission !== undefined ? { permission: source.permission } : {}),
+    ...(source.checklist !== undefined
+      ? { checklist: source.checklist.map(item => ({ ...item, checked: false, checkedBy: undefined, checkedAt: undefined, note: undefined })) }
+      : {}),
+    ...(source.branch !== undefined ? { branch: source.branch } : {}),
+    ...(source.branches !== undefined ? { branches: { ...source.branches } } : {}),
+    spawnedFrom: source.id,
+    version: 1,
+    createdAt: now,
+    updatedAt: now,
+    createdBy: { kind: 'system' },
+    updatedBy: { kind: 'system' },
+    comments: [{
+      id: newCommentId(),
+      body: normalizeBody(`[系统] 定期任务上一轮执行完毕（执行 ${prevExecutionId ?? '未知'}），本卡承接定时继续下一轮；上一轮成果见 ${source.id} 的待验收。`),
+      systemKey: 'sys.spawnedFrom',
+      systemParams: { sourceId: source.id, executionId: prevExecutionId ?? '' },
+      version: 1,
+      createdAt: now,
+    }],
+    executions: [],
+  }
+}
+
 /** The whole durable ledger. */
 export type TaskLedger = {
   schemaVersion: number
@@ -712,24 +783,52 @@ export function asStatus(raw: string): TaskStatus {
   return raw as TaskStatus
 }
 
+/**
+ * Parse a raw runAt input: epoch ms number or ISO date string → epoch ms.
+ * @param raw - untyped runAt value.
+ * @returns the epoch ms, or undefined when absent.
+ */
+function normalizeRunAt(raw: unknown): number | undefined {
+  if (raw === undefined || raw === null) return undefined
+  if (typeof raw === 'number' && Number.isFinite(raw)) return Math.trunc(raw)
+  if (typeof raw === 'string') {
+    const t = Date.parse(raw)
+    if (Number.isNaN(t)) throw new Error('execution.runAt is not a valid time (epoch ms or ISO string)')
+    return t
+  }
+  throw new Error('execution.runAt must be an epoch ms number or an ISO date string')
+}
+
 /**
  * Validate an execution config request from raw tool/route input.
- * `scheduled` requires a valid cron; computes the first `nextRunAt` from
- * `now`.
+ * `scheduled` requires either a valid cron (periodic, 定期执行) or a runAt
+ * instant (one-shot, 定时执行); the two are mutually exclusive. A cron's
+ * first `nextRunAt` is computed from `now`.
  * @param raw - raw execution input ({@link ExecutionConfig} fields, untyped).
  * @param now - current epoch ms.
+ * @param opts - `allowPastRunAt` lets the import path keep a historical
+ *   one-shot instant instead of rejecting it.
  * @returns the normalized config.
  */
 export function normalizeExecution(
-  raw: { mode?: string; cron?: string },
+  raw: { mode?: string; cron?: string; runAt?: unknown },
   now: number,
+  opts?: { allowPastRunAt?: boolean },
 ): ExecutionConfig {
   const mode = raw.mode ?? 'claim'
   if (mode !== 'claim' && mode !== 'scheduled') {
     throw new Error("execution.mode must be 'claim' or 'scheduled'")
   }
   if (mode === 'claim') return { mode }
+  const runAt = normalizeRunAt(raw.runAt)
   const cron = (raw.cron ?? '').trim()
+  if (cron.length > 0 && runAt !== undefined) {
+    throw new Error('execution: cron and runAt are mutually exclusive (periodic vs one-shot)')
+  }
+  if (runAt !== undefined) {
+    if (!opts?.allowPastRunAt && runAt <= now) throw new Error('execution.runAt must be in the future')
+    return { mode, runAt, nextRunAt: runAt }
+  }
   const match = parseCron(cron)
   if (match === null) throw new Error('execution.cron is not a valid 5-field cron expression')
   const next = nextCronTime(match, now)
@@ -1055,8 +1154,9 @@ export function validateImportedTask(raw: unknown, now: number): { ok: true; tas
   if (!isValidTaskId(id)) return fail('missing/invalid id (must match ^[A-Za-z0-9][A-Za-z0-9_-]{0,99}$)')
   try {
     const execution = normalizeExecution(
-      typeof e.execution === 'object' && e.execution !== null ? e.execution as { mode?: string; cron?: string } : {},
+      typeof e.execution === 'object' && e.execution !== null ? e.execution as { mode?: string; cron?: string; runAt?: unknown } : {},
       now,
+      { allowPastRunAt: true },
     )
     const comments: CommentRecord[] = []
     if (Array.isArray(e.comments)) {

package/src/shared/version.ts

@@ -6,5 +6,5 @@
  */
 
 /** The package version (must equal package.json "version"). */
-export const PLUGIN_VERSION = '0.7.1'
+export const PLUGIN_VERSION = '0.7.4'