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

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

@@ -1,10 +1,12 @@
 import type { TypertGateway } from '@deepseek-ai/dsh-api-gateway';
 import { HostTaskLedger } from './host-ledger.ts';
-import { HostExecutionRunner, type SessionCommandDispatcher, type TaskBoardWorkspaceRegistry } from './host-runner.ts';
+import { HostExecutionRunner, type GatewayPeer, type SessionCommandDispatcher, type TaskBoardWorkspaceRegistry } from './host-runner.ts';
 import { PowerInhibitor } from './power-inhibitor.ts';
 import { type TaskBoardAction, type TaskBoardEventPayload, type TaskBoardSnapshot } from './protocol.ts';
+import type { CardDefaults } from './core/card-defaults.ts';
 import { TaskBoardExtensionRegistry } from './host/extension-registry.ts';
 import type { TaskBoardExtension } from './core/extension.ts';
+import { type ScheduleMode } from './core/tasks.ts';
 import { type ModelCatalogView, type VerificationContract, type VerificationSettings } from './core/verification.ts';
 import type { TaskPermission } from './core/handover.ts';
 /** One teammate the Host asks the Agent Teams service to spawn for a team run. */
@@ -34,6 +36,30 @@ export interface TeamSpawnResult {
 export interface TaskBoardTeamDispatcher {
     spawn(input: TeamSpawnInput): Promise<TeamSpawnResult>;
 }
+/**
+ * Why an enforced goal execution settled failed while its acceptance DID run:
+ * attempts were recorded and none of them passed. The judge answered about the
+ * work and the work did not pass.
+ */
+export declare const NO_MATCHING_PASS_VERIFICATION_REASON = "goal \u9A8C\u6536\uFF1A\u672C\u6B21\u6267\u884C\u6CA1\u6709\u5339\u914D\u7684\u9A8C\u6536\u901A\u8FC7\u8BB0\u5F55\uFF08\u9A8C\u6536\u672A\u8FD0\u884C\u3001\u672A\u901A\u8FC7\u6216\u62A5\u544A\u6765\u81EA\u5176\u4ED6\u6267\u884C\uFF09\uFF0C\u6309\u672A\u9A8C\u6536\u5224\u5931\u8D25\u3002";
+/**
+ * Why an enforced goal execution settled failed with ZERO acceptance records:
+ * the gate was never opened, so the judge never ran and nothing was ever judged
+ * (issue #1837). The root cause is a session that declared completion in prose
+ * instead of calling `update_goal(action: complete)` — a tool-adherence problem,
+ * NOT a quality verdict on the delivery — so this reason says so and keeps the
+ * two investigation directions apart.
+ */
+export declare const NEVER_INVOKED_VERIFICATION_REASON = "goal \u9A8C\u6536\u672A\u89E6\u53D1\uFF1A\u672C\u6B21\u6267\u884C\u6CA1\u6709\u4EFB\u4F55\u9A8C\u6536\u8BB0\u5F55\uFF0C\u9A8C\u6536\u95E8\u4ECE\u672A\u6253\u5F00\u2014\u2014\u6267\u884C\u4F1A\u8BDD\u6CA1\u6709\u8C03\u7528 update_goal(action: complete) \u6765\u5B8C\u6210\u76EE\u6807\uFF08\u5E38\u89C1\u4E8E\u53EA\u5728\u56DE\u590D\u91CC\u5BA3\u544A\u5B8C\u6210\uFF09\u3002\u8FD9\u4E0D\u662F\u8D28\u91CF\u5224\u8D1F\uFF1A\u4EA4\u4ED8\u4ECE\u672A\u88AB\u88C1\u5224\u8BC4\u4F30\u3002";
+/**
+ * Why an enforced goal execution settled failed while its ONLY acceptance
+ * records are INVALID: the judge answered but could not locate its own
+ * rejection, so the board stopped calling it. This is NOT an evidence-backed
+ * quality veto — the requirement is explicit that such a run must not be
+ * described as one — but the execution still has no matching pass, so it ends
+ * for lack of one, and the reason names that precisely.
+ */
+export declare const INVALID_ONLY_VERIFICATION_REASON = "goal \u9A8C\u6536\u65E0\u6548\uFF1A\u672C\u6B21\u6267\u884C\u53EA\u8BB0\u5F55\u4E86\u65E0\u6548\u9A8C\u6536\uFF08\u88C1\u5224\u672A\u80FD\u7ED9\u51FA\u4E0E\u4EFB\u52A1\u8981\u6C42\u5BF9\u5E94\u3001\u4E14\u53EF\u5B9A\u4F4D\u5230\u672C\u6B21\u8BC1\u636E\u7684\u5426\u51B3\u4F9D\u636E\uFF09\uFF0C\u770B\u677F\u5DF2\u505C\u6B62\u8C03\u7528\u88C1\u5224\u3002\u8FD9**\u4E0D\u662F**\u6709\u8BC1\u636E\u7684\u8D28\u91CF\u5224\u8D1F\uFF1A\u9A8C\u6536\u672C\u8EAB\u4E0D\u53EF\u7528\uFF0C\u672C\u6B21\u8FD0\u884C\u56E0\u6CA1\u6709\u5339\u914D\u7684\u901A\u8FC7\u8BB0\u5F55\u800C\u7ED3\u675F\u3002\u8BF7\u68C0\u67E5\u9A8C\u6536\u73AF\u5883\u4E0E\u8BC1\u636E\u53EF\u89C1\u6027\uFF0C\u6216\u7528 task_board_manage(action=reset-verification) \u6E05\u9664\u8BB0\u5F55\u7684\u65E0\u6548\u9A8C\u6536\u540E\u91CD\u65B0\u5B8C\u6210\u76EE\u6807\u3002";
 /**
  * Provenance of one cron-triggered cascade: when the rule fired and the zone
  * its wall clock was read in. Passed into every launched prompt of that run so
@@ -42,7 +68,10 @@ export interface TaskBoardTeamDispatcher {
 export interface ScheduledRunContext {
     triggeredAt: number;
     timeZone: string;
-    cron: string;
+    /** Whether this fire came from a recurring rule or a single planned instant. */
+    mode: ScheduleMode;
+    /** Cron expression of a recurring rule; absent on a one-shot. */
+    cron?: string;
 }
 /**
  * The native timer face the Host arms through. The cordis `timer` service
@@ -62,6 +91,12 @@ export declare class TaskBoardHostService {
     private readonly listeners;
     /** The one recurring timer: the session-roster poll. */
     private pollTimer;
