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

package/src/core/poll-cadence.ts

@@ -0,0 +1,41 @@
+/**
+ * Roster-poll cadence: the one recurring Host timer the board holds.
+ *
+ * The cadence is a user setting (seconds), so the bounds and the seconds to
+ * milliseconds conversion live here rather than in either half: the settings
+ * card validates a draft against the same range the Host clamps a hand-edited
+ * configuration to, and a programmatic mount that passes no cadence gets the
+ * default.
+ *
+ * @module dsh-task-board/core/poll-cadence
+ */
+
+/** Cadence used when neither the settings document nor the mount names one. */
+export const DEFAULT_SESSION_POLL_SECONDS = 5
+
+/** Shortest accepted cadence: a faster poll only burns CPU on the Host. */
+export const SESSION_POLL_MIN_SECONDS = 1
+
+/** Longest accepted cadence, five minutes. */
+export const SESSION_POLL_MAX_SECONDS = 300
+
+/**
+ * Clamp a configured cadence into the supported range. A value the schema
+ * would refuse (non-finite, below the floor, above the ceiling) still leaves
+ * the board polling: an out-of-range setting never disables the timer.
+ * @param seconds - configured cadence in seconds, or undefined for the default.
+ * @returns the effective cadence in seconds.
+ */
+export function normalizeSessionPollSeconds(seconds: number | undefined): number {
+  if (seconds === undefined || !Number.isFinite(seconds)) return DEFAULT_SESSION_POLL_SECONDS
+  return Math.min(Math.max(Math.trunc(seconds), SESSION_POLL_MIN_SECONDS), SESSION_POLL_MAX_SECONDS)
+}
+
+/**
+ * The cadence in the milliseconds the Host timer face takes.
+ * @param seconds - configured cadence in seconds, or undefined for the default.
+ * @returns the effective cadence in milliseconds.
+ */
+export function sessionPollMs(seconds: number | undefined): number {
+  return normalizeSessionPollSeconds(seconds) * 1_000
+}

package/src/core/store.ts

@@ -10,7 +10,7 @@
  * localStorage backend.
  */
 import { isValidCron, isValidTimeZone } from './schedule.ts'
-import { isTaskPermission, isTaskStatus, normalizeTags, normalizeTargetId, type ScheduleRule, type TaskFreeze, type TaskRecord, type TaskPermission, type TaskStatus } from './tasks.ts'
+import { SCHEDULE_STOP_REASONS, isTaskPermission, isTaskStatus, normalizeTags, normalizeTargetId, type ScheduleRule, type ScheduleStopReason, type TaskFreeze, type TaskRecord, type TaskPermission, type TaskStatus } from './tasks.ts'
 import { isExecutionOutcome } from './subtask.ts'
 import type { TaskHandover } from './handover.ts'
 import { sanitizeFreezeSnapshot } from './freeze-snapshot.ts'
@@ -87,6 +87,10 @@ function isTaskRecordShape(value: unknown): value is Omit<TaskRecord, 'status'>
     if (entry.initiatedBy !== undefined && typeof entry.initiatedBy !== 'string') return false
     if (entry.frozenBy !== undefined && typeof entry.frozenBy !== 'string') return false
     if (entry.frozenAt !== undefined && typeof entry.frozenAt !== 'number') return false
+    // An external-outcome marker is optional in BOTH directions: a ledger
+    // written before the field existed carries none, and a non-boolean value
+    // is dropped by the repair below rather than trusted as provenance.
+    if (entry.external !== undefined && typeof entry.external !== 'boolean') return false
     // The acceptance block is repaired like every other optional field: an
     // unusable one is dropped, which can only make the board MORE strict.
     if (entry.verification !== undefined && normalizeVerification(entry.verification) === undefined) return false
@@ -104,29 +108,73 @@ function normalizeStatus(status: unknown): TaskStatus {
   return isTaskStatus(status) ? status : 'todo'
 }
 
