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

package/lib/types/client/board/TaskForm.d.ts

@@ -4,7 +4,7 @@
  * NewTaskModal and the EditTaskModal. State stays in the owning modal; these
  * are controlled components.
  */
-import type { ReactNode } from 'react';
+import { type ReactNode } from 'react';
 import { type TaskTag } from '../../core/tasks.ts';
 /** Modal overlay: closes on backdrop press, submits through the form. */
 export declare function ModalShell({ ariaLabel, title, error, pending, submitLabel, onSubmit, onClose, secondaryAction, children, }: {
@@ -22,6 +22,24 @@ export declare function ModalShell({ ariaLabel, title, error, pending, submitLab
     };
     children: ReactNode;
 }): import("react").JSX.Element;
+/**
+ * One collapsible region of a task form (create/edit dialog UX): the form
+ * groups its configuration into a few regions instead of stacking every field
+ * in one long column, so a normal-sized dialog needs no scrollbar. A collapsed
+ * region keeps a one-line summary of the values it holds, so nothing is hidden
+ * without a trace; a region holding a blocking error is forced open by its
+ * owner (forceOpen) rather than reporting the error out of sight.
+ */
+export declare function CollapsibleSection({ title, summary, defaultOpen, forceOpen, children, }: {
+    title: string;
+    /** One-line value preview rendered only while the region is collapsed. */
+    summary?: string | undefined;
+    /** Whether the region starts expanded (the owner's default layout). */
+    defaultOpen?: boolean;
+    /** Open regardless of the stored state: an error inside must stay visible. */
+    forceOpen?: boolean;
+    children: ReactNode;
+}): import("react").JSX.Element;
 /** Title + description + prompt fields shared by the new and edit task forms. */
 export declare function TaskContentFields({ title, description, prompt, onTitleChange, onDescriptionChange, onPromptChange, }: {
     title: string;

package/lib/types/client/board/preset-label.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Display-only labels for the agent-preset roster, shared by the task form and
+ * the detail view.
+ *
+ * The deployment's four built-in presets (the `standard` / `ptc` / `minimal` /
+ * `cordis` rows the shipped web-app bundle declares) carry no display name in
+ * the registry roster, so a picker would list bare ids beside the user presets.
+ * The map below only supplies names for those four; any other id — a renamed
+ * built-in, a community preset, a user preset — falls back to the roster name
+ * and then to the id, so this table can never hide or mislabel a preset.
+ */
+import type { ExecutionPresetOption } from '../../core/controller.ts';
+/** Whether one roster row is a shipped built-in preset. */
+export declare function isBuiltinPreset(id: string): boolean;
+/** Display label of one preset row: built-in label, roster name, or raw id. */
+export declare function presetLabel(preset: Pick<ExecutionPresetOption, 'id' | 'name'>): string;
+/**
+ * Label of the empty ("inherit") choice: names the preset a run actually lands
+ * on when the card pins nothing, which is the deployment default the roster
+ * marks with `isDefault`.
+ */
+export declare function inheritPresetLabel(presets: readonly ExecutionPresetOption[]): string;

package/lib/types/client/host-api.d.ts

@@ -7,13 +7,36 @@ import { type TaskBoardAction, type TaskBoardEventPayload, type TaskBoardParseDr
  * "Unexpected token 'o', \"not found\" is not valid JSON" is what a missing
  * Host half looks like today.
  */
-export type HostApiFailure = 'not-mounted' | 'unauthorized' | 'locked' | 'rejected' | 'timeout' | 'unreachable' | 'unexpected';
+export type HostApiFailure = 
+/** The board's own routes are not registered and nothing explains why. */
+'not-mounted'
+/** Another live DSH process owns the ledger, so this instance registered no board routes (#1730). */
+ | 'ledger-locked'
+/** This row degraded during start for some other reason the family health route reports (#1730). */
+ | 'degraded' | 'unauthorized' | 'forbidden' | 'locked' | 'rejected' | 'timeout' | 'unreachable' | 'unexpected';
 /** Transport failure carrying a stable class next to its user-facing message. */
 export declare class HostApiError extends Error {
     readonly failure: HostApiFailure;
     readonly status?: number | undefined;
     constructor(failure: HostApiFailure, message: string, status?: number | undefined);
 }
+/**
+ * Name the real reason this board's routes are missing (issue #1730).
+ *
+ * The core webserver answers an unmounted route with a bare 404, which cannot
+ * distinguish "this deployment never loaded the plugin" from "this row
+ * degraded during start" — a second DSH process holding `ledger-v2.lock` is
+ * the case that matters, because the panel's advice ("restart the service")
+ * is then false: the lock belongs to the other process, and restarting cannot
+ * win it. The family health route knows the difference, so the 404 is
+ * disambiguated there before anything is shown.
+ * @param fallback - copy for the plain "routes are not there" failure, which
+ *   is route-specific (the board's state route and the AI-parse route phrase
+ *   their own absence); it is also what is shown when the ledger names nothing.
+ * @param fetchImpl - fetch implementation (injected for tests).
+ * @returns the HostApiError to throw for a missing board route.
+ */
+export declare function missingRouteFailure(fallback?: string, fetchImpl?: typeof fetch): Promise<HostApiError>;
 export interface TaskBoardHostTransport {
     bootstrap(legacy: readonly TaskRecord[]): Promise<TaskBoardSnapshot>;
     state(): Promise<TaskBoardSnapshot>;

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

@@ -9,7 +9,7 @@
  * plugin must not take the GUI down.
  */
 import type { Context as ClientContext } from '@deepseek-ai/cordis';
-import type { ConfigForm } from '@deepseek-ai/dsh-client-ui-settings/client';
+import type { ConfigForm, ConfigForms } from '@deepseek-ai/dsh-client-ui-settings/client';
 import { type TaskBoardSettings } from './TaskBoardSettingsCard.tsx';
 import { type TaskBoardKey } from './locales.ts';
 /** Domain-owned description of one settings namespace a family card binds. */
@@ -94,3 +94,17 @@ export declare function apply(ctx: ClientContext): void;
  * @returns the form the settings card reads and writes.
  */
 export declare function bindSettingsForm(ctx: ClientContext): ConfigForm<TaskBoardSettings>;
+/**
+ * The profile entry id this package's own row carries, for a page that serves
+ * no family binder.
+ *
+ * The shared describe mirror is the only local evidence of which row id this
+ * profile actually serves, but it answers asynchronously: at plugin activation
+ * it usually holds nothing yet. An unanswered mirror therefore binds the
+ * aggregate row id rather than guessing among the candidates, and the binding
+ * is re-resolved once the mirror answers — see
+ * {@link createServedEntryForm}, which owns that rebinding.
+ * @param forms - the shared configuration forms service.
+ * @returns the entry id to bind before the mirror answers.
+ */
+export declare function servedEntryId(forms: ConfigForms): string;

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

@@ -29,7 +29,10 @@ export declare const zh: {
     'board.created': string;
     'board.hostError': string;
     'board.hostError.notMounted': string;
+    'board.hostError.ledgerLocked': string;
+    'board.hostError.degraded': string;
     'board.hostError.unauthorized': string;
+    'board.hostError.forbidden': string;
     'board.hostError.locked': string;
     'board.hostError.timeout': string;
     'board.hostError.unreachable': string;
@@ -54,6 +57,19 @@ export declare const zh: {
     'new.aiParseFailed': string;
     'board.retryHost': string;
     'board.hostMeta': string;
+    'new.section.parse': string;
+    'new.section.content': string;
+    'new.section.labels': string;
+    'new.section.execution': string;
+    'new.section.run': string;
+    'new.section.handover': string;
+    'new.section.schedule': string;
+    'new.summary.none': string;
+    'new.summary.labelCount': string;
+    'new.summary.filled': string;
+    'new.summary.scheduleOff': string;
+    'new.summary.multiRound': string;
+    'new.summary.singleRound': string;
     'new.title': string;
     'new.titlePlaceholder': string;
     'new.description': string;
@@ -145,13 +161,31 @@ export declare const zh: {
     'detail.schedule.invalid': string;
     'detail.schedule.notScheduled': string;
     'detail.schedule.dueSoon': string;
+    'detail.schedule.timeZone': string;
+    'detail.schedule.timeZoneHost': string;
+    'detail.schedule.timeZoneHostUnknown': string;
+    'detail.schedule.timeZoneHint': string;
+    'detail.schedule.timeZoneSearch': string;
+    'detail.schedule.timeZoneNone': string;
+    'detail.schedule.nextRunOverdue': string;
+    'detail.schedule.duration.days': string;
+    'detail.schedule.duration.hours': string;
+    'detail.schedule.duration.minutes': string;
+    'detail.schedule.duration.seconds': string;
     'card.scheduled': string;
     'new.workspace': string;
-    'new.mode': string;
+    'new.agentPreset': string;
     'new.permission': string;
     'new.model': string;
     'exec.workspace.recent': string;
-    'exec.mode.default': string;
+    'exec.mode.inherit': string;
+    'exec.mode.inheritWith': string;
+    'exec.mode.builtinGroup': string;
+    'exec.mode.customGroup': string;
+    'preset.builtin.standard': string;
+    'preset.builtin.ptc': string;
+    'preset.builtin.minimal': string;
+    'preset.builtin.cordis': string;
     'exec.mode.defaultSuffix': string;
     'exec.mode.brokenSuffix': string;
     'exec.mode.removed': string;
@@ -167,6 +201,8 @@ export declare const zh: {
     'exec.teamRunHint': string;
     'exec.teamRunUnavailable': string;
     'exec.reuseSessionHint': string;
+    'exec.goalRun': string;
+    'exec.goalRunHint': string;
     'detail.executionSettings': string;
     'exec.hint': string;
     'settings.title': string;

package/lib/types/client/native-panel.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Native panel registration for the task board.
+ *
+ * The board is an official-style center-column panel, not a DOM takeover: it
+ * contributes a row into the sidebar shell's own global panel list
+ * (`sidebar.panellist`) and its page into the layout's keyed `main` slot. The
+ * shell then owns the row box, the label, the active highlight, the collapsed
+ * rail, the panel switch and the window-chrome interplay exactly as it does for
+ * the shipped Plugins and Schedule pages, so the board renders through the same
+ * container the desktop application's Plugins page uses.
+ *
+ * Both registrations go through `ctx.slots.inject`, which fires only once the
+ * owning shell entry has declared the seat: load order between this plugin and
+ * ui-layout / ui-sidebar therefore does not matter, and neither does a shell
+ * that cannot serve the seats (the callback simply never runs).
+ *
+ * @module @linxin666/dsh-client-ui-task-board/client
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+import { TASK_BOARD_PANEL_ID, type BoardController } from '../core/controller.ts';
+/** The panel id shared by the sidebar row and the main-slot occupant. */
+export { TASK_BOARD_PANEL_ID };
+/**
+ * The sidebar row glyph the shell asks for at its own size and active state.
+ * The shell owns the button, label, tooltip and rail geometry; this component
+ * draws only the glyph, like every other panel row.
+ *
+ * The glyph carries `data-dsh-panel-entry` because it is the only DOM the
+ * panel's own code owns inside that shell-owned row: the L2 contract (skins)
+ * resolves which row belongs to which plugin through it, since the shell
+ * stamps no per-entry hook of its own (see contracts/semantic-attrs-v1.md).
+ * @param props - the shell's icon share: square edge and selection state.
+ * @returns the decorative board glyph.
+ */
+export declare function TaskBoardPanelIcon({ size }: {
+    size: number;
+    active: boolean;
+}): React.ReactElement;
+/**
+ * The main-slot page. The layout mounts it only while the board is the selected
+ * panel, so the conversation keeps the center column untouched the rest of the
+ * time; the wrapper carries the pinned `data-dsh-taskboard-view` semantic
+ * anchor (L2 contract, skins) and the container query context the board's
+ * responsive rules read.
+ * @param props - the framework main-slot share plus this entry's injected face.
+ * @returns the board page.
+ */
+export declare function TaskBoardPanel({ controller }: {
+    controller: BoardController;
+}): React.ReactElement;
+/**
+ * Register the board's sidebar row and center-column page.
+ *
+ * Both seats are declared by shell plugins this package does not depend on at
+ * runtime, so each registration is wrapped in `ctx.slots.inject`: the callback
+ * runs only after the owning entry declares the seat, and a shell that never
+ * declares it leaves the board simply absent instead of failing boot.
+ * @param ctx - client root context (services: slots).
+ * @param controller - the board controller the page and the row drive.
+ * @returns disposer releasing both registrations.
+ */
+export declare function registerTaskBoardPanel(ctx: ClientContext, controller: BoardController): () => void;

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

@@ -0,0 +1,47 @@
+/** One selectable zone, in the order the picker shows it. */
+export interface ZoneChoice {
+    /** Canonical IANA id, or `''` for the Host-zone entry. */
+    id: string;
+    /** Display label. */
+    label: string;
+}
+/**
+ * Zones offered by the picker: the Host zone first (the default, and the entry
+ * a rule with no stored zone follows), then the runtime's own inventory.
+ *
+ * The Host entry is always present, even before the Host snapshot reports a
+ * zone: it is the entry that stores no zone, so dropping it would leave a rule
+ * unable to express "follow the Host" and would let the control silently
+ * display an unrelated zone.
+ *
+ * A stored zone the inventory does not list (a rule written on another machine
+ * or under a different ICU build) is appended, so opening the editor can never
+ * silently rewrite the rule's zone.
+ * @param hostTimeZone - zone the Host reported for this deployment, when known.
+ * @param storedTimeZone - zone the edited rule already stores, when any.
+ * @returns the de-duplicated choice list.
+ */
+export declare function zoneChoices(hostTimeZone: string | undefined, storedTimeZone?: string): ZoneChoice[];
+/**
+ * The relative half of a next-run label: how far away the instant is, or how
+ * far past it the board is running. `now` is passed in rather than sampled so
+ * callers can share one clock reading across a row, and tests stay
+ * deterministic.
+ * @param targetMs - the instant being described.
+ * @param now - the reference instant.
+ * @returns localized relative wording.
+ */
+export declare function relativeTimeLabel(targetMs: number, now: number): string;
+/**
+ * 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
+ * rule's zone can differ from the reader's, so the wall clock alone is
+ * ambiguous and the distance alone loses the actual moment.
+ * @param targetMs - the instant being described.
+ * @param timeZone - zone to render the absolute half in.
+ * @param formatAbsolute - formatter for the absolute half (keeps Intl caching in the caller).
+ * @param now - the reference instant.
+ * @param translate - translate function, bound so this module stays dependency-light.
+ * @returns the combined label.
+ */
+export declare function nextRunLabel(targetMs: number, timeZone: string | undefined, formatAbsolute: (ms: number, timeZone?: string) => string, now: number): string;

package/lib/types/client/settings-entry-form.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Family settings form bound to the profile entry id a Host actually serves.
+ *
+ * Under the 0.1.7 settings model a form is addressed by PROFILE ENTRY ID, while
+ * a family card knows only its own settings namespace. The family binder
+ * (`ctx.get('webUiSettings')`, published by dsh-web-settings) resolves one onto
+ * the other and is the preferred transport; this module is the fallback for a
+ * page that serves no binder — the group plugin is not installed, or its client
+ * half has not applied yet (the aggregate mounts its children in order, and a
+ * child still waiting on its own injects publishes nothing).
+ *
+ * The shared describe mirror is the only local evidence of which row id this
+ * profile serves, but it answers asynchronously: at plugin activation it usually
+ * holds nothing yet. A one-shot guess therefore cannot be right for every
+ * deployment, and the form is bound once per session:
+ *
+ * - binding the bare namespace made every save answer `No configurable plugin
+ *   entry "<namespace>"` on an aggregate install (the namespace is not an entry
+ *   id there), which the card reported as "the deployment did not accept these
+ *   values";
+ * - binding the aggregate row id would break a standalone install, whose row id
+ *   is the namespace or the package's own `ui-*` row.
+ *
+ * So the fallback starts on the most likely row and REBINDS the moment the
+ * mirror names one of this package's rows. Until the mirror answers, the form
+ * reports the binding it holds (usually `loading`), which the card renders as an
+ * unavailable form rather than a doomed one.
+ */
+import type { ConfigForm, ConfigForms } from '@deepseek-ai/dsh-client-ui-settings/client';
+/** Options of {@link createServedEntryForm}. */
+export interface ServedEntryFormOptions<T> {
+    /** The shared configuration forms service (`ctx.configForms`). */
+    forms: ConfigForms;
+    /**
+     * Profile entry ids this package's rows carry, most likely first: the
+     * aggregate's generated row, the package's own standalone row, then the bare
+     * namespace. The first is the fallback while the mirror has no answer; the
+     * last is the answer when the mirror serves none of them.
+     */
+    entryIds: readonly string[];
+}
+/**
+ * Create a settings form bound to the profile entry id this Host serves, and
+ * rebound whenever the shared describe mirror names a different one of this
+ * package's rows.
+ * @param options - the shared forms service and this package's candidate row ids.
+ * @returns a form delegating to the currently resolved entry's own form.
+ */
+export declare function createServedEntryForm<T>(options: ServedEntryFormOptions<T>): ConfigForm<T>;

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

@@ -43,6 +43,19 @@ export interface SessionsControllerFace {
     /** Subscribe to catalog changes; selection ownership rides the same snapshot. */
     subscribe(fn: () => void): () => void;
 }
+/** Stable id shared by the board's sidebar panel row and its main-slot page. */
+export declare const TASK_BOARD_PANEL_ID = "task-board";
+/**
+ * The layout's panel-navigation face. The board no longer owns the center
+ * column at the DOM level: selecting the panel is the layout's business, and
+ * this is the one call that asks for it (null returns to the conversation).
+ * Optional, so a composition without the layout service keeps the board's
+ * pure state transitions testable.
+ */
+export interface PanelNavigationFace {
+    /** Select the board panel, or null to hand the column back to the conversation. */
+    select(panelId: string | null): void;
+}
 /** Controller dependencies (all swappable in tests). */
 export interface ControllerDeps {
     store: TaskStore;
@@ -53,6 +66,8 @@ export interface ControllerDeps {
     uuid?: () => string;
     /** Host-authoritative transport; absent keeps the legacy in-memory test path. */
     transport?: TaskBoardTransport;
+    /** Layout panel selection; absent keeps the board state-only (tests, shell-less hosts). */
+    panel?: PanelNavigationFace;
 }
 /**
  * Register one host directory as a DSH project (workspace). Wired by the
@@ -149,9 +164,33 @@ export declare class BoardController {
     isHostBacked(): boolean;
     /** Retry initial migration/state synchronization after an explicit Host error. */
     retryHostSync(): Promise<boolean>;
+    /**
+     * Show the board. The layout owns which panel the center column renders, so
+     * the state flip and the panel selection travel together here; a composition
+     * with no layout face (tests, a shell-less host) still flips the state.
+     *
+     * The selection is requested AFTER the snapshot flips so a subscriber
+     * rendering against `boardOpen` never observes "open" while the shell still
+     * shows the conversation.
+     */
     openBoard(): void;
+    /**
+     * Return the center column to the conversation. The layout's own selection is
+     * the source of truth for what the column renders, so this asks for the
+     * conversation explicitly rather than only clearing local state.
+     */
     closeBoard(): void;
     toggleBoard(): void;
+    /**
+     * Reflect a panel selection that came from OUTSIDE this controller (the user
+     * clicked another sidebar row, or the layout dropped the panel id). Keeps
+     * `boardOpen` aligned with what the column actually shows without asking the
+     * layout to select anything back.
+     * @param panelId - the layout's current panel id, or null for the conversation.
+     */
+    syncPanelSelection(panelId: string | null): void;
+    /** Ask the layout to select a panel; a shell that serves no layout face is a no-op. */
+    private selectPanel;
     /**
      * Switch between the kanban columns and the archive view. Leaving the
      * archive view with an archived task still selected closes the selection —
@@ -223,6 +262,7 @@ export declare class BoardController {
     setSchedule(id: string, patch: {
         enabled?: boolean;
         cron?: string;
+        timeZone?: string | null;
     }): boolean;
     /**
      * Legacy pure-controller seam retained for migration-focused tests. The
@@ -259,8 +299,8 @@ export declare class BoardController {
      * (background navigation, the Host runner creating and selecting a fresh
      * execution session, settlement, other plugins), so closing on `current`
      * changes would evict the board without the user asking. The board closes
-     * only on explicit user navigation: a sidebar session/workspace row click
-     * (board-mount onClickSidebarRow) or the board's own actions
+     * only on explicit user navigation: selecting another panel (the layout owns
+     * selection, and `syncPanelSelection` follows it) or the board's own actions
      * (openSession / close). Keeping the hook preserves the subscription
      * contract for future listeners.
      */

package/lib/types/core/degraded-reason.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The family health ledger's degraded-record contract (issues #1528, #1730).
+ *
+ * A family plugin row that fails during apply is recorded by the dsh-web-all
+ * shell as a degraded record; the shell serves the ledger through its
+ * loopback-only `GET /api/dsh-web-all/degraded` route because the failed
+ * plugin could not register any route of its own — the task board whose ledger
+ * lock is held by another DSH process is exactly that case, and without this
+ * the panel could only report "the Host API is not mounted".
+ *
+ * Both halves define this shape: the shell WRITES it (packages/dsh-web-all,
+ * src/degraded.ts — the two packages have no import edge, one is bundled into
+ * the other's profile) and a plugin's browser half PARSES it. The edits move
+ * together.
+ */
+/** Where a degraded row failed: module import, plugin shape, or fiber start. */
+export type DegradedStage = 'import' | 'shape' | 'start';
+/** One degraded family row as the shell's health route serves it. */
+export interface DegradedRow {
+    /** Real plugin package name from the shell row config. */
+    plugin: string;
+    /** Where the failure happened. */
+    stage: DegradedStage;
+    /** The shell's one-line reason, for display. */
+    reason: string;
+}
+/**
+ * The one degraded record naming `plugin`, or undefined when that row is not
+ * degraded (or the payload does not come from the shell's own shape). A
+ * plugin may appear once: the shell keys the ledger by package name and
+ * refreshes the record on every new failure.
+ * @param body - parsed JSON body of the health route.
+ * @param plugin - the real plugin package name to look for.
+ * @returns the degraded row, or undefined when the ledger does not name it.
+ */
+export declare function degradedRowOf(body: unknown, plugin: string): DegradedRow | undefined;
+/**
+ * Extract the pid of the LIVE process a ledger-lock failure blames, when the
+ * reason identifies one. The task board's lock refusal is the one degraded
+ * reason that carries an owner the user can act on, so the panel renders the
+ * pid in its own sentence and adds the guidance that actually applies.
+ * @param reason - the shell's one-line failure reason.
+ * @returns the confirmed owner pid, or undefined when the reason names none or
+ *   warns that the PID may have been reused (its own text owns the recovery).
+ */
+export declare function ledgerOwnerPid(reason: string): number | undefined;

package/lib/types/core/package-name.d.ts

@@ -0,0 +1,9 @@
+/**
+ * npm identity of this plugin. The dsh-web-all degraded ledger is keyed by the
+ * real plugin package name of a family row, and this plugin's browser half
+ * must name its OWN row there to learn why its Host API is missing (issue
+ * #1730): the served bundle cannot derive the name, because a family row
+ * mounts the package from a versioned profile path. The host half spells the
+ * same name in its single-mount guard (src/index.ts); the two move together.
+ */
+export declare const TASK_BOARD_PACKAGE = "@linxin666/dsh-client-ui-task-board";

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

@@ -1,15 +1,36 @@
 /**
- * Minimal 5-field cron parsing and next-run computation for scheduled task
- * runs. Framework-free and dependency-free so the scheduler and controller
- * share one tiny pure module.
+ * Zone-aware 5-field cron parsing and next-run computation for scheduled task
+ * runs. Framework-free and dependency-free (Intl only) so the Host scheduler
+ * and the browser next-run preview share one tiny pure module.
  *
  * Grammar: five whitespace-separated fields, 分 时 日 月 周. Every field
  * supports the wildcard, step (wildcard or range + "/n"), single value,
  * inclusive range a-b, and comma lists mixing any of those. Ranges: minutes
  * 0-59, hours 0-23, days 1-31, months 1-12, weekdays 0-7 (0 and 7 both mean
- * Sunday). When both the day and weekday fields are restricted they combine
- * with OR semantics (standard cron). Invalid expressions parse to null and
- * are rejected by the UI/controller.
+ * Sunday). Invalid expressions parse to null and are rejected by the UI and
+ * the Host.
+ *
+ * Day semantics follow Vixie cron: a field is *starred* when its field text
+ * starts with `*`. When day-of-month and day-of-week are both restricted the
+ * fields combine with OR; otherwise they combine with AND. The distinction
+ * matters for a stepped star such as `*/2`, which still restricts the dates it
+ * matches, so `0 0 */2 * 1` means "the Mondays that fall on an even day of
+ * month" rather than "every even day, or every Monday".
+ *
+ * Time zone: every candidate wall clock is interpreted in an explicit IANA
+ * zone (the schedule's stored zone, or the Host zone when none is given).
+ * A wall clock that does not exist (spring-forward gap) is skipped, and an
+ * ambiguous wall clock (fall-back overlap) resolves to the earlier instant, so
+ * a repeated local minute fires exactly once. The Host-scheduler semantics are
+ * byte-identical to `@deepseek-ai/dsh-schedule`'s resolver, which was verified
+ * against it across twelve IANA zones (including 30-minute and 45-minute DST
+ * offsets and a date-line jump) and 300k decision instants.
+ *
+ * That upstream is on the experimental track and is NOT a dependency here (no
+ * import, no inject, no peer range), so a change to it fails no test. Re-run the
+ * differential check on any `dsh-schedule` release or cohort bump that moves it,
+ * and keep this comment honest; the re-verification trigger is recorded in
+ * [the owning Agent Note](../../../../.agents/notes/implemented/feature/2026-09-29-task-board-schedule-time-zone.md).
  */
 /** The parsed match sets of one cron expression. */
 export interface CronSchedule {
@@ -19,11 +40,61 @@ export interface CronSchedule {
     months: ReadonlySet<number>;
     /** Weekdays 0-6, 0 = Sunday (input 7 normalized to 0). */
     weekdays: ReadonlySet<number>;
-    /** Whether the day-of-month field was the literal '*' (unrestricted). */
-    dayWildcard: boolean;
-    /** Whether the weekday field was the literal '*' (unrestricted). */
-    weekdayWildcard: boolean;
+    /** Whether the day-of-month field text starts with `*` (Vixie starred). */
+    dayStarred: boolean;
+    /** Whether the weekday field text starts with `*` (Vixie starred). */
+    weekdayStarred: boolean;
+}
+/** Fallback zone when the process reports no usable IANA zone. */
+export declare const HOST_TIME_ZONE_FALLBACK = "UTC";
+/** One resolved wall-clock reading in some zone. */
+export interface ZonedParts {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
 }
+/**
+ * The wall-clock reading of one instant in an explicit zone. Reading through
+ * Intl (rather than the process `Date` accessors) is what makes the result
+ * independent of the Host's own TZ.
+ * @param timeZone - explicit IANA zone.
+ * @param epochMs - instant to read.
+ * @returns the zone-local calendar and clock fields.
+ */
+export declare function partsInZone(timeZone: string, epochMs: number): ZonedParts;
+/**
+ * Resolve a wall clock in an explicit zone to its instant.
+ *
+ * The offset is probed a day either side of the naive guess so both DST
+ * transitions are covered, then every candidate offset whose inverse maps back
+ * to the requested wall clock is kept. No survivor means the wall clock does
+ * not exist (a spring-forward gap); several means it is ambiguous (a fall-back
+ * overlap), and the earliest instant wins so the repeated clock is taken once.
+ * @param timeZone - explicit IANA zone.
+ * @param year - full calendar year.
+ * @param month - 1-12.
+ * @param day - day of month.
+ * @param hour - 0-23.
+ * @param minute - 0-59.
+ * @returns the instant in ms epoch, or undefined when the wall clock is skipped.
+ */
+export declare function zonedEpoch(timeZone: string, year: number, month: number, day: number, hour: number, minute: number): number | undefined;
+/**
+ * The Host process's IANA zone, used for schedules that store no zone of their
+ * own (a ledger written before zones were persisted).
+ * @returns a zone name Intl accepts, never empty.
+ */
+export declare function resolveHostTimeZone(): string;
+/**
+ * Whether a value names a zone this runtime can actually resolve. A stored
+ * zone is trusted only after it round-trips through Intl, so a typo or a zone
+ * that this ICU build does not know can never arm a schedule.
+ * @param value - candidate zone name.
+ * @returns true when the name is usable.
+ */
+export declare function isValidTimeZone(value: string): boolean;
 /**
  * Parse a 5-field cron expression.
  * @returns the match sets, or null when the expression is invalid.
@@ -32,18 +103,22 @@ export declare function parseCron(expr: string): CronSchedule | null;
 /** Whether the expression parses. */
 export declare function isValidCron(expr: string): boolean;
 /**
- * Compute the next matching instant after `fromMs` (ms epoch), in local time,
- * at minute granularity, strictly greater than `fromMs`. Returns the ms epoch
- * of the matching minute's start, or undefined when the calendar constraint
- * can never match (for example `0 0 30 2 *`). The five-year horizon includes
- * a full leap cycle, so a valid February 29 schedule remains reachable from
- * every non-leap year.
+ * Compute the next matching instant after `fromMs` strictly greater than it,
+ * interpreting the expression's wall clock in `timeZone` (the Host zone when
+ * omitted). Returns the ms epoch of the matching minute's start, or undefined
+ * when the calendar constraint can never match (for example `0 0 30 2 *`).
+ * The five-year horizon includes a full leap cycle, so a valid February 29
+ * schedule remains reachable from every non-leap year.
  *
  * Walks candidate year/month/day/hour/minute values straight from the parsed
  * field sets instead of scanning every minute: a sparse expression such as
  * `0 0 29 2 *` used to iterate ~1.5M wall-clock minutes before reaching the
- * next leap day. Wall-clock field construction + the final `matches` re-check
- * preserve the old minute scan's DST semantics exactly (nonexistent spring
- * minutes normalize forward and the repeated fall-back hour is never visited).
+ * next leap day. A candidate wall clock that the zone skips (spring-forward
+ * gap) is passed over, which is what makes the gap semantics fall out of the
+ * candidate walk rather than needing a separate rule.
+ * @param expr - 5-field cron expression.
+ * @param fromMs - exclusive lower bound, ms epoch.
+ * @param timeZone - explicit IANA zone; defaults to the Host zone.
+ * @returns the next trigger instant, or undefined when unreachable.
  */
-export declare function nextRunAtMs(expr: string, fromMs: number): number | undefined;
+export declare function nextRunAtMs(expr: string, fromMs: number, timeZone?: string): number | undefined;