+    /** Cadence of the roster poll, in seconds (a settings field; see the config schema). */
+    private sessionPollSeconds;
+    /** Pending delay that follows a failed poll pass, if one is armed. */
+    private pollBackoffTimer;
+    /** Consecutive failed poll passes; doubles the next retry delay. */
+    private consecutivePollFailures;
     /** The armed schedule timer, if a trigger is pending. */
     private scheduleTimer;
     /** The instant the armed schedule timer targets (ms epoch), for resume detection. */
@@ -70,12 +105,11 @@ export declare class TaskBoardHostService {
     private pollInFlight;
     private active;
     /**
-     * Ids the last roster poll saw as present and idle; undefined while the
-     * roster is unknown. Session reuse (issue #1419) requires this positive
-     * evidence, so a launch before the first successful poll mints a fresh
-     * conversation instead of prompting into a session it cannot see.
+     * Admission control for the session-creating half of a run: one board action
+     * opens a whole subtree, and this is what keeps the Host from asking DSH for
+     * every member's session at once (see {@link LaunchAdmissionQueue}).
      */
-    private idleSessionIds;
+    private readonly launches;
     /**
      * Consecutive unreadable-history polls per open execution (see
      * {@link noteUnreadableInspection}). Cleared as soon as an inspection
@@ -87,6 +121,16 @@ export declare class TaskBoardHostService {
     private readonly verificationCatalog;
     private readonly team;
     private readonly timers;
+    /** Live reader of the global native-/goal switch; frozen per execution. */
+    private readonly goalRunEnabled;
+    /** Live reader of the deployment's new-card defaults (published and applied per create). */
+    private readonly cardDefaults;
+    /**
+     * Live reader of the run-launch admission width: how many launches may be in
+     * flight at once. Read at every admission, so a settings edit bounds the next
+     * launch without remounting the row. Absent means the default.
+     */
+    private readonly runLaunchWidth;
     private lastPowerJson;
     private readonly now;
     /** The deployment's workspaces, consulted to resolve a card that pins none. */
@@ -103,14 +147,36 @@ export declare class TaskBoardHostService {
         now?: () => number;
         commandDispatcher?: SessionCommandDispatcher;
         workspaceRegistry?: TaskBoardWorkspaceRegistry;
+        /**
+         * The owner peer every gateway request the runner makes speaks for.
+         * Production passes the peer bound to the plugin fiber (see
+         * {@link createOwnerPeer}); absent is fine for tests and bare mounts,
+         * where the runner binds one to a fresh root context.
+         */
+        ownerPeer?: GatewayPeer;
         /**
          * Permission baseline of the confirmation gate: a fixed value, or a live
          * resolver the board re-reads so a Host Settings change needs no remount.
          */
         sessionDefaultPermission?: TaskPermission | (() => TaskPermission);
         maxSubtaskDepth?: number;
+        /**
+         * Live reader of the deployment's new-card defaults (volatile config reads).
+         * The board publishes them for the create dialog and re-reads them for every
+         * create that opts in, so a settings edit reaches the next created card
+         * without remounting the row. Absent means the deployment configures none.
+         */
+        cardDefaults?: () => CardDefaults;
         team?: TaskBoardTeamDispatcher;
         timers?: HostTimerFace;
+        /**
+         * Live GLOBAL native /goal switch (a volatile config read). Read ONCE per
+         * execution, at launch, and carried by value from then on: a settings edit
+         * made while a run is in flight must not arm, disarm or otherwise change the
+         * goal/acceptance contract of that run. Absent means OFF, which is the
+         * default for every deployment that never configured it.
+         */
+        goalRunEnabled?: () => boolean;
         /**
          * Live acceptance settings (volatile config reads). Absent keeps goal
          * acceptance OFF for every execution this service opens, which is what a
@@ -119,9 +185,25 @@ export declare class TaskBoardHostService {
         verificationSettings?: () => VerificationSettings;
         /** The host model catalog the acceptance contract resolves its route from. */
         verificationCatalog?: () => Promise<ModelCatalogView | undefined>;
+        /**
+         * Live admission width for run launches: the number of launches (one
+         * session creation and its prompt each) that may be in flight at once. Read
+         * per admission, so editing the setting bounds the next launch of a run that
+         * is still queueing. Absent means the default width.
+         */
+        runLaunchWidth?: () => number;
     });
     start(): void;
