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

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;
 }

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 `settings.plugin.item` slot the
+ * plugin-configuration section 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 TaskBoardSnapshot } from '../protocol.ts';
+export interface TaskBoardHostTransport {
+    bootstrap(legacy: readonly TaskRecord[]): Promise<TaskBoardSnapshot>;
+    state(): Promise<TaskBoardSnapshot>;
+    action(action: TaskBoardAction): Promise<TaskBoardSnapshot>;
+    subscribe(listener: () => 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: () => 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/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, TaskBoardSnapshot } from '../protocol.ts';
+export interface TaskBoardTransport {
+    bootstrap(legacy: readonly TaskRecord[]): Promise<TaskBoardSnapshot>;
+    state(): Promise<TaskBoardSnapshot>;
+    action(action: TaskBoardAction): Promise<TaskBoardSnapshot>;
+    subscribe(listener: () => 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,11 @@ export declare class BoardController {
     /** Settle tasks left 'running' whose sessions already finished. */
     private reconcileRunningTasks;
     private persistAndNotify;
+    private commitRemote;
+    private performRemote;
+    private initializeRemote;
+    private doInitializeRemote;
+    private refreshRemote;
+    private acceptRemote;
     private notify;
 }

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

@@ -34,7 +34,9 @@ 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.
  */
 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,42 @@
+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;
+    constructor(dir?: string, now?: () => number);
+    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 commit;
+    private notify;
+    private acquireLock;
+}

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

@@ -0,0 +1,24 @@
+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, so a bare local curl cannot exercise the agent control plane.
+ * 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,30 @@
+import type { ApiProxy } from '@deepseek-ai/dsh-host-apiproxy';
+import type { TaskRecord } from './core/tasks.ts';
+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;
+    } | {
+        known: false;
+    }>;
+    inspect(sessionId: string, startedAt?: number): Promise<ExecutionInspection>;
+}

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

@@ -0,0 +1,41 @@
+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, 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 readonly now;
+    constructor(api: ApiProxy, options?: {
+        ledger?: HostTaskLedger;
+        power?: PowerInhibitor;
+        now?: () => number;
+    });
+    start(): void;
+    setConfiguration(active: boolean, preventIdleSleep: boolean): void;
+    snapshot(): TaskBoardSnapshot;
+    subscribe(listener: () => void): () => void;
+    apply(requestId: string, action: TaskBoardAction): TaskBoardSnapshot;
+    dispose(): void;
+    private launch;
+    private pollSessions;
+    private reconcileExecutions;
+    private tickSchedule;
+    private armedSchedules;
+    private hasOpenExecutions;
+    private scheduleLaunch;
+    private schedulePoll;
+    private scheduleTick;
+    private syncPowerReasons;
+    private emit;
+}

package/lib/types/index.d.ts

@@ -1,20 +1,17 @@
 /**
  * Host loader entry for the task-board plugin.
  *
- * Everything the board does is browser work (DOM, localStorage, driving the
- * client runtime's session services over the wire), so the host half's main
- * behavior is a system-prompt section announcing the plugin to every agent.
- * The section registers while this plugin is in the host composition (mount /
- * DSH restart) and disappears when the plugin leaves it (unmount / restart),
- * so agents always know the board exists and how to cooperate with it. The
- * announcement can be turned off through the web settings plugin-configuration
- * surface (`announceToAgent`); the section then disappears live.
+ * The Host owns the v2 ledger, action API, cron scheduler, session runner,
+ * execution reconciliation, and optional idle-sleep inhibitor. The browser is
+ * a same-origin asynchronous view over that service.
  */
 import type { Context } from '@deepseek-ai/cordis';
 import z from 'schemastery';
+/** Default environment variable holding the authenticated proxy token. */
+export declare const DEFAULT_PROXY_TOKEN_ENV = "DSH_TASK_BOARD_PROXY_TOKEN";
 export declare const inject: string[];
 /** Model-facing announcement: plugin presence, capabilities, and limits. */
