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

package/lib/types/client/TaskBoardSettingsCard.d.ts

@@ -18,6 +18,14 @@ export interface TaskBoardSettings {
     preventIdleSleep?: boolean;
     /** Subtask depth limit (1..3); 1 means a single level of subtasks. */
     maxSubtaskDepth?: number;
+    /** Roster-poll cadence in seconds while the board has work to reconcile. */
+    sessionPollSeconds?: number;
+    /**
+     * GLOBAL native /goal switch (default off): the master control over whether
+     * this board starts a run with dsh's built-in /goal at all. Frozen per
+     * execution.
+     */
+    goalRunEnabled?: boolean;
     /** Goal acceptance for this board's executions (default on). */
     goalVerification?: boolean;
     /** Judge model route for goal acceptance; blank inherits the host default. */
@@ -35,6 +43,10 @@ export interface TaskBoardSettingsCardState extends CardShell {
     preventIdleSleep: CardFieldState;
     /** Subtask depth limit field. */
     maxSubtaskDepth: CardFieldState;
+    /** Roster-poll cadence field. */
+    sessionPollSeconds: CardFieldState;
+    /** GLOBAL native /goal switch. */
+    goalRunEnabled: CardFieldState;
     /** Goal-acceptance switch. */
     goalVerification: CardFieldState;
     /** Judge model route field. */

package/lib/types/client/index.d.ts

@@ -88,11 +88,10 @@ declare module '@deepseek-ai/cordis' {
 }
 /**
  * Required services (fiber inject waiting — the runtime must be up first).
- * The generated remote faces are probed at use time instead of injected:
- * `remote.agentPresets` only registers on 0.1.2-alpha.2 hosts (the
- * api-remotes contribution), so a hard wait would pend the entry forever
- * on hosts below that cohort, which serve the same roster through the
- * connection RPC face.
+ * The generated remote namespaces are not all hard injects: `remote.session`
+ * is one, while `remote.agentPresets` is reached through a scoped inject at
+ * use time (see mountUi), because the namespace mounts with the official
+ * api-remotes assembly applied beside this entry rather than before it.
  */
 export declare const inject: string[];
 /**

package/lib/types/client/locales.d.ts

@@ -150,6 +150,7 @@ export declare const zh: {
     'detail.noSession': string;
     'detail.executionStarted': string;
     'detail.execution.initiator': string;
+    'detail.execution.external': string;
     'detail.executionEnded': string;
     'detail.result.succeeded': string;
     'detail.result.failed': string;
@@ -192,7 +193,34 @@ export declare const zh: {
     'detail.schedule.duration.hours': string;
     'detail.schedule.duration.minutes': string;
     'detail.schedule.duration.seconds': string;
+    'detail.schedule.mode': string;
+    'detail.schedule.mode.cron': string;
+    'detail.schedule.mode.once': string;
+    'detail.schedule.at': string;
+    'detail.schedule.atHint': string;
+    'detail.schedule.atInvalid': string;
+    'detail.schedule.plannedAt': string;
+    'detail.schedule.zoneOnceHint': string;
+    'detail.schedule.maxRuns': string;
+    'detail.schedule.maxRunsUnlimited': string;
+    'detail.schedule.maxRunsValue': string;
+    'detail.schedule.maxRunsCustom': string;
+    'detail.schedule.maxRunsInvalid': string;
+    'detail.schedule.runs': string;
+    'detail.schedule.runsUnlimited': string;
+    'detail.schedule.remaining': string;
+    'detail.schedule.cancel': string;
+    'detail.schedule.ended': string;
+    'detail.schedule.skipped': string;
+    'detail.schedule.stop.fired': string;
+    'detail.schedule.stop.limit': string;
+    'detail.schedule.stop.no-target': string;
+    'detail.schedule.stop.missed': string;
+    'detail.schedule.stop.busy': string;
+    'detail.schedule.stop.permission': string;
+    'detail.schedule.stop.launch-failed': string;
     'card.scheduled': string;
+    'card.scheduledOnce': string;
     'new.workspace': string;
     'new.agentPreset': string;
     'new.permission': string;
@@ -255,9 +283,16 @@ export declare const zh: {
     'settings.unsaved': string;
     'settings.saveFailed': string;
     'settings.invalidNumber': string;
+    'settings.sessionPollSeconds': string;
+    'settings.sessionPollSecondsHint': string;
     'settings.maxSubtaskDepth': string;
     'settings.maxSubtaskDepthHint': string;
     'settings.maxSubtaskDepthOption': string;
+    'settings.runBehaviorTitle': string;
+    'settings.runBehaviorCardHint': string;
+    'settings.goalRunGlobal': string;
+    'settings.goalRunGlobalHint': string;
+    'settings.goalRunGlobalDisabledTaskOption': string;
     'settings.goalVerificationTitle': string;
     'settings.goalVerification': string;
     'settings.goalVerificationCardHint': string;
@@ -287,6 +322,7 @@ export declare const zh: {
     'running.repairing': string;
     'running.verificationPassed': string;
     'running.verificationFailed': string;
+    'running.verificationInvalid': string;
     'verify.title': string;
     'verify.status.passed': string;
     'verify.status.failed': string;
@@ -294,6 +330,34 @@ export declare const zh: {
     'verify.status.verifying': string;
     'verify.status.pending': string;
     'verify.status.off': string;
+    'verify.status.invalid': string;
+    'verify.status.invalidHeld': string;
+    'verify.attemptInvalid': string;
+    'verify.invalidReason.missing-finding': string;
+    'verify.invalidReason.unlocatable-quote': string;
+    'verify.invalidReason.baseline-finding': string;
+    'verify.invalidReason.vacuous-finding': string;
+    'verify.invalidReason.insufficient-evidence': string;
+    'verify.invalidReason.unknown': string;
+    'verify.invalidCounts': string;
+    'verify.invalidDetail': string;
+    'verify.criterionFindings': string;
+    'verify.criterionFinding': string;
+    'verify.criterionFindingFull': string;
+    'verify.location.task': string;
+    'verify.location.trajectory': string;
+    'verify.location.workspace': string;
+    'verify.location.baseline': string;
+    'verify.location.unknown': string;
+    'verify.detailRemoved': string;
+    'verify.cleanup.cleaned': string;
+    'verify.cleanup.pending': string;
+    'verify.cleanup.failed': string;
+    'verify.cleanup.audit': string;
+    'verify.cleanup.stage.quality': string;
+    'verify.cleanup.stage.invalid': string;
+    'verify.cleanup.stage.exception': string;
+    'verify.cleanup.stage.budget': string;
     'verify.summary': string;
     'verify.criteria': string;
     'verify.criterion': string;
@@ -315,6 +379,7 @@ export declare const zh: {
     'verify.applicability.goalUnavailable': string;
     'verify.applicability.skipped': string;
     'verify.applicability.teamMember': string;
+    'verify.applicability.goalDisabled': string;
     'verify.effortFallback': string;
     'verify.thresholdValue': string;
     'detail.parent': string;

package/lib/types/client/plugin-card-seat.d.ts

@@ -78,6 +78,11 @@ export interface PluginCardSeat {
     label?: () => string;
     /** Locale namespace the card renders with. */
     locale: string;
+    /**
+     * Child slots this card declares and renders. Forwarded to whichever seat
+     * the host renders; absent for a card that declares none.
+     */
+    children?: Record<string, unknown>;
     /** Business-face factory of the registration. */
     inject?: () => object;
     /**

package/lib/types/client/schedule-zone.d.ts

@@ -1,3 +1,5 @@
+import { type ScheduleRule, type ScheduleStopReason } from '../core/tasks.ts';
+import { type TaskBoardKey } from './locales.ts';
 /** One selectable zone, in the order the picker shows it. */
 export interface ZoneChoice {
     /** Canonical IANA id, or `''` for the Host-zone entry. */
@@ -32,6 +34,54 @@ export declare function zoneChoices(hostTimeZone: string | undefined, storedTime
  * @returns localized relative wording.
  */
 export declare function relativeTimeLabel(targetMs: number, now: number): string;
+/**
+ * The `datetime-local` input value for an instant, read in an explicit zone:
+ * `YYYY-MM-DDTHH:mm`. Uses the shared engine's zone reader, so the editor
+ * shows the same wall clock the Host schedules by.
+ * @param epochMs - the instant to render.
+ * @param timeZone - zone to read it in; absent uses the Host zone.
+ * @returns the input value.
+ */
+export declare function zonedInputValue(epochMs: number, timeZone?: string): string;
+/**
+ * Parse a `datetime-local` input value back to an instant, read in an explicit
+ * zone. Returns undefined when the text is not a whole calendar wall clock or
+ * names one the zone skips (a spring-forward gap), so the editor can refuse an
+ * unusable instant instead of silently moving it.
+ * @param value - the input text.
+ * @param timeZone - zone to interpret it in; absent uses the Host zone.
+ * @returns the instant, or undefined when it is not a usable wall clock.
+ */
+export declare function parseZonedInput(value: string, timeZone?: string): number | undefined;
+/**
+ * The default instant a new one-shot editor opens on: the next whole hour,
+ * rendered in the zone the rule will be read in.
+ * @param now - reference instant.
+ * @param timeZone - zone the rule is read in.
+ * @returns the input value for a near-future default.
+ */
+export declare function defaultZonedInputValue(now: number, timeZone?: string): string;
+/**
+ * The editor's run-cap option for a stored cap: the two named presets, the
+ * unlimited entry, or a custom value the editor shows in its own field.
+ * @param maxRuns - the stored cap, when any.
+ * @returns the select option value.
+ */
+export declare function runCapOption(maxRuns: number | undefined): string;
+/** The locale key describing why a rule stopped or skipped an occurrence. */
+export declare function stopReasonKey(reason: ScheduleStopReason): TaskBoardKey;
+/**
+ * The run-budget line: how many scheduled executions the Host opened and how
+ * many remain. Derived from the counter and the cap rather than stored, so the
+ * display cannot drift from the ledger.
+ * @param rule - the schedule rule.
+ * @returns localized wording.
+ */
+export declare function budgetLabel(rule: ScheduleRule): string;
+/** The line describing a rule that stopped itself, or undefined while it may still fire. */
+export declare function endedLabel(rule: ScheduleRule): string | undefined;
+/** The line describing the last skipped occurrence, or undefined when none. */
+export declare function skippedLabel(rule: ScheduleRule): string | undefined;
 /**
  * The full next-run label: the absolute wall clock in the schedule's own zone,
  * plus the relative distance in parentheses. Showing both matters because a

package/lib/types/core/controller.d.ts

@@ -13,6 +13,7 @@
  */
 import type { TaskStore } from './store.ts';
 import { type NewTaskInput, type TaskRecord, type TaskStatus } from './tasks.ts';
+import { type SetSchedulePatch } from './use-cases/task-schedule.ts';
 import { type TaskUpdatePatch } from './use-cases/task-update.ts';
 import type { TaskBoardAction, TaskBoardEventPayload, TaskBoardParseDraft, TaskBoardParseRequest, TaskBoardSnapshot } from '../protocol.ts';
 import type { TaskBoardExtensionActionRequest, TaskBoardVisibilityPredicate } from './extension.ts';
@@ -111,7 +112,7 @@ export interface ExecutionOptionsSnapshot {
  * (revision/scheduler/power); a full snapshot also carries the deployment
  * constants the UI reads (session default permission, subtask depth).
  */
-export type HostMirror = Pick<TaskBoardSnapshot, 'revision' | 'scheduler' | 'power' | 'sessionDefaultPermission' | 'maxSubtaskDepth' | 'teamRunAvailable' | 'extensions'>;
+export type HostMirror = Pick<TaskBoardSnapshot, 'revision' | 'scheduler' | 'power' | 'sessionDefaultPermission' | 'maxSubtaskDepth' | 'teamRunAvailable' | 'goalRunEnabled' | 'extensions'>;
 /** Immutable controller snapshot for UI subscriptions. */
 export interface ControllerSnapshot {
     tasks: readonly TaskRecord[];
@@ -287,19 +288,17 @@ export declare class BoardController {
      */
     deleteTag(name: string): Promise<boolean>;
     /**
-     * Update a task's schedule rule. A blank or invalid cron expression is
-     * rejected (returns false, state untouched). When the rule ends up enabled
-     * the next run instant is computed immediately; a disabled rule carries no
-     * next-run instant. Delegates the domain transition to the schedule use case.
+     * Update a task's schedule rule. An unusable plan (blank or invalid cron, a
+     * one-shot with no future instant, a non-positive run cap) is rejected
+     * (returns false, state untouched). When the rule ends up enabled the next
+     * run instant is computed immediately — a one-shot's next instant IS its
+     * planned instant — and a disabled rule carries none. Delegates the domain
+     * transition to the schedule use case.
      * @param id - the task to schedule.
      * @param patch - fields to change (absent fields keep their current value).
-     * @returns true when applied, false when rejected (invalid cron / unknown task).
+     * @returns true when applied, false when rejected (unknown task / unusable plan).
      */
-    setSchedule(id: string, patch: {
-        enabled?: boolean;
-        cron?: string;
-        timeZone?: string | null;
-    }): boolean;
+    setSchedule(id: string, patch: SetSchedulePatch): boolean;
     /**
      * Legacy pure-controller seam retained for migration-focused tests. The
      * production browser never rolls schedules; the Host ledger owns them.

package/lib/types/core/poll-cadence.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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 declare const DEFAULT_SESSION_POLL_SECONDS = 5;
+/** Shortest accepted cadence: a faster poll only burns CPU on the Host. */
+export declare const SESSION_POLL_MIN_SECONDS = 1;
+/** Longest accepted cadence, five minutes. */
+export declare 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 declare function normalizeSessionPollSeconds(seconds: number | undefined): number;
+/**
+ * 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 declare function sessionPollMs(seconds: number | undefined): number;

package/lib/types/core/tasks.d.ts

@@ -34,8 +34,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. */
@@ -76,17 +91,69 @@ export declare const EXECUTION_HISTORY_LIMIT = 20;
  * cannot start a new run while one is still open.
  */
 export declare function retainRecentExecutions(executions: readonly ExecutionRecord[]): ExecutionRecord[];
+/**
+ * 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 declare const SCHEDULE_STOP_REASONS: readonly ScheduleStopReason[];
 /**
  * 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.
@@ -96,7 +163,51 @@ 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 declare function scheduleRunBudget(rule: ScheduleRule): number | undefined;
+/**
+ * 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 declare function scheduleExhausted(rule: ScheduleRule): boolean;
+/**
+ * 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 declare function schedulePlannedAt(rule: ScheduleRule): number | undefined;
 /**
  * Frozen context snapshot carried by a continuation card (issue #4): the
  * goal/progress/next text (already sanitized by the freeze gates) plus the
@@ -236,9 +347,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;
     /**
@@ -338,8 +451,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;
     /**
@@ -348,15 +461,21 @@ 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;
+        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
@@ -448,7 +567,8 @@ export declare function withStatus(task: TaskRecord, status: TaskStatus, now: nu
  * 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 declare function withSchedule(task: TaskRecord, patch: Partial<ScheduleRule>, now: number): TaskRecord;
 /**
@@ -461,6 +581,16 @@ export declare function startExecution(task: TaskRecord, now: number, executionI
     task: TaskRecord;
     execution: ExecutionRecord;
 };
+/**
+ * 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 declare function settledStatus(task: TaskRecord, outcome: ExecutionOutcome): TaskStatus;
 /**
  * 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

package/lib/types/core/use-cases/task-schedule.d.ts

@@ -1,23 +1,37 @@
-import { type TaskRecord } from '../tasks.ts';
+import { type ScheduleMode, type ScheduleStopReason, type TaskRecord } from '../tasks.ts';
 /** Fields the schedule use case may change on a rule. */
 export interface SetSchedulePatch {
     enabled?: boolean;
+    /** Which kind of plan to write; an absent key keeps the current mode. */
+    mode?: ScheduleMode;
+    /** 5-field cron expression of a recurring rule. */
     cron?: string;
-    /** IANA zone for the cron wall clock; `null` clears it back to the Host zone. */
+    /** Planned instant of a one-shot rule (ms epoch). */
+    at?: number;
+    /** IANA zone for the wall clock; `null` clears it back to the Host zone. */
     timeZone?: string | null;
+    /** Run cap of a recurring rule; `null` clears it back to unlimited. */
+    maxRuns?: number | null;
 }
 /** Result of arming/disarming a rule. */
 export interface SetScheduleResult {
     /** The next ledger; unchanged reference when rejected. */
     tasks: readonly TaskRecord[];
-    /** Whether the rule was applied (false on unknown task / invalid cron). */
+    /** Whether the rule was applied (false on unknown task / invalid plan). */
     applied: boolean;
 }
 /**
- * Set an on-board task's schedule rule. A blank or invalid cron, an unknown or
- * archived task, or an unusable zone is rejected (state untouched); an enabled
- * rule computes the next run instant immediately in the rule's own zone, a
- * disabled one carries no next-run instant.
+ * Set an on-board task's scheduling rule. An unknown or archived task, an
+ * unusable zone, a blank or invalid cron, a one-shot with no usable instant,
+ * a one-shot armed in the past, and a run cap that is not a positive integer
+ * are all rejected (state untouched). An enabled rule computes its next run
+ * instant immediately — a one-shot's next instant IS its planned instant — and
+ * a disabled rule carries none.
+ *
+ * Arming a rule that was not enabled, or switching its kind, starts a fresh
+ * budget: the run counter and any previous stop/skip record are cleared. Edits
+ * to a live rule (expression, zone, cap) keep the consumed count, so an
+ * already-spent budget can never silently reset and overrun.
  * @param tasks - current ledger.
  * @param id - the task to schedule.
  * @param patch - rule fields to change (absent fields keep their current value).
@@ -26,9 +40,8 @@ export interface SetScheduleResult {
  */
 export declare function applySetSchedule(tasks: readonly TaskRecord[], id: string, patch: SetSchedulePatch, now: number, hostTimeZone: string): SetScheduleResult;
 /**
- * Roll a task's schedule rule forward (scheduler callback): persist the next
- * due instant and the trigger instant. No-op for tasks without a rule (deleted
- * mid-tick, for example).
+ * Roll a task's schedule rule forward (legacy pure-controller seam): persist
+ * the next due instant and the trigger instant. No-op for tasks without a rule.
  * @param tasks - current ledger.
  * @param id - the task to roll forward.
  * @param nextRunAt - next due instant (may be undefined to clear).
@@ -36,3 +49,48 @@ export declare function applySetSchedule(tasks: readonly TaskRecord[], id: strin
  * @param now - clock instant (ms epoch).
  */
 export declare function applyScheduleNextRun(tasks: readonly TaskRecord[], id: string, nextRunAt: number | undefined, lastTriggeredAt: number | undefined, now: number): readonly TaskRecord[];
+/**
+ * The effect one due occurrence has on its rule, applied by the Host ledger.
+ */
+export interface ScheduleProgress {
+    /** Executions this occurrence actually opened (0 or 1), added to the counter. */
+    consumed: number;
+    /** Next due instant; absent stops the rule. */
+    nextRunAt?: number;
+    /** Trigger instant recorded as `lastTriggeredAt` (a consumed run only). */
+    lastTriggeredAt?: number;
+    /** Terminal reason when the rule stops itself (disarms it). */
+    endedReason?: ScheduleStopReason;
+    /** Why this occurrence produced no run, when it did not. */
+    skippedReason?: ScheduleStopReason;
+}
+/**
+ * Refund the one scheduled run an occurrence consumed before its launch failed
+ * without ever creating a session. Nothing ran, so the run budget is restored
+ * and the rule is left able to serve its next occurrence — a launch failure
+ * must never silently spend the user's limited budget.
+ *
+ * A recurring rule keeps its already-rolled-forward target; a fire that ended
+ * the rule at its cap (no target left) is restored and re-armed at the next
+ * occurrence, so a failed launch consumes nothing. A one-shot has no later
+ * occurrence, so it is left stopped with `launch-failed` and its run returned.
+ * A rule the user disabled in the meantime is not resurrected.
+ * @param tasks - current ledger.
+ * @param id - the task whose occurrence is being refunded.
+ * @param now - clock instant (ms epoch).
+ * @param hostTimeZone - zone a rule with no stored zone follows.
+ * @returns the next ledger.
+ */
+export declare function applyScheduleRefund(tasks: readonly TaskRecord[], id: string, now: number, hostTimeZone: string): readonly TaskRecord[];
+/**
+ * Record what a due occurrence did to a task's rule: advance the run counter
+ * by the executions it opened, set the next target (or stop the rule), and
+ * note a terminal reason or a skipped occurrence. Nothing is written for a
+ * task that has no rule or has been archived mid-tick.
+ * @param tasks - current ledger.
+ * @param id - the task whose rule fired.
+ * @param progress - the occurrence's effect.
+ * @param now - clock instant (ms epoch).
+ * @returns the next ledger.
+ */
+export declare function applyScheduleProgress(tasks: readonly TaskRecord[], id: string, progress: ScheduleProgress, now: number): readonly TaskRecord[];