-    setConfiguration(active: boolean, preventIdleSleep: boolean): void;
+    /**
+     * Apply the live configuration. The roster cadence is re-read on every
+     * commit, so a settings edit takes effect without a restart; the poll is
+     * scheduled at the new cadence immediately rather than waiting out the old
+     * interval.
+     * @param active - the board's master switch.
+     * @param preventIdleSleep - whether the board holds an idle-sleep assertion.
+     * @param sessionPollSeconds - roster-poll cadence in seconds (clamped).
+     */
+    setConfiguration(active: boolean, preventIdleSleep: boolean, sessionPollSeconds?: number): void;
     snapshot(): TaskBoardSnapshot;
     /**
      * Admit one external provider. Idempotent by extension id; the returned
@@ -184,6 +266,26 @@ export declare class TaskBoardHostService {
     private emitStatusChanges;
     dispose(): void;
     private launch;
+    /**
+     * Read the acceptance contract one run group freezes, in the order the board
+     * has always read it: the acceptance settings, then the global native-/goal
+     * switch, then the model catalog that both resolves the contract's route and
+     * decides the reasoning effort the session may be given.
+     */
+    private freezeRunContract;
+    /**
+     * A {@link RunContractFreezer} that reads once and hands the SAME value to
+     * every later caller of one run group. A read that fails is not cached: the
+     * next member reads again, exactly as a per-execution read would have.
+     */
+    private contractFreezerForRunGroup;
+    /**
+     * Give back the occurrence a launch consumed, for a launch that never reached
+     * a session: a failed launch, or one the Host abandoned while it was still
+     * waiting for an admission slot. A manual run, and a launch that DID reach a
+     * session, are never refunded.
+     */
+    private refundUnstartedSchedule;
     private scheduleTeammate;
     /**
      * Spawn one teammate inside the Lead session and attach the teammate's
@@ -193,7 +295,32 @@ export declare class TaskBoardHostService {
      * Lead's cascade verdict.
      */
     private spawnTeammate;