-export declare const TASK_BOARD_GUIDANCE = "\u672C\u673A\u5DF2\u5B89\u88C5 dsh-task-board \u63D2\u4EF6\uFF08DSH Web GUI \u7684\u4EFB\u52A1\u770B\u677F\uFF09\uFF1A\u4FA7\u8FB9\u680F\u300C\u4EFB\u52A1\u770B\u677F\u300D\u5165\u53E3\uFF1B\u5728 dsh-web-ui \u63D2\u4EF6\u5168\u5BB6\u6876\u4ED3\u5E93\uFF08packages/dsh-task-board\uFF09\u7EDF\u4E00\u7EF4\u62A4\uFF0C\u7ECF\u805A\u5408\u5305 web-ui-all \u4E00\u952E\u5B89\u88C5\u3002\u80FD\u529B\uFF1A\u591A\u5217\u770B\u677F\u7BA1\u7406\u4EFB\u52A1\uFF1B\u4EFB\u52A1\u53EF\u771F\u5B9E\u6267\u884C\uFF08\u9A71\u52A8 agent \u4F1A\u8BDD\uFF09\uFF1B\u4EFB\u52A1\u53EF\u9489\u4F4F\u6267\u884C\u76EE\u6807\u2014\u2014\u5DE5\u4F5C\u533A / \u6A21\u5F0F\uFF08agent \u9884\u8BBE\uFF09/ \u6743\u9650\uFF08read-only / workspace-write / danger-full-access\uFF09\uFF0C\u7F3A\u7701\u7528\u8FD0\u884C\u65F6\u9ED8\u8BA4\uFF1B\u4EFB\u52A1\u652F\u6301 5 \u6BB5 cron \u5B9A\u65F6\u6267\u884C\uFF08\u5982 0 23 * * *\uFF09\uFF1B\u6570\u636E\u5B58\u6D4F\u89C8\u5668 localStorage\uFF08\u952E dsh.taskBoard.v1\uFF09\u3002\u9650\u5236\uFF1A\u5B9A\u65F6\u8C03\u5EA6\u5728\u6D4F\u89C8\u5668\u7AEF\uFF0C\u9700 GUI \u6807\u7B7E\u9875\u6253\u5F00\uFF0C\u9519\u8FC7\u5373\u8DF3\u8FC7\uFF1B\u6267\u884C\u6D88\u8017 API \u989D\u5EA6\u3002\u7528\u6237\u63D0\u5230\u300C\u4EFB\u52A1\u770B\u677F / \u770B\u677F / \u5B9A\u65F6\u4EFB\u52A1\u300D\u65F6\u5373\u6307\u672C\u63D2\u4EF6\uFF0C\u8BF7\u636E\u6B64\u534F\u4F5C\u3002";
+export declare const TASK_BOARD_GUIDANCE = "\u672C\u673A\u5DF2\u5B89\u88C5 dsh-task-board \u63D2\u4EF6\uFF08DSH Web GUI \u7684\u4EFB\u52A1\u770B\u677F\uFF09\uFF1A\u4FA7\u8FB9\u680F\u300C\u4EFB\u52A1\u770B\u677F\u300D\u5165\u53E3\uFF1B\u5728 dsh-web-ui \u63D2\u4EF6\u5168\u5BB6\u6876\u4ED3\u5E93\uFF08packages/dsh-task-board\uFF09\u7EDF\u4E00\u7EF4\u62A4\uFF0C\u7ECF\u805A\u5408\u5305 web-ui-all \u4E00\u952E\u5B89\u88C5\u3002\u80FD\u529B\uFF1A\u591A\u5217\u770B\u677F\u7BA1\u7406\u4EFB\u52A1\uFF1BHost \u6743\u5A01\u8D26\u672C\uFF1B\u5173\u95ED\u6D4F\u89C8\u5668\u540E\u4ECD\u7531 Host \u6267\u884C\u548C\u7ED3\u7B97\uFF1B\u4EFB\u52A1\u53EF\u9489\u4F4F\u5DE5\u4F5C\u533A\u3001agent \u9884\u8BBE\u548C\u6743\u9650\uFF1B\u652F\u6301 Host \u672C\u5730\u65F6\u533A\u7684 5 \u6BB5 cron\uFF0C\u9519\u8FC7\u7684\u89E6\u53D1\u70B9\u4E0D\u8865\u8DD1\uFF1B\u53EF\u9009\u4E14\u9ED8\u8BA4\u5173\u95ED\u7684\u7A7A\u95F2\u7CFB\u7EDF\u7761\u7720\u4FDD\u62A4\u5141\u8BB8\u5C4F\u5E55\u7184\u706D\uFF0C\u4F46\u4E0D\u627F\u8BFA\u62E6\u622A\u5408\u76D6\u3001\u624B\u52A8\u7761\u7720\u3001\u4F11\u7720\u3001\u5173\u673A\u6216\u5524\u9192\u5DF2\u7761\u7720\u673A\u5668\u3002\u6267\u884C\u6D88\u8017 API \u989D\u5EA6\u3002\u7528\u6237\u63D0\u5230\u300C\u4EFB\u52A1\u770B\u677F / \u770B\u677F / \u5B9A\u65F6\u4EFB\u52A1\u300D\u65F6\u5373\u6307\u672C\u63D2\u4EF6\uFF0C\u8BF7\u636E\u6B64\u534F\u4F5C\u3002";
 /**
  * Settings namespace of the board's announcement capability — the section the
  * web settings surface edits. Spelled here rather than imported: the browser
@@ -31,8 +28,19 @@ export interface Config {
     announceToAgent?: boolean;
     /** Master switch for the plugin (browser half + host announcement). */
     enabled?: boolean;
