@linxin666/dsh-client-ui-task-board 0.1.20 → 0.2.1

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

@@ -9,7 +9,7 @@
 import { type ReactNode } from 'react';
 import type { CardShell } from './settings-form.ts';
 /** Copy keys the card chrome itself reads; every consumer locale carries this shared vocabulary. */
-export declare const CARD_COPY_KEYS: readonly ['settings.collapse', 'settings.expand', 'settings.notExposed', 'settings.unsaved', 'settings.readOnly', 'settings.saveFailed', 'settings.discard', 'settings.save', 'settings.saving'];
+export declare const CARD_COPY_KEYS: readonly ["settings.collapse", "settings.expand", "settings.notExposed", "settings.unsaved", "settings.readOnly", "settings.saveFailed", "settings.discard", "settings.save", "settings.saving"];
 /** Copy key the card chrome itself reads. */
 export type CardCopyKey = (typeof CARD_COPY_KEYS)[number];
 /** Key domain for the plugin's own copy (inferred per consumer). */
@@ -39,6 +39,12 @@ export interface PluginSettingsCardProps<TKey extends string = string> {
      * already provides the selection.
      */
     alwaysOpen?: boolean;
+    /**
+     * Hide the save/discard footer: cards whose body applies its own changes
+     * immediately (an embedded external settings section) have no staged
+     * edits, so the footer would sit there permanently disabled.
+     */
+    hideFooter?: boolean;
     /** The plugin's controls. */
     children: ReactNode;
 }
@@ -82,6 +88,27 @@ export declare function ValueField(props: FieldProps & {
     /** Placeholder shown while the draft is empty. */
     placeholder?: string;
 }): import("react").JSX.Element;