+    /**
+     * One roster pass, and whether it could read the session tree.
+     *
+     * The board reads the DSH session roster only while it has something the
+     * roster can decide: an execution to inspect, or a card parked in the running
+     * column whose verdict may arrive from a settle this process never saw. That
+     * gate is what removes the cost the reporter measured — `session/list`
+     * rebuilds every persisted session row (string conversion, object allocation,
+     * a stat per record), and an idle board with no tasks was paying it every few
+     * seconds forever.
+     * @returns whether the roster was readable (an idle pass counts as readable).
+     */
     private pollSessions;
+    /**
+     * The session a run may continue in, for a card that opted into reuse
+     * (issue #1419). Reuse requires positive evidence that the previous session
+     * is present and idle, and that evidence must be read for THIS launch: an
+     * idle board no longer polls, so a roster cached from an earlier pass could
+     * be hours old — either refusing a session that has been idle all along, or
+     * prompting into one that started running since. A card that did not opt in
+     * reads no roster at all, and a read that fails mints a fresh conversation
+     * exactly as an unknown roster always did.
+     * @param task - the task about to run.
+     * @returns the session id to continue in, or undefined for a fresh session.
+     */
+    private reuseSessionFor;
     /** Reuse the session list this poll already fetched: one list RPC per tick, not 1 + E. */
     private reconcileExecutions;
     /**
@@ -206,6 +333,30 @@ export declare class TaskBoardHostService {
      * each streak is logged, so the Host log names the session.
      */
     private settleAndNotify;
+    /**
+     * Remove one execution's acceptance-only detail after it PASSED and settled.
+     *
+     * Deliberately narrow: only the acceptance mechanism's own per-attempt
+     * material (findings, invalid diagnostics, the bulky judge side) is removed,
+     * and only for THIS execution, keyed by its own id in the ledger it belongs
+     * to. No user file, task artifact, raw session history or other execution's
+     * record is read or written. Idempotent by the record's own state, and it
+     * clearly never touches a run that did not pass (the caller's guard) — a
+     * failed or invalid execution keeps everything a repair or a review needs.
+     * @param taskId - the task whose execution settled.
+     * @param executionId - the settled execution.
+     */
+    private cleanupAcceptanceDetail;
+    /**
+     * Catch-up pass: clean the acceptance detail of every execution that PASSED
+     * and settled but whose cleanup did not finish (a crash, a failed write, a
+     * Host killed mid-cleanup).
+     *
+     * The same bounds as any other cleanup apply — only a real pass record on a
+     * settled execution is touched — so this can never delete material belonging
+     * to an execution that did not pass, and never a user file.
+     */
+    private cleanupPendingAcceptanceDetail;
     private noteUnreadableInspection;
     /** Drop the armed schedule timer and forget its target. */
     private clearScheduleTimer;