+    /** Prevent idle system sleep while sessions run or schedules are armed. */
+    preventIdleSleep?: boolean;
+    /** Canonical reverse-proxy Host authorities admitted with a server-side token. */
+    trustedProxyHosts?: string[];
+    /** Environment variable whose value the authenticated proxy injects upstream. */
+    proxyTokenEnv?: string;
 }
 export declare const Config: z<Config>;
+/** Resolve proxy access without ever placing the token value in plugin config. */
+export declare function resolveProxyAccess(config: Config | undefined, env?: NodeJS.ProcessEnv): {
+    trustedProxyHosts: string[];
+    proxyToken?: string;
+};
 /**
  * Register the board's announcement section, gated on the composition entry's
  * `announceToAgent` (and the live settings value once the web settings

package/lib/types/loopback.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Loopback trust fence shared by the host route families: socket address,
+ * Host header, and browser same-origin markers. 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.
+ *
+ * Semantics: RFC 5735 IPv4 127/8, ::1, IPv4-mapped ::ffff:127/8 (matching the
+ * remote-web-ui gate), localhost hostnames, plus the browser same-origin
+ * markers (sec-fetch-site and Origin) for the request-level fence.
+ * @module dsh-web-ui-shared/host/loopback
+ */
+import type { IncomingMessage } from 'node:http';
+/** IPv4 127/8 predicate (four decimal octets, first == 127). */
+export declare function isIPv4Loopback(v4: string): boolean;
+/** Whether a socket remote address names the loopback range (127/8, ::1, IPv4-mapped). */
+export declare function isLoopbackAddress(address: string | undefined): boolean;
+/** Whether a normalized URL hostname names the loopback authority (localhost, [::1], 127/8). */
+export declare function isLoopbackHostname(hostname: string): boolean;
+/**
+ * Request-level trust fence: a loopback socket address AND a loopback Host
+ * header, plus browser same-origin markers. The socket address is
+ * authoritative; X-Forwarded-For is never trusted.
+ */
+export declare function isLoopbackRequest(request: IncomingMessage): boolean;

package/lib/types/power-inhibitor.d.ts

@@ -0,0 +1,73 @@
+import { type ChildProcess, type SpawnSyncReturns } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import type { TaskBoardPowerSnapshot } from './protocol.ts';
+declare const WINDOWS_HELPER: string;
+declare const LINUX_HELPER: string;
+declare const LINUX_INHIBIT_PATHS: readonly ["/usr/bin/systemd-inhibit", "/bin/systemd-inhibit"];
+export interface PowerReasons {
+    runningSessions: number;
+    armedSchedules: number;
+    sessionStateKnown: boolean;
+}
+export interface SpawnOptions {
+    shell: false;
+    windowsHide: boolean;
+    stdio: ['pipe', 'pipe', 'pipe'] | ['ignore', 'ignore', 'ignore'];
+}
+export type SpawnLike = (file: string, args: readonly string[], options: SpawnOptions) => ChildProcess;
+export type SpawnSyncLike = (file: string, args: readonly string[], options: {
+    stdio: 'ignore';
+    timeout: number;
+    windowsHide: boolean;
+}) => Pick<SpawnSyncReturns<Buffer>, 'status' | 'error'>;
+export interface PowerInhibitorOptions {
+    platform?: NodeJS.Platform;
+    pid?: number;
+    env?: NodeJS.ProcessEnv;
+    spawn?: SpawnLike;
+    spawnSync?: SpawnSyncLike;
+    exists?: typeof existsSync;
+    execPath?: string;
+    setTimeout?: typeof globalThis.setTimeout;
+    clearTimeout?: typeof globalThis.clearTimeout;
+}
+export declare class PowerInhibitor {
+    private readonly listeners;
+    private enabled;
+    private reasons;
+    private phase;
+    private child;
+    private retry;
+    private retryReset;
+    private retryIndex;
+    private lastError;
+    private stopping;
+    private readonly platform;
+    private readonly pid;
+    private readonly env;
+    private readonly spawn;
+    private readonly spawnSync;
+    private readonly exists;
+    private readonly execPath;
+    private readonly timer;
+    private readonly clearTimer;
+    private linuxProbe;
+    constructor(options?: PowerInhibitorOptions);
+    setEnabled(enabled: boolean): void;
+    updateReasons(reasons: PowerReasons): void;
+    subscribe(listener: () => void): () => void;
+    snapshot(): TaskBoardPowerSnapshot;
+    dispose(): void;
+    private desired;
+    private sync;
+    private acquire;
+    private markReady;
+    private fail;
+    private release;
+    private clearRetryReset;
+    private windowsPowerShell;
+    private linuxSystemdInhibit;
+    private spawnCommand;
+    private emit;
+}
+export { LINUX_HELPER, LINUX_INHIBIT_PATHS, WINDOWS_HELPER };