+/** A persisted ms timestamp, kept only when it is a usable finite number. */
+function optionalInstant(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined
+}
+
+/** A persisted positive-integer run cap, or undefined for unlimited/repair. */
+function optionalRunCap(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 1 ? value : undefined
+}
+
+/** A persisted stop reason, kept only when it names a reason this build knows. */
+function optionalStopReason(value: unknown): ScheduleStopReason | undefined {
+  return typeof value === 'string' && SCHEDULE_STOP_REASONS.includes(value as ScheduleStopReason)
+    ? value as ScheduleStopReason
+    : undefined
+}
+
 /**
- * Repair a persisted schedule rule: drop rules without a usable cron string,
- * coerce booleans/numbers, and leave `nextRunAt`/`lastTriggeredAt` undefined
- * when missing (a fresh recompute or the next tick fixes them).
+ * Repair a persisted schedule rule. Both modes are repaired field by field and
+ * a rule that carries no usable plan is dropped (the task row survives):
+ * a recurring rule without a well-formed 5-field cron, or a one-shot without a
+ * finite planned instant. A rule written before `mode` existed is a cron rule.
  */
 function normalizeSchedule(schedule: unknown): ScheduleRule | undefined {
   if (typeof schedule !== 'object' || schedule === null) return undefined
   const rule = schedule as Record<string, unknown>
+  // A stored zone survives only when this runtime can resolve it; an unusable
+  // name is dropped (the rule then follows the Host zone) instead of being
+  // kept to fail every later resolve.
+  const timeZone = typeof rule.timeZone === 'string' && isValidTimeZone(rule.timeZone) ? rule.timeZone : undefined
+  const runCountValue = rule.runCount
+  const runCount = typeof runCountValue === 'number' && Number.isInteger(runCountValue) && runCountValue >= 0
+    ? runCountValue
+    : 0
+  const endedAt = optionalInstant(rule.endedAt)
+  const endedReason = optionalStopReason(rule.endedReason)
+  const skippedAt = optionalInstant(rule.skippedAt)
+  const skippedReason = optionalStopReason(rule.skippedReason)
+  const common = {
+    enabled: rule.enabled === true,
+    ...(timeZone === undefined ? {} : { timeZone }),
+    nextRunAt: optionalInstant(rule.nextRunAt),
+    lastTriggeredAt: optionalInstant(rule.lastTriggeredAt),
+    runCount,
+    ...(endedAt === undefined ? {} : { endedAt }),
+    ...(endedReason === undefined ? {} : { endedReason }),
+    ...(skippedAt === undefined ? {} : { skippedAt }),
+    ...(skippedReason === undefined ? {} : { skippedReason }),
+  }
+  if (rule.mode === 'once') {
+    const at = optionalInstant(rule.at)
+    // A one-shot with no instant can never fire; drop it rather than keep a
+    // rule the scheduler would have to interpret.
+    if (at === undefined) return undefined
+    return { ...common, mode: 'once', at }
+  }
   // Reject (drop) a schedule whose cron is not a well-formed 5-field
   // expression: a malformed rule would otherwise linger as a never-firing
   // schedule instead of being dropped for later repair.
   if (typeof rule.cron !== 'string') return undefined
   if (rule.cron.trim() === '' || !isValidCron(rule.cron)) return undefined
-  // A stored zone survives only when this runtime can resolve it; an unusable
-  // name is dropped (the rule then follows the Host zone) instead of being
-  // kept to fail every later resolve.
-  const timeZone = typeof rule.timeZone === 'string' && isValidTimeZone(rule.timeZone) ? rule.timeZone : undefined
+  const maxRuns = optionalRunCap(rule.maxRuns)
   return {
-    enabled: rule.enabled === true,
+    ...common,
+    mode: 'cron',
     cron: rule.cron,
-    ...(timeZone === undefined ? {} : { timeZone }),
-    nextRunAt: typeof rule.nextRunAt === 'number' ? rule.nextRunAt : undefined,
-    lastTriggeredAt: typeof rule.lastTriggeredAt === 'number' ? rule.lastTriggeredAt : undefined,
+    ...(maxRuns === undefined ? {} : { maxRuns }),
   }
 }
 