@@ -240,6 +391,13 @@ export declare class TaskBoardHostService {
      * member then launches on its own so one refused participant cannot hold the
      * others back. A team run's members are spawned inside the root's Lead
      * session instead, once that session exists.
+     *
+     * Every launch of one run set goes through the admission queue, which admits
+     * at most `runLaunchWidth` of them at a time — the whole subtree still opens,
+     * members just enter the running column in batches. Order inside the group is
+     * the order they are enqueued here, so the root's session always exists before
+     * any member's, and one member's launch settling (or failing) is what admits
+     * the next. All members share the one contract this group freezes.
      */
     private dispatchRuns;
     /**
@@ -248,7 +406,40 @@ export declare class TaskBoardHostService {
      */
     private setApplicability;
     private scheduleLaunch;
+    /**
+     * Hand one launch to the admission queue, or abandon it on the spot when the
+     * Host is already stopping: a queue entry created after {@link dispose} would
+     * otherwise never be drained, and its card would sit in the running column
+     * until the next Host start recovered it.
+     */
+    private enqueueLaunch;
+    /** Whether one opened execution is still open in the ledger. */
+    private isExecutionOpen;
+    /**
+     * Take one launch that never started out of the running column.
+     *
+     * Settled as CANCELLED, not failed: nothing about the run's work went wrong —
+     * the Host stopped before the launch got a slot, which is exactly what the
+     * next start's interrupted-start recovery records for an execution that never
+     * reached a session. A scheduled occurrence that never reached a session is
+     * refunded on the same terms as any other pre-session failure, so a run the
+     * Host never started cannot silently spend the user's run budget.
+     */
+    private abandonQueuedRun;
     private schedulePoll;
+    /**
+     * Count one failed pass and arm the retry that follows it.
+     *
+     * A session tree that is down is retried on a doubling delay instead of
+     * hammering it on the fixed cadence: the heartbeat would otherwise repeat
+     * every failure — and every retry inside {@link HostExecutionRunner.listRunning}
+     * — at exactly the interval the reporter measured.
+     */
+    private notePollFailure;
+    /** Arm the retry that follows a failed pass, doubling up to the ceiling. */
+    private armPollBackoff;
+    /** Drop a pending retry; the next regular tick takes over. */
+    private clearPollBackoff;
     /**
      * Re-arm from the ledger's current targets. Callers that just changed a
      * schedule (the host routes, the agent tools) invoke this after the write

package/lib/types/index.d.ts

@@ -62,12 +62,73 @@ export interface Config {
      * of the root task opens, so the ceiling is deliberately small.
      */
     maxSubtaskDepth?: Volatile<number>;
+    /**
+     * How often, in seconds, the Host re-reads the DSH session roster while the
+     * board has something to reconcile: a running card, an open execution, or an
+     * active provider extension. An idle board with none of those does not poll
+     * at all, so this cadence only bounds how quickly a running card settles.
+     */
+    sessionPollSeconds?: Volatile<number>;
+    /**
+     * How many run launches this board may have in flight at once (1..16,
+     * default 3). One run opens its whole subtree, so without a bound the Host
+     * asks DSH for every member's session in the same tick; this is the mechanism
+     * that enforces the repository's measured guidance for heavy implementation
+     * subagents. Members wait their turn instead of being dropped: the subtree
+     * still opens completely, they only enter the running column in batches. Read
+     * at each admission, so an edit bounds the next launch of a run that is still
+     * queueing.
+     */
+    runLaunchWidth?: Volatile<number>;
     /**
      * Continuable-subagent provider the Agent Teams service uses to compose a
      * teammate. Matches the Agent Teams tool plugin's `freshProvider` default;
      * only team-mode runs use it.
      */
     teamProvider?: string;
+    /**
+     * GLOBAL native /goal switch (default OFF), the master control over whether
+     * this board starts a run with dsh's built-in /goal at all. A run uses native
+     * /goal only when THIS is on AND the task's own `goalRun` is not off; while
+     * it is off every task runs one plain turn.
+     *
+     * The value is frozen when an execution starts, so toggling it only affects
+     * executions that begin afterwards and never re-writes a task's stored
+     * `goalRun` preference. A run that consequently does not execute native
+     * /goal is marked as such (its acceptance applicability is `goal-disabled`)
+     * and is never reported as a passed goal acceptance or failed for lacking a
+     * completion call. Independent of `goalVerification`; acceptance governs the
+     * completing call of a goal-form run, this switch governs whether the run
+     * becomes a goal run.
+     */
+    goalRunEnabled?: Volatile<boolean>;
+    /**
+     * Agent preset a NEW card starts from (volatile, default blank = not set).
+     * A prefill, never a pin: the create dialog opens with it selected, the
+     * caller may override it, and the card stores what it was created with. It
+     * reaches the create path only when that caller opts in with
+     * `applyCardDefaults`, so the extension provider's own create and the legacy
+     * import are untouched.
+     */
+    cardDefaultMode?: Volatile<string>;
+    /**
+     * Permission a NEW card starts from (volatile, default blank = not set), one
+     * of the three presets. A prefill like the rest: a value above
+     * `sessionDefaultPermission` still has to be confirmed by a human before the
+     * card may run, because the pre-execution gate is what decides that.
+     */
+    cardDefaultPermission?: Volatile<TaskPermission | ''>;
+    /**
+     * Model a NEW card starts from (volatile, default blank = not set).
+     */
+    cardDefaultModel?: Volatile<string>;
+    /**
+     * Reasoning level a NEW card starts from (volatile, default blank = not set).
+     * Bound to `cardDefaultModel` exactly as a card's own level is bound to its
+     * own model: it applies only while the card's final model IS that default
+     * model, and a blank `cardDefaultModel` makes it inert.
+     */
+    cardDefaultReasoningEffort?: Volatile<string>;
     /**
      * Goal acceptance for executions this board starts (default ON). When on,
      * update_goal(action: complete) inside a task execution is refused until an
@@ -93,6 +154,23 @@ export interface Config {
      * sent, and the fallback to the model's own default is reported.
      */
     goalVerificationReasoningEffort?: Volatile<string>;
+    /**
+     * Ceiling of ONE judge request of a goal acceptance, in seconds
+     * (30..600, default 150). One acceptance issues six judge requests (three
+     * criteria times two rounds), so a ceiling that is too small turns a slow but
+     * healthy judge route into a wall of timeouts, and every timeout was charged
+     * as an acceptance anomaly. Raise it for a reasoning model reading a long
+     * trace.
+     */
+    goalVerificationCallTimeoutSeconds?: Volatile<number>;
+    /**
+     * Total ceiling of ONE goal acceptance attempt, in seconds (120..1800,
+     * default eight times the per-call default). Keep it at or above
+     * `goalVerificationCallTimeoutSeconds` times six or an acceptance can never
+     * finish: the attempt then ends early with a budget stop that judges nothing
+     * and spends no acceptance budget.
+     */
+    goalVerificationBudgetSeconds?: Volatile<number>;
 }
 /**
  * Continuable-subagent provider for fresh teammates, matching the Agent Teams
@@ -124,18 +202,42 @@ export interface ConfigInput {
     sessionDefaultPermission?: TaskPermission;
     /** Subtask depth limit, 1..3. */
     maxSubtaskDepth?: number;