+interface SelectOption {
+    value: string;
+    label: string;
+}
+/**
+ * The shared dual-mode select control. While an appearance skin is active it
+ * renders the legacy native `<select>` untouched, so element-level skin
+ * selectors keep working; under the default appearance it renders a
+ * self-drawn `role="listbox"` popup whose open/close is transition-animated.
+ * Staged cards reach it through BooleanField/ChoiceField; immediate-apply
+ * editors (the side-card prefs) bind it directly through onEdit.
+ * 双模式下拉框：皮肤激活时用原生 select，默认外观用自绘动画弹层。
+ */
+export declare function SelectField(props: {
+    id: string;
+    options: ReadonlyArray<SelectOption>;
+    value: string;
+    disabled: boolean;
+    invalid: boolean;
+    onEdit: (text: string) => void;
+}): import("react").JSX.Element;
 /** A staged boolean field: 继承 / 开 / 关. */
 export declare function BooleanField(props: FieldProps & {
     /** Copy for the inherit option. */
@@ -101,3 +128,4 @@ export declare function ChoiceField(props: FieldProps & {
         label: string;
     }>;
 }): import("react").JSX.Element;
+export {};

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

@@ -1,8 +1,7 @@
 /**
- * The task-board settings card: whether the board announces itself in every
- * agent's system prompt. Registers into the `settings.plugin.item` slot the
- * plugin-configuration section renders, bound to the `task-board` settings
- * namespace.
+ * Task-board settings for availability, agent announcement, and optional Host
+ * idle-sleep protection. Registers into the `web-ui.plugin.item` child slot
+ * the Web UI plugin group renders, bound to the `task-board` namespace.
  */
 import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
 import type { SettingsScope, SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client';
@@ -13,6 +12,8 @@ export interface TaskBoardSettings {
     enabled?: boolean;
     /** Whether the board announces itself in every agent's system prompt. */
     announceToAgent?: boolean;
+    /** Prevent host idle sleep while sessions run or schedules are armed. */
+    preventIdleSleep?: boolean;
 }
 /** What the task-board card renders. */
 export interface TaskBoardSettingsCardState extends CardShell {
@@ -20,6 +21,8 @@ export interface TaskBoardSettingsCardState extends CardShell {
     enabled: CardFieldState;
     /** System-prompt announcement flag. */
     announceToAgent: CardFieldState;
+    /** Idle-system-sleep protection flag. */
+    preventIdleSleep: CardFieldState;
 }
 /** The registration-side face the card's slot entry injects. */
 export interface TaskBoardSettingsCardFace extends CardActions {

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

@@ -1,9 +1,12 @@
 import type { TaskRecord } from '../../core/tasks.ts';
 /** Compact relative/absolute time label. */
-export declare function formatTime(ms: number): string;
+export declare function formatHostTimestamp(ms: number, timeZone?: string): string;
+export declare function formatTime(ms: number, timeZone?: string): string;
 /** One card in a column. */
-declare function TaskCardInner({ task, onClick }: {
+declare function TaskCardInner({ task, pending, timeZone, onClick }: {
     task: TaskRecord;
+    pending: boolean;
+    timeZone?: string;
     onClick: () => void;
 }): import("react").JSX.Element;
 /** Memoized card: re-renders only when the card's own task record changes. */

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

@@ -0,0 +1,18 @@
+import type { TaskRecord } from '../core/tasks.ts';
+import { type TaskBoardAction, type TaskBoardEventPayload, type TaskBoardSnapshot } from '../protocol.ts';
+export interface TaskBoardHostTransport {
+    bootstrap(legacy: readonly TaskRecord[]): Promise<TaskBoardSnapshot>;
+    state(): Promise<TaskBoardSnapshot>;
+    action(action: TaskBoardAction): Promise<TaskBoardSnapshot>;
+    subscribe(listener: (event?: TaskBoardEventPayload) => void): () => void;
+}
+export declare class HttpTaskBoardHostTransport implements TaskBoardHostTransport {
+    private readonly storage;
+    constructor(storage?: Pick<Storage, 'getItem' | 'setItem'> | undefined);
+    bootstrap(legacy: readonly TaskRecord[]): Promise<TaskBoardSnapshot>;
+    state(): Promise<TaskBoardSnapshot>;
+    action(action: TaskBoardAction): Promise<TaskBoardSnapshot>;
+    private post;
+    private request;
+    subscribe(listener: (event?: TaskBoardEventPayload) => void): () => void;
+}

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

@@ -24,8 +24,12 @@ export declare const zh: {
     'board.status.done': string;
     'board.status.failed': string;
     'board.runs': string;
+    'board.pending': string;
     'board.updated': string;
     'board.created': string;
+    'board.hostError': string;
+    'board.retryHost': string;
+    'board.hostMeta': string;
     'new.title': string;
     'new.titlePlaceholder': string;
     'new.description': string;
@@ -99,6 +103,12 @@ export declare const zh: {
     'settings.enabledHint': string;
     'settings.announceToAgent': string;
     'settings.announceToAgentHint': string;
+    'settings.preventIdleSleep': string;
+    'settings.preventIdleSleepHint': string;
+    'settings.powerStatus': string;
+    'settings.powerBoundary': string;
+    'settings.powerUnknown': string;
+    'settings.powerError': string;
     'settings.inherit': string;
     'settings.on': string;
     'settings.off': string;

package/lib/types/client/sidebar-entry-core.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Shared sidebar entry injection core.
+ *
+ * dsh's sidebar shell exposes no slot an external plugin can register into,
+ * so the entry row is injected between the shell's New Session button and the
+ * workspace browser. The injection self-heals: a MutationObserver watches the
+ * sidebar root and re-inserts the row whenever a React re-render displaces it
+ * (re-insertion happens in the same frame, before paint, so no flicker).
+ *
+ * The row is plain DOM (no React tree) so it can never disturb the shell's
+ * reconciliation; the view it toggles is a separate root owned by the caller.
+ *
+ * Packages receive this file as a generated copy via scripts/sync-shared.mjs;
+ * edit the shared source and re-run the sync instead of editing a copy.
+ */
+/** Per-package configuration for one sidebar entry row. */
+export interface SidebarEntryOptions {
+    /** Full attribute name identifying the injected row (idempotency key), e.g. 'data-dsh-ssh-entry'. */
+    rowAttribute: string;
+    /** CSS selector matching the injected row, e.g. '[data-dsh-ssh-entry]'. */
+    rowSelector: string;
+    /**
+     * L2 semantic-attribute plugin id (issue #506, enum table:
+     * skins/skin-center/contracts/semantic-attrs-v1.md). When set, the row also
+     * outputs data-dsh-plugin="<id>" and data-dsh-part="sidebar-entry"; unset
+     * leaves the row without semantic attributes.
+     */
+    plugin?: string;
+    /** Inline icon markup (matches the shell's 16px nav-icon look). */
+    icon: string;
+    /** CSS module class names for the row and its two spans (entry / entryIcon / entryLabel). */
+    css: Record<string, string>;
+    /** Localized row label (aria-label + visible text). */
+    label(): string;
+    /** Optional localized tooltip (title attribute). */
+    tooltip?(): string;
+    /** Click action (open/toggle the owning panel). */
+    onToggle(): void;
+    /** Family-block position: 'before' inserts ahead of sibling plugin rows, 'after' behind them. */
+    position: 'before' | 'after';
+    /**
+     * Selectors of the sibling plugin entry rows this package orders against
+     * (its own row included — the placement guard excludes a row that is
+     * already inside the root). Each package passes the same list it used
+     * before the consolidation so the rendered order stays stable.
+     */
+    familySelectors: readonly string[];
+    /** Optional active-state bridge; highlights the row while the panel is open. */
+    active?: {
+        subscribe(listener: () => void): () => void;
+        isOpen(): boolean;
+    };
+}
+/**
+ * Mount the sidebar entry, waiting for the shell to render and self-healing
+ * on later React re-renders.
+ * @param options - the row's attribute/icon/copy/action/ordering configuration.
+ * @returns disposer removing the entry and its observers.
+ */
+export declare function mountSidebarEntry(options: SidebarEntryOptions): () => void;

package/lib/types/client/sidebar-entry.d.ts

@@ -1,17 +1,15 @@
 /**
- * Sidebar entry injection.
+ * Sidebar entry injection — package-specific wiring over the shared core.
  *
  * dsh's sidebar shell exposes no slot an external plugin can register into
  * (`sidebar.workspaces` / `sidebar.settings` are single-occupant and already
- * taken), so — following the skin precedent of DOM-level extension — the
- * entry row is injected between the shell's New Session button and the
- * workspace browser. The injection self-heals: a MutationObserver watches the
- * sidebar root and re-inserts the row whenever a React re-render displaces it
- * (re-insertion happens in the same frame, before paint, so no flicker).
- *
- * The row is plain DOM (no React tree) so it can never disturb the shell's
- * reconciliation; the board view it toggles is a separate React root mounted
- * in the center column (see board-mount.ts).
+ * taken), so the entry row is injected between the shell's New Session button
+ * and the workspace browser. The DOM injection / self-healing / idempotency
+ * logic lives exactly once in shared/client/sidebar-entry-core.ts (synced
+ * copy); this wrapper supplies the task-board icon, copy, CSS module, and the
+ * board toggle. The row is plain DOM (no React tree); the board view it
+ * toggles is a separate React root mounted in the center column
+ * (see board-mount.ts).
  */
 import type { BoardController } from '../core/controller.ts';
 /** Stable data attribute identifying the injected entry row. */

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

@@ -1,10 +1,9 @@
 /**
  * Board controller: the single owner of task-ledger state and view state.
  *
- * It keeps the ledger in memory, persists every mutation through the
- * {@link TaskStore}, drives real executions through the
- * {@link ExecutionService}, and closes the board view whenever the user
- * navigates to a session (the sessions-list `current` selection changes).
+ * In production it projects the Host ledger and submits confirmed actions;
+ * the legacy store/execution seams remain for v1 migration tests. It also
+ * closes the board whenever the user navigates to a session.
  * Framework-free (structural runtime faces) so the whole orchestration is
  * unit-testable with fakes.
  *
@@ -13,10 +12,17 @@
  * owns only the orchestration seam (state, persistence, notify, execution,
  * navigation, reconciliation).
  */
-import { ExecutionService } from './execution.ts';
+import type { ExecutionService } from './execution.ts';
 import type { TaskStore } from './store.ts';
 import { type NewTaskInput, type TaskRecord, type TaskStatus } from './tasks.ts';
 import { type TaskUpdatePatch } from './use-cases/task-update.ts';
+import type { TaskBoardAction, TaskBoardEventPayload, TaskBoardSnapshot } from '../protocol.ts';
+export interface TaskBoardTransport {
+    bootstrap(legacy: readonly TaskRecord[]): Promise<TaskBoardSnapshot>;
+    state(): Promise<TaskBoardSnapshot>;
+    action(action: TaskBoardAction): Promise<TaskBoardSnapshot>;
+    subscribe(listener: (event?: TaskBoardEventPayload) => void): () => void;
+}
 /** The sessions face the controller needs for navigation awareness. */
 export interface SessionsControllerFace {
     list: {
@@ -31,7 +37,8 @@ export interface SessionsControllerFace {
 /** Controller dependencies (all swappable in tests). */
 export interface ControllerDeps {
     store: TaskStore;
-    exec: ExecutionService;
+    /** Legacy browser execution seam used only by isolated v1 tests. */
+    exec?: ExecutionService;
     sessions: SessionsControllerFace;
     /** Clock; defaults to Date.now. */
     now?: () => number;
@@ -39,6 +46,8 @@ export interface ControllerDeps {
     uuid?: () => string;
     /** Debounce (ms) for session-list-changed reconciles; defaults to 350. */
     reconcileDebounceMs?: number;
+    /** Host-authoritative transport; absent keeps the legacy in-memory test path. */
+    transport?: TaskBoardTransport;
 }
 /** One workspace option the execution-target pickers offer. */
 export interface ExecutionWorkspaceOption {
@@ -69,6 +78,9 @@ export interface ControllerSnapshot {
     selectedTaskId: string | undefined;
     /** Picker option sets (workspace list + agent-preset roster). */
     executionOptions: ExecutionOptionsSnapshot;
+    pendingTaskIds: readonly string[];
+    transportError?: string;
+    host?: Pick<TaskBoardSnapshot, 'revision' | 'scheduler' | 'power'>;
 }
 /** The selected task (resolved from the ledger), or undefined. */
 export declare function selectedTaskOf(snapshot: ControllerSnapshot): TaskRecord | undefined;
@@ -87,6 +99,12 @@ export declare class BoardController {
     private disposers;
     private readonly now;
     private readonly uuid;
+    private readonly pendingTaskIds;
+    private readonly taskQueues;
+    private transportError;
+    private hostState;
+    private remoteSubscribed;
+    private remoteInitialization;
     /** @param deps - store, execution service, and the sessions navigation face. */
     constructor(deps: ControllerDeps);
     /** Load the persisted ledger and start the navigation/status subscriptions. */
@@ -95,6 +113,10 @@ export declare class BoardController {
     dispose(): void;
     getSnapshot(): ControllerSnapshot;
     subscribe(fn: () => void): () => void;
+    /** Whether production mutations are confirmed by the Host transport. */
+    isHostBacked(): boolean;
+    /** Retry initial migration/state synchronization after an explicit Host error. */
+    retryHostSync(): Promise<boolean>;
     openBoard(): void;
     closeBoard(): void;
     toggleBoard(): void;
@@ -107,6 +129,8 @@ export declare class BoardController {
     openTask(id: string): void;
     closeTask(): void;
     createTask(input: NewTaskInput): TaskRecord | undefined;
+    /** Create through the Host and expose the task only after confirmation. */
+    createTaskConfirmed(input: NewTaskInput): Promise<TaskRecord | undefined>;
     updateTask(id: string, patch: TaskUpdatePatch): void;
     /**
      * Replace (a part of) the picker option sets the UI feeds (workspace list
@@ -138,18 +162,13 @@ export declare class BoardController {
         cron?: string;
     }): boolean;
     /**
-     * Roll a task's schedule forward (scheduler callback): persist the next due
-     * instant and the trigger instant of this run. No-op when the task has no
-     * schedule rule (it was deleted mid-tick, for example).
+     * Legacy pure-controller seam retained for migration-focused tests. The
+     * production browser never rolls schedules; the Host ledger owns them.
      */
     applyScheduleNextRun(id: string, nextRunAt: number | undefined, lastTriggeredAt: number | undefined): void;
     /**
-     * Reload the ledger from the persisted store without notifying subscribers.
-     * The scheduler calls this before every tick so a task deleted in another
-     * tab (or a stale in-memory copy) can never be fired from this tab: the
-     * fire decision and the subsequent roll-forward both run on the freshest
-     * persisted truth. Deliberately silent — same-origin external changes still
-     * reach subscribers through the storage-event subscription.
+     * Reload the legacy v1 store without notifying subscribers. Production v2
+     * reads Host snapshots instead; this remains only for isolated legacy tests.
      */
     reloadFromStore(): void;
     /**
@@ -186,5 +205,18 @@ export declare class BoardController {
     /** Settle tasks left 'running' whose sessions already finished. */
     private reconcileRunningTasks;
     private persistAndNotify;
+    private commitRemote;
+    private performRemote;
+    private initializeRemote;
+    private doInitializeRemote;
+    /**
+     * SSE frames carry revision/scheduler/power. When the revision matches the
+     * one already applied, apply the frame's scheduler/power in place and skip
+     * the full /state fetch; otherwise the 5 s heartbeat would re-clone and
+     * re-serialize the whole ledger per tab even while nothing changes.
+     */
+    private onRemoteEvent;
+    private refreshRemote;
+    private acceptRemote;
     private notify;
 }

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

@@ -34,7 +34,16 @@ 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 nothing matches within
- * 366 days (e.g. `0 0 30 2 *`).
+ * 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).
  */
 export declare function nextRunAtMs(expr: string, fromMs: number): number | undefined;

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

@@ -26,9 +26,8 @@ export interface ExecutionRecord {
     error: string | undefined;
 }
 /**
- * A scheduled-run rule attached to a task. The browser-side scheduler ticks
- * every minute and triggers the task when `nextRunAt` is due; the rule is
- * persisted with the task (localStorage), so scheduling survives refreshes.
+ * 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.
  */
 export interface ScheduleRule {
     /** Whether the schedule is armed. */
@@ -77,14 +76,15 @@ export interface TaskRecord {
     permission?: TaskPermission;
     /**
      * When the task was archived (ms epoch). Archived tasks keep their status
-     * and execution history but leave the main board; absent means on-board.
+     * and execution history, leave the main board, and cannot run until restored;
+     * absent means on-board.
      */
     archivedAt?: number;
 }
 /** Statuses a settled task may be archived from. */
 export declare const ARCHIVABLE_STATUSES: readonly TaskStatus[];
 /** Permission presets a task may pin on its execution session (the `/permission <id>` ids). */
-export declare const TASK_PERMISSIONS: readonly ['read-only', 'workspace-write', 'danger-full-access'];
+export declare const TASK_PERMISSIONS: readonly ["read-only", "workspace-write", "danger-full-access"];
 /** One permission preset id. */
 export type TaskPermission = typeof TASK_PERMISSIONS[number];
 /** Whether an unknown value is a known permission preset id. */
@@ -124,7 +124,7 @@ export declare const ALL_STATUSES: readonly TaskStatus[];
 /** Brand an unknown string as a status; undefined when it is not one. */
 export declare function isTaskStatus(value: unknown): value is TaskStatus;
 /** Whether a manual move target is allowed from the given status. */
-export declare function canMoveManually(_from: TaskStatus, to: TaskStatus): boolean;
+export declare function canMoveManually(from: TaskStatus, to: TaskStatus): boolean;
 /** Normalize one optional execution-target string: trim; blank collapses to undefined. */
 export declare function normalizeTargetId(value: string | undefined): string | undefined;
 /** Create a task from user input. */

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

@@ -1,8 +1,8 @@
 /**
  * Archive/restore task use case: move a settled (done/failed) task off the
- * main board and back. Purely a marker transition — the task keeps its
- * status, execution history and transcript references, so archiving never
- * loses traceability and restoring lands it in the exact column it left.
+ * main board and back. The task keeps its status, execution history, and
+ * transcript references, while archiving disarms any schedule so it cannot
+ * create more execution records until the user restores and re-enables it.
  */
 import type { TaskRecord } from '../tasks.ts';
 /** Result of an archive transition. */
@@ -15,7 +15,8 @@ export interface ArchiveTaskResult {
 /**
  * Archive one task: only settled statuses (done/failed) can be archived;
  * a running or not-yet-settled task stays on the board (its runner still
- * owns its lifecycle). Already-archived tasks are a no-op.
+ * owns its lifecycle). Archiving disarms a schedule; already-archived tasks
+ * are a no-op.
  */
 export declare function applyArchiveTask(tasks: readonly TaskRecord[], id: string, now: number): ArchiveTaskResult;
 /** Restore one task back onto the main board (clears the archive marker). */

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

@@ -12,9 +12,9 @@ export interface SetScheduleResult {
     applied: boolean;
 }
 /**
- * Set a task's schedule rule. A blank or invalid cron is rejected (state
- * untouched); an enabled rule computes the next run instant immediately, a
- * disabled or invalid one carries no next-run instant.
+ * Set an on-board task's schedule rule. A blank or invalid cron, or an
+ * archived task, is rejected (state untouched); an enabled rule computes the
+ * next run instant immediately, a disabled one carries no next-run instant.
  * @param tasks - current ledger.
  * @param id - the task to schedule.
  * @param patch - rule fields to change (absent fields keep their current value).

package/lib/types/dsh-home.d.ts

@@ -0,0 +1,16 @@
+/**
+ * DSH_HOME resolution shared by the plugin family's Host halves: the
+ * environment override wins, the platform home fallback follows. Mirrors
+ * what dsh-pet and dsh-liangshen each used to implement locally.
+ */
+/** Expand a leading ~ (or ~user) in a path, platform-style. */
+export declare function expandHome(path: string, home?: string): string;
+/**
+ * Resolve the DSH home directory.
+ * @param env - process environment to read DSH_HOME from.
+ * @param home - platform home directory fallback (test seam).
+ * @returns the absolute DSH home path.
+ */
+export declare function resolveDshHome(env?: NodeJS.ProcessEnv, home?: string): string;
+/** Resolve the DSH home directory from the live environment. */
+export declare function dshHome(): string;

package/lib/types/host-ledger.d.ts

@@ -0,0 +1,52 @@
+import { type ExecutionRecord, type TaskRecord } from './core/tasks.ts';
+import { type TaskBoardAction, type TaskBoardSchedulerSnapshot } from './protocol.ts';
+export interface LedgerState {
+    revision: number;
+    tasks: TaskRecord[];
+    scheduler: TaskBoardSchedulerSnapshot;
+}
+export interface OpenedRun {
+    task: TaskRecord;
+    execution: ExecutionRecord;
+}
+export declare class HostTaskLedger {
+    private readonly now;
+    private document;
+    private readonly listeners;
+    private readonly requestCache;
+    private readonly lockToken;
+    private lockFd;
+    readonly file: string;
+    readonly lockFile: string;
+    /** Small sidecar for the 30 s scheduler heartbeat (lastTickAt only). */
+    readonly schedulerFile: string;
+    constructor(dir?: string, now?: () => number);
+    /** Revision + scheduler without any task cloning; feeds the SSE event frame. */
+    summary(): {
+        revision: number;
+        scheduler: TaskBoardSchedulerSnapshot;
+    };
+    state(): LedgerState;
+    subscribe(listener: () => void): () => void;
+    dispose(): void;
+    applyRequest(requestId: string, action: TaskBoardAction): {
+        state: LedgerState;
+        run?: OpenedRun;
+    };
+    openScheduled(taskId: string, nextRunAt: number | undefined, triggeredAt: number): OpenedRun | undefined;
+    skipMissed(now: number): void;
+    setScheduler(patch: Partial<TaskBoardSchedulerSnapshot>): void;
+    attachSession(taskId: string, executionId: string, sessionId: string): void;
+    settle(taskId: string, executionId: string, outcome: 'succeeded' | 'failed' | 'cancelled', error?: string): void;
+    private apply;
+    private repairSchedules;
+    private reconcileInterruptedStarts;
+    private load;
+    private syncRecentRequests;
+    private readSchedulerSidecar;
+    /** Atomic write of the scheduler heartbeat sidecar (0600, tmp + rename + fsync). */
+    private writeSchedulerSidecar;
+    private commit;
+    private notify;
+    private acquireLock;
+}

package/lib/types/host-routes.d.ts

@@ -0,0 +1,26 @@
+import type { IncomingMessage } from 'node:http';
+import type { WebRoute } from '@deepseek-ai/dsh-host-webserver';
+import type { TaskBoardHostService } from './host-service.ts';
+/** Header replaced by an authenticated same-host reverse proxy. */
+export declare const TASK_BOARD_PROXY_TOKEN_HEADER = "x-dsh-task-board-proxy-token";
+/** Optional authenticated reverse-proxy access layered over the loopback default. */
+export interface TaskBoardRouteAccess {
+    trustedProxyHosts?: readonly string[];
+    proxyToken?: string;
+}
+interface ResolvedRouteAccess {
+    trustedProxyHosts: ReadonlySet<string>;
+    proxyToken?: string;
+}
+/**
+ * Task-board route fence. Direct desktop access uses the repository-wide
+ * loopback socket + Host guard and additionally requires a browser same-origin
+ * marker: a bare local curl without any browser signal cannot exercise the
+ * agent control plane (a forged Origin does pass the marker — it is a
+ * tripwire, the socket/Host/origin-equality checks carry the authority).
+ * Authenticated proxies must be explicitly allowlisted and replace the
+ * internal token header after their own authentication step.
+ */
+export declare function isTrustedTaskBoardRequest(req: IncomingMessage, access: ResolvedRouteAccess): boolean;
+export declare function makeTaskBoardRoutes(service: TaskBoardHostService, access?: TaskBoardRouteAccess): WebRoute[];
+export {};

package/lib/types/host-runner.d.ts

@@ -0,0 +1,41 @@
+import type { ApiProxy } from '@deepseek-ai/dsh-host-apiproxy';
+import type { TaskRecord } from './core/tasks.ts';
+/** One session-list row, extracted from the sessions.list RPC result. */
+export type SessionSummary = Extract<Awaited<ReturnType<ApiProxy['sessions']['list']>>['result'], {
+    ok: true;
+}>['value']['items'][number];
+export type ExecutionInspection = {
+    outcome: 'pending';
+} | {
+    outcome: 'succeeded';
+} | {
+    outcome: 'failed';
+    error: string;
+} | {
+    outcome: 'cancelled';
+    error: string;
+};
+/** A post-create launch failure that still identifies the session to the ledger. */
+export declare class SessionLaunchError extends Error {
+    readonly sessionId: string;
+    constructor(sessionId: string, cause: unknown);
+}
+export declare class HostExecutionRunner {
+    private readonly api;
+    constructor(api: ApiProxy);
+    launch(task: TaskRecord): Promise<string>;
+    listRunning(): Promise<{
+        known: true;
+        count: number;
+        items: SessionSummary[];
+    } | {
+        known: false;
+    }>;
+    /**
+     * Resolve one execution's outcome. The caller may pass the session list it
+     * already fetched this poll tick; otherwise inspect lists sessions itself.
+     * Sharing the list keeps a poll with E open executions at one list RPC
+     * instead of 1 + E.
+     */
+    inspect(sessionId: string, startedAt?: number, sessions?: readonly SessionSummary[]): Promise<ExecutionInspection>;
+}

package/lib/types/host-service.d.ts

@@ -0,0 +1,45 @@
+import type { ApiProxy } from '@deepseek-ai/dsh-host-apiproxy';
+import { HostTaskLedger } from './host-ledger.ts';
+import { HostExecutionRunner } from './host-runner.ts';
+import { PowerInhibitor } from './power-inhibitor.ts';
+import type { TaskBoardAction, TaskBoardEventPayload, TaskBoardSnapshot } from './protocol.ts';
+export declare class TaskBoardHostService {
+    readonly ledger: HostTaskLedger;
+    readonly runner: HostExecutionRunner;
+    readonly power: PowerInhibitor;
+    private readonly listeners;
+    private timers;
+    private lastScheduleTick;
+    private disposed;
+    private pollInFlight;
+    private tickInFlight;
+    private active;
+    private preventIdleSleep;
+    private lastPowerJson;
+    private readonly now;
+    constructor(api: ApiProxy, options?: {
+        ledger?: HostTaskLedger;
+        power?: PowerInhibitor;
+        now?: () => number;
+    });
+    start(): void;
+    setConfiguration(active: boolean, preventIdleSleep: boolean): void;
+    snapshot(): TaskBoardSnapshot;
+    /** SSE frame payload; deliberately skips the tasks deep-clone of {@link snapshot}. */
+    eventPayload(): TaskBoardEventPayload;
+    subscribe(listener: () => void): () => void;
+    apply(requestId: string, action: TaskBoardAction): TaskBoardSnapshot;
+    dispose(): void;
+    private launch;
+    private pollSessions;
+    /** Reuse the session list this poll already fetched: one list RPC per tick, not 1 + E. */
+    private reconcileExecutions;
+    private tickSchedule;
+    private armedSchedules;
+    private hasOpenExecutions;
+    private scheduleLaunch;
+    private schedulePoll;
+    private scheduleTick;
+    private syncPowerReasons;
+    private emit;
+}