@@ -210,6 +258,7 @@ export function parseLedger(raw: string | null): TaskRecord[] {
       // A malformed acceptance block is dropped rather than dropping the
       // execution record: the board then treats that run as unverified.
       verification: normalizeVerification(execution.verification),
+      external: execution.external === true ? true : undefined,
     }))
     // Execution targets are normalized like the schedule: blank strings
     // clear the pin and unknown permission strings from a future version
@@ -219,9 +268,9 @@ export function parseLedger(raw: string | null): TaskRecord[] {
     task.archivedAt = typeof row.archivedAt === 'number' && Number.isFinite(row.archivedAt) ? row.archivedAt : undefined
     task.permission = isTaskPermission(row.permission) ? row.permission as TaskPermission : undefined
     task.reuseSession = row.reuseSession === true ? true : undefined
-    // The goal opt-in is stored only when it is OFF: absent means the default
-    // (start each run with /goal), so a hand-edited true normalizes back to it.
-    task.goalRun = row.goalRun === false ? false : undefined
+    // The goal opt-in is stored only when it is ON: absent means the default
+    // (one plain turn per run), so a hand-edited false normalizes back to it.
+    task.goalRun = row.goalRun === true ? true : undefined
     // The acceptance opt-out is stored only when it is ON: absent inherits the
     // board-wide switch, so a hand-edited false normalizes back to inherit.
     task.skipVerification = row.skipVerification === true ? true : undefined

package/src/core/tasks.ts

@@ -37,8 +37,23 @@ export interface ExecutionRecord {
    * Session id of the DSH session that issued the run/rerun action (issue #6
    * audit origin). Client-asserted, not a trust boundary; absent when the run
    * was triggered by cron (source unknown).
+   *
+   * On an EXTERNAL record (issue #1826) this names the agent that completed the
+   * work outside the Host instead, which is what makes the history readable.
    */
   initiatedBy?: string
+  /**
+   * True when this outcome was recorded from outside the Host by
+   * `record-external-outcome` rather than observed from a DSH session
+   * (issue #1826).
+   *
+   * The board never manufactures one of these itself: every Host-side path
+   * (`run`, `settle`, cascade folding, restart recovery) writes an execution
+   * without it, so `external` is the single field separating work this Host ran
+   * from work an outside agent reported. Such a record never carries a
+   * `sessionId` and never claims a verdict the Host observed.
+   */
+  external?: boolean
   /** Freeze instant captured from the card snapshot when the run opened. */
   frozenAt?: number
   /** Freeze source session captured from the card snapshot when the run opened. */
@@ -88,17 +103,74 @@ export function retainRecentExecutions(executions: readonly ExecutionRecord[]):
   return [...settled.slice(Math.max(settled.length - keepSettled, 0)), ...open]
 }
 
+/**
+ * How a rule produces its triggers: a recurring cron rule, or one single
+ * planned instant. The distinction is stored rather than inferred so a
+ * one-shot is never represented as a date-restricted cron expression.
+ */
+export type ScheduleMode = 'cron' | 'once'
+
+/**
+ * Why a due occurrence produced no run, or why a rule stopped on its own.
+ *
+ * These are stable codes, not display text: the board renders them through its
+ * locale dictionary, so the ledger never carries a translated string.
+ */
+export type ScheduleStopReason =
+  /** The single planned instant produced its run. */
+  | 'fired'
+  /** The recurring rule reached its run budget. */
+  | 'limit'
+  /** The plan has no reachable instant any more (an impossible cron). */
+  | 'no-target'
+  /** The instant passed while the board was not running through it. */
+  | 'missed'
+  /** The task already had an open execution, so this occurrence was skipped. */
+  | 'busy'
+  /** An above-default permission was still unconfirmed, so this occurrence was skipped. */
+  | 'permission'
+  /**
+   * A scheduled launch failed before any session existed, so the occurrence
+   * created no execution and its run was refunded rather than spent.
+   */
+  | 'launch-failed'
+
+/** Every stop reason this build understands; the repair and wire gates share it. */
+export const SCHEDULE_STOP_REASONS: readonly ScheduleStopReason[] = [
+  'fired', 'limit', 'no-target', 'missed', 'busy', 'permission', 'launch-failed',
+]
+
 /**
  * A scheduled-run rule attached to a task. The Host scheduler triggers the
  * task when `nextRunAt` is due and persists the rule in the Host ledger.
+ *
+ * A rule is either `cron` (the historical shape: a 5-field expression with an
+ * explicit IANA zone, optionally capped by `maxRuns`) or `once` (one planned
+ * instant, `at`, with an implicit budget of one run). Both modes count the
+ * executions the scheduler actually started in `runCount`; a rule that reaches
+ * its budget stops itself in the ledger (`enabled: false` + `endedReason`)
+ * instead of relying on the execution agent to disable it.
  */
 export interface ScheduleRule {
   /** Whether the schedule is armed. */
   enabled: boolean
-  /** 5-field cron expression: `分 时 日 月 周`. */
-  cron: string
   /**
-   * IANA zone the cron wall clock is read in (issue #1722). Absent means the
+   * Which kind of plan this rule carries. A rule loaded from a ledger written
+   * before the field existed normalizes to `cron` (its `cron` is the plan).
+   */
+  mode: ScheduleMode
+  /**
+   * 5-field cron expression: `分 时 日 月 周`. Present on a `cron` rule and
+   * absent on a `once` rule.
+   */
+  cron?: string
+  /**
+   * The instant a `once` rule executes (ms epoch). Kept after the run so the
+   * detail view can still show the planned time once the rule has ended.
+   */
+  at?: number
+  /**
+   * IANA zone the 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.
@@ -108,6 +180,62 @@ export interface ScheduleRule {
   nextRunAt: number | undefined
   /** Instant of the latest scheduled trigger (ms epoch). */
   lastTriggeredAt: number | undefined
+  /**
+   * Scheduled executions the Host has created under this rule. This is the
+   * run budget's counter: it counts executions that were successfully opened
+   * (whatever their later outcome), never completions, and a manual run never
+   * touches it. A skipped occurrence (busy / permission / missed / no target)
+   * creates no execution and therefore consumes nothing.
+   */
+  runCount: number
+  /**
+   * Maximum scheduled executions for a `cron` rule; absent means unlimited
+   * (the historical behavior). A `once` rule has an implicit budget of one and
+   * stores no `maxRuns`.
+   */
+  maxRuns?: number
+  /** Instant the rule stopped itself (ms epoch); absent while it may still fire. */
+  endedAt?: number
+  /** Why the rule stopped itself; present with `endedAt`. */
+  endedReason?: ScheduleStopReason
+  /** Instant of the latest occurrence that produced no run. */
+  skippedAt?: number
+  /** Why that occurrence produced no run; present with `skippedAt`. */
+  skippedReason?: ScheduleStopReason
+}
+
+/**
+ * The rule's total run budget: one for a one-shot, the stored cap for a
+ * recurring rule, and undefined when the rule is unlimited.
+ * @param rule - the schedule rule.
+ * @returns the budget, or undefined for an uncapped rule.
+ */
+export function scheduleRunBudget(rule: ScheduleRule): number | undefined {
+  if (rule.mode === 'once') return 1
+  return rule.maxRuns
+}
+
+/**
+ * Whether a rule has no runs left. The scheduler refuses to open another
+ * execution for an exhausted rule, which is what makes the budget terminal
+ * regardless of restarts or repeated timer fires.
+ * @param rule - the schedule rule.
+ * @returns true when the run budget is spent.
+ */
+export function scheduleExhausted(rule: ScheduleRule): boolean {
+  const budget = scheduleRunBudget(rule)
+  return budget !== undefined && rule.runCount >= budget
+}
+
+/**
+ * The instant a rule plans to fire next, for display, whatever its mode: the
+ * planned `at` of a one-shot, or the stored `nextRunAt` of a recurring rule.
+ * @param rule - the schedule rule.
+ * @returns the planned instant, or undefined when the rule carries none.
+ */
+export function schedulePlannedAt(rule: ScheduleRule): number | undefined {
+  if (rule.mode === 'once') return rule.at
+  return rule.nextRunAt
 }
 
 /**
@@ -300,9 +428,11 @@ export interface TaskRecord {
    * 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.
+   * instead of at the first turn end. Absent means OFF — the option is
+   * unchecked by default, so only an explicit `true` joins the goal run and
+   * every card that never touched it (including every card written before the
+   * field existed) runs one plain turn. A session whose `/goal` command is
+   * refused still runs the prompt.
    */
   goalRun?: boolean
   /**
@@ -410,8 +540,8 @@ export interface NewTaskInput {
   /** 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.
+   * Start the execution with dsh's built-in `/goal`. Absent means the default
+   * (one plain turn); only an explicit true joins the goal run.
    */
   goalRun?: boolean
   /**
@@ -420,12 +550,22 @@ export interface NewTaskInput {
    */
   skipVerification?: boolean
   /**
-   * Optional scheduled-run rule requested at creation time (the new-task
-   * 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.
+   * Optional scheduling rule requested at creation time (the new-task
+   * dialog): an enable flag, the kind of plan (a recurring 5-field cron
+   * expression, or one planned instant for a one-shot), an optional run cap,
+   * 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 plan is valid.
    */
-  schedule?: { enabled: boolean; cron: string; timeZone?: string }
+  schedule?: {
+    enabled: boolean
+    mode?: ScheduleMode
+    cron?: string
+    /** Planned instant of a one-shot rule (ms epoch). */
+    at?: number
+    timeZone?: string
+    /** Run cap of a recurring rule; absent means unlimited. */
+    maxRuns?: number
+  }
   /**
    * Optional frozen context snapshot (goal/progress/next, sanitized by the
    * protocol gate) turning the new task into a continuation card.
@@ -561,10 +701,10 @@ export function createTask(input: NewTaskInput, now: number, id: string): TaskRe
     model: normalizeTargetId(input.model),
     reuseSession: input.reuseSession === true ? true : undefined,
     teamRun: input.teamRun === true ? true : undefined,
-    // Default ON: only an explicit false is stored, so a card that never
+    // Default OFF: only an explicit true 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,
+    // keeps running one plain turn.
+    goalRun: input.goalRun === true ? true : undefined,
     // Default OFF: only an explicit true is stored, so a card that never
     // touched the option inherits the board-wide acceptance switch exactly as
     // every card written before the field existed does.
@@ -582,35 +722,38 @@ export function withStatus(task: TaskRecord, status: TaskStatus, now: number): T
   return { ...task, status, updatedAt: now }
 }
 
+/** Every field a schedule patch may carry; the rest of the rule is carried over. */
+const SCHEDULE_PATCH_KEYS = [
+  'enabled', 'mode', 'cron', 'at', 'timeZone', 'nextRunAt', 'lastTriggeredAt',
+  'runCount', 'maxRuns', 'endedAt', 'endedReason', 'skippedAt', 'skippedReason',
+] as const satisfies ReadonlyArray<keyof ScheduleRule>
+
 /**
  * Merge a schedule patch into a task's schedule rule (creating it when
  * absent), with a fresh updatedAt. Keys present in the patch overwrite the
  * current value — including explicit `undefined`, which clears a field (used
- * to disarm `nextRunAt`); absent keys keep their current value.
+ * to disarm `nextRunAt` or to drop an ended/skip record); absent keys keep
+ * their current value.
  */
 export function withSchedule(
   task: TaskRecord,
   patch: Partial<ScheduleRule>,
   now: number,
 ): TaskRecord {
-  const current = task.schedule
-  const schedule: ScheduleRule = {
-    enabled: current?.enabled ?? false,
-    cron: current?.cron ?? '',
-    ...(current?.timeZone === undefined ? {} : { timeZone: current.timeZone }),
-    nextRunAt: current?.nextRunAt,
-    lastTriggeredAt: current?.lastTriggeredAt,
+  const schedule: ScheduleRule = task.schedule === undefined
+    ? { enabled: false, mode: 'cron', nextRunAt: undefined, lastTriggeredAt: undefined, runCount: 0 }
+    : { ...task.schedule }
+  const fields = schedule as unknown as Record<string, unknown>
+  const next = patch as unknown as Record<string, unknown>
+  for (const key of SCHEDULE_PATCH_KEYS) {
+    if (!(key in patch)) continue
+    if (next[key] === undefined) delete fields[key]
+    else fields[key] = next[key]
   }
-  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
+  // The three non-optional fields can never be cleared into an unusable rule.
+  if (schedule.enabled !== true) schedule.enabled = false
+  if (schedule.mode !== 'once') schedule.mode = 'cron'
+  if (!Number.isFinite(schedule.runCount) || schedule.runCount < 0) schedule.runCount = 0
   return { ...task, updatedAt: now, schedule }
 }
 
@@ -654,6 +797,21 @@ export function startExecution(
   }
 }
 
+/**
+ * The column a settled outcome puts a card in. The ONE derivation shared by
+ * every settlement path (issue #1826): a Host-run execution and an outcome an
+ * outside agent reported both land in the same column from the same rule, so
+ * the column never becomes a second, independent piece of state.
+ @param task - the card being settled.
+ @param outcome - the settled outcome.
+ @returns the status the card shows afterwards.
+ */
+export function settledStatus(task: TaskRecord, outcome: ExecutionOutcome): TaskStatus {
+  if (outcome === 'succeeded') return task.schedule?.enabled === true ? 'todo' : 'done'
+  if (outcome === 'failed') return 'failed'
+  return task.status === 'running' ? 'todo' : task.status
+}
+
 /**
  * Settle a running execution: record the outcome and move the task into the
  * matching column. No-op (returns the input task) when the execution is not
@@ -673,11 +831,7 @@ export function settleExecution(
   const settled: ExecutionRecord = { ...execution, endedAt: now, result: outcome, error }
   const executions = [...task.executions]
   executions[index] = settled
-  const status: TaskStatus = outcome === 'succeeded'
-    ? (task.schedule?.enabled ? 'todo' : 'done')
-    : outcome === 'failed' ? 'failed'
-      : task.status === 'running' ? 'todo' : task.status
-  return { ...task, status, updatedAt: now, executions }
+  return { ...task, status: settledStatus(task, outcome), updatedAt: now, executions }
 }
 
 /** A settled-execution summary string for the detail view. */

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

@@ -67,22 +67,43 @@ export function applyCreateTask(
     model: input.model ?? parent.model,
   }
   let task = createTask(effective, now, id)
-  // Arm the requested schedule (new-task dialog): only an enabled rule with
-  // a valid cron is applied; blank, invalid, or disabled requests leave the
-  // task unscheduled.
+  // Arm the requested schedule (new-task dialog). The Host wire gate already
+  // rejects a malformed enabled plan; this arm re-checks it so a direct caller
+  // (a test or an embedder) cannot persist an unusable rule either.
   const requested = input.schedule
-  if (requested?.enabled === true && requested.cron.trim() !== '' && isValidCron(requested.cron)) {
-    const cron = requested.cron.trim()
+  if (requested?.enabled === true) {
     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)
+    if (requested.mode === 'once') {
+      const at = requested.at
+      if (at === undefined || !Number.isInteger(at) || at <= now) {
+        return { task: undefined, tasks, error: 'invalid schedule instant' }
+      }
+      task = withSchedule(task, {
+        enabled: true,
+        mode: 'once',
+        at,
+        timeZone: requestedZone,
+        nextRunAt: at,
+        runCount: 0,
+      }, now)
+    } else {
+      const cron = (requested.cron ?? '').trim()
+      if (cron !== '' && isValidCron(cron)) {
+        const maxRuns = requested.maxRuns
+        if (maxRuns !== undefined && (!Number.isInteger(maxRuns) || maxRuns < 1)) {
+          return { task: undefined, tasks, error: 'invalid schedule run cap' }
+        }
+        const zone = requestedZone ?? hostTimeZone
+        const nextRunAt = nextRunAtMs(cron, now, zone)
+        if (nextRunAt !== undefined) {
+          task = withSchedule(task, { enabled: true, mode: 'cron', cron, maxRuns, timeZone: requestedZone, nextRunAt, runCount: 0 }, now)
+        }
+      }
     }
   }
   return { task, tasks: [...tasks, task] }