+    /** Roster-poll cadence in seconds while the board has work to reconcile. */
+    sessionPollSeconds?: number;
+    /** Concurrent run launches allowed at once, 1..16. */
+    runLaunchWidth?: number;
     /** Continuable-subagent provider the Agent Teams service composes a teammate from. */
     teamProvider?: string;
+    /** Global native /goal switch; default off, frozen per execution. */
+    goalRunEnabled?: boolean;
+    /** Agent preset a new card starts from; blank = not set. */
+    cardDefaultMode?: string;
+    /** Permission a new card starts from; blank = not set. */
+    cardDefaultPermission?: TaskPermission | '';
+    /** Model a new card starts from; blank = not set. */
+    cardDefaultModel?: string;
+    /** Reasoning level a new card starts from; blank = not set. */
+    cardDefaultReasoningEffort?: string;
     /** Goal acceptance switch. */
     goalVerification?: boolean;
     /** Judge model route for goal acceptance; blank inherits the host default. */
     goalVerificationModel?: string;
     /** Judge reasoning effort; blank inherits the host default. */
     goalVerificationReasoningEffort?: string;
+    /** Ceiling of one judge request of a goal acceptance, in seconds. */
+    goalVerificationCallTimeoutSeconds?: number;
+    /** Total ceiling of one goal acceptance attempt, in seconds. */
+    goalVerificationBudgetSeconds?: number;
 }
 export declare const Config: z<ConfigInput, Config>;
 /** Schema default for the goal-acceptance switch, re-read for hand-built contexts. */
 export declare const DEFAULT_GOAL_VERIFICATION = true;
+/**
+ * Schema default for the GLOBAL native-/goal switch, re-read for hand-built
+ * contexts. Deliberately false: a deployment that never configured it (and
+ * every card written before the option existed) runs plain single turns.
+ */
+export declare const DEFAULT_GOAL_RUN = false;
 declare module '@deepseek-ai/cordis' {
     interface Events {
         /**
@@ -250,6 +352,45 @@ export declare function buildTeamDispatcher(ctx: Context, provider: string): Tas
  * @returns the llm service, or undefined when this deployment serves none.
  */
 export declare function resolveLlmRuntime(ctx: Context): LlmRuntime | undefined;
+/**
+ * The subset of `sessionController` the board uses to wake a cold persisted
+ * session before running a slash command on it (issue #1861).
+ */
+interface SessionControllerFace {
+    resolveAgent(sessionId: Parameters<Context['agents']['get']>[0]): Promise<{
+        readonly agent: Parameters<Context['commands']['execute']>[0];
+    } | {
+        readonly error: {
+            readonly message?: string;
+        };
+    }>;
+}
+/**
+ * Resolve the optional `sessionController` service. Like the tool registry and
+ * the llm runtime, it is read dynamically so capture-only test contexts that do
+ * not mount the full session controller still activate the board.
+ * @param ctx - the plugin context.
+ * @returns the session controller face, or undefined when unavailable.
+ */
+export declare function resolveSessionController(ctx: Context): SessionControllerFace | undefined;
+/**
+ * Resolve the live Agent for an execution session, resuming a cold persisted
+ * session through `sessionController.resolveAgent` when it is not yet in
+ * `ctx.agents` (issue #1861).
+ *
+ * A fresh run (`session/create`) or a session the browser is currently
+ * following is already in `ctx.agents`, so the fast path returns immediately.
+ * A scheduled or manual reuse of a cold session — one that `session/list`
+ * reports as idle from disk without activating its Agent — is not in
+ * `ctx.agents` when `pinAndPrompt` runs `/permission` ahead of
+ * `session/selectModel` and `session/prompt`; delegating to
+ * `sessionController.resolveAgent` resumes it with its recorded preset and
+ * model-selection state, matching what those gateway endpoints do next.
+ * @param ctx - the plugin context.
+ * @param sessionId - the target execution session id.
+ * @returns the live Agent for `sessionId`.
+ */
+export declare function resolveExecutionAgent(ctx: Context, sessionId: Parameters<Context['agents']['get']>[0]): Promise<Parameters<Context['commands']['execute']>[0]>;
 /**
  * Activate the board's host half: ledger, routes, cron scheduler, power
  * inhibitor, and the model-facing announcement.

package/lib/types/protocol.d.ts

@@ -1,22 +1,36 @@
 import type { TaskUpdatePatch } from './core/use-cases/task-update.ts';
+import type { SetSchedulePatch } from './core/use-cases/task-schedule.ts';
 import { type NewTaskInput, type TaskPermission, type TaskRecord, type TaskStatus } from './core/tasks.ts';
 import { type TaskBoardExtensionPayload } from './core/extension.ts';
 import { type ModelCatalogView, type VerificationContract, type VerificationSettings } from './core/verification.ts';
-export declare const TASK_BOARD_SCHEMA_VERSION: 5;
-/** Ledger documents written before v5; loaded once and migrated on startup. */
-export declare const TASK_BOARD_LEGACY_SCHEMA_VERSION: 4;
+export declare const TASK_BOARD_SCHEMA_VERSION: 6;
+/** Ledger documents written before v6; loaded once and migrated on startup. */
+export declare const TASK_BOARD_LEGACY_SCHEMA_VERSION: 5;
+/** Ledger documents written before v5; migrated through the v5 normalization too. */
+export declare const TASK_BOARD_PRE_ACCEPTANCE_SCHEMA_VERSION: 4;
 /** Ledger documents written before v4; migrated through the v4 normalization too. */
 export declare const TASK_BOARD_OLDER_SCHEMA_VERSION: 3;
 /** Ledger documents written before v3; migrated through every later normalization too. */
 export declare const TASK_BOARD_OLDEST_SCHEMA_VERSION: 2;
 /**
- * Every older generation the loader migrates in place. v5 only ADDS the
- * per-execution acceptance block, so the migration is the normalization pass
- * that re-validates each row; a document from any listed generation upgrades
- * losslessly.
+ * The last generation whose rules still need the Host zone stamped on them at
+ * migration: v4 introduced the stored zone but a rule written without one must
+ * stop following a later TZ change. A v5 rule already carries its zone (or
+ * deliberately follows the Host), so it is NOT stamped again.
+ */
+export declare const TASK_BOARD_ZONE_STAMP_SCHEMA_VERSION: 4;
+/**
+ * Every older generation the loader migrates in place. v5 only added the
+ * per-execution acceptance block and v6 only added the scheduling mode and run
+ * budget, so the migration is the normalization pass that re-validates each
+ * row; a document from any listed generation upgrades losslessly.
  */
 export declare const TASK_BOARD_MIGRATABLE_SCHEMA_VERSIONS: readonly number[];
 export declare const TASK_BOARD_API_PREFIX = "/api/task-board";
+/** Longest accepted caller identity on an external outcome record. */
+export declare const EXTERNAL_INITIATOR_MAX_LENGTH = 200;
+/** Longest accepted free-text summary on an external outcome record. */
+export declare const EXTERNAL_SUMMARY_MAX_LENGTH = 1000;
 export type PowerPhase = 'disabled' | 'idle' | 'acquiring' | 'active' | 'error' | 'unsupported';
 export interface TaskBoardPowerSnapshot {
     platform: string;
@@ -52,6 +66,27 @@ export interface TaskBoardSnapshot {
      * into team execution (Team Lead session plus one teammate per subtask).
      */
     teamRunAvailable?: boolean;
+    /**
+     * Live GLOBAL native-/goal switch. The browser uses it to disable the
+     * task-level option (and explain that the global switch must be turned on
+     * first) WITHOUT rewriting anyone's stored per-task preference; the Host
+     * freezes its own read per execution, so this mirror never governs a run in
+     * flight.
+     */
+    goalRunEnabled?: boolean;
+    /**
+     * New-card defaults this deployment configures: what the create dialog opens
+     * with, and what the create path fills an omitted target from when the caller
+     * opts in (`applyCardDefaults`). A target the board configures nothing for is
+     * omitted rather than published blank, so the browser can tell "no default
+     * model" from "a blank one".
+     */
+    cardDefaults?: {
+        mode?: string;
+        permission?: TaskPermission;
+        model?: string;
+        reasoningEffort?: string;
+    };
     /**
      * Read-only summaries published by running extensions, keyed by extension id.
      * The board forwards them verbatim; it never interprets their shape.
@@ -124,14 +159,30 @@ export type TaskBoardAction = {
 } | {
     kind: 'settle';
     taskId: string;
+}
+/** Clear the acceptance anomalies recorded on a card's open execution (issue #1828). */
+ | {
+    kind: 'reset-verification';
+    taskId: string;
+}
+/**
+ * Record an outcome an agent OUTSIDE the Host produced (issue #1826).
+ *
+ * It writes a real execution record, so the terminal column and the run
+ * history both derive from that one record instead of a bare column edit.
+ * `cancelled` is deliberately absent: nothing outside a DSH session may
+ * claim the Host closed a run, and `running` must stay Host-only.
+ */
+ | {
+    kind: 'record-external-outcome';
+    taskId: string;
+    result: 'succeeded' | 'failed';
+    initiatedBy: string;
+    summary?: string;
 } | {
     kind: 'set-schedule';
     taskId: string;
-    patch: {
-        enabled?: boolean;
-        cron?: string;
-        timeZone?: string | null;
-    };
+    patch: SetSchedulePatch;
 } | {
     kind: 'run';
     taskId: string;