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

package/lib/types/host/launch-admission.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Admission control for the session-creating half of a run.
+ *
+ * One board action can open a whole subtree, and a team run hands every member
+ * of it to the Lead at once. Both paths used to fire every launch in the same
+ * tick, so the Host asked DSH for N sessions at once — the burst the repository's
+ * measured guidance caps at three heavy implementation subagents
+ * (docs/multi-agent-resources.md), with no mechanism enforcing it.
+ *
+ * The queue is SERVICE-wide, not per run group: the pressure it bounds is the
+ * machine's (the Host process's memory and the swap it drives), and two run
+ * groups opened from two tabs share one Host. Admission is round-robin across
+ * run groups — FIFO inside a group, so a group's first run (the Lead, which
+ * carries the run shape and the teammate namespace) always starts before its
+ * members — so a large subtree cannot starve a run opened after it, and no
+ * entry can be starved.
+ *
+ * The width is read through a live callback, so a settings edit takes effect on
+ * the next admission without remounting anything.
+ *
+ * @module dsh-task-board/host/launch-admission
+ */
+/** One launch the queue has not started yet. */
+export interface QueuedLaunch {
+    /** Run group this launch belongs to; the unit of round-robin fairness. */
+    readonly groupId: string;
+    /**
+     * Perform the launch. The slot is held until this promise settles, which
+     * makes "in flight" mean "still creating and prompting its session".
+     * A rejection is swallowed here so one broken launch can never wedge the
+     * slot; the caller owns reporting.
+     */
+    start(): Promise<void>;
+    /**
+     * Called by {@link LaunchAdmissionQueue.drain} for a launch that never
+     * started, so the caller can take its execution out of the running column.
+     */
+    abandon(): void;
+}
+export declare class LaunchAdmissionQueue {
+    private readonly width;
+    /** Waiting launches per run group, in arrival order. */
+    private readonly waiting;
+    /** Run groups in round-robin order. */
+    private rotation;
+    /** Slot holders of the launches in flight, one per admitted launch. */
+    private readonly inFlight;
+    /** Highest number of launches in flight at once; observability and tests. */
+    peakInFlight: number;
+    /**
+     * @param width - live admission width (already normalized by the caller).
+     */
+    constructor(width: () => number);
+    /** Launches the queue has not admitted yet. */
+    get pendingCount(): number;
+    /** Launches currently holding a slot. */
+    get inFlightCount(): number;
+    /** Admit one launch, immediately if a slot is free. */
+    enqueue(launch: QueuedLaunch): void;
+    /**
+     * Abandon every waiting launch: the queue is being torn down, so an entry
+     * that never started can never start. Launches already in flight are left
+     * alone — their session may already exist, and the callers that own them
+     * settle them through the normal path.
+     * @returns the abandoned launches, in abandonment order.
+     */
+    drain(): QueuedLaunch[];
+    private pump;
+    /** The next launch by round-robin across groups and FIFO inside one. */
+    private takeNext;
+    private admit;
+}

package/lib/types/host/verification-gate.d.ts

@@ -18,7 +18,21 @@
  * - an anomaly (timeout, authentication, unparseable answer, an unusable judge
  *   route) is recorded separately from a quality verdict and is never treated
  *   as one;
+ * - exhausting the anomaly budget does NOT judge the card: an environment that
+ *   cannot answer is not the work failing, so the cycle is held open with no
+ *   judge call until a user clears the recorded anomalies (issue #1828);
+ * - an attempt the time budget ends before any verdict is recorded as its own
+ *   stage and charged to no budget at all (issue #1828);
+ * - an INVALID acceptance (a veto whose required evidence is missing,
+ *   unlocatable, or aimed at the empty-work baseline) is recorded in its own
+ *   stage, spends its OWN bounded budget, and never consumes a quality attempt
+ *   or fails the card; when that budget is spent the cycle is held for a human
+ *   exactly like a spent anomaly budget;
  * - concurrent completion calls for one execution share one acceptance.
+
+ * The validity check itself is program-level (`assessAcceptanceValidity` in
+ * `core/verification.ts`), applied after the judge answers and BEFORE any
+ * quality verdict is written: a stronger prompt alone could not enforce it.
  */
 import type { PreToolDecision } from '@deepseek-ai/dsh-tools';
 import type { LlmRuntime } from '@deepseek-ai/dsh-llm';
@@ -51,6 +65,16 @@ export interface GoalVerificationGateDeps {
      * that serves none) simply means the judge sees the trajectory alone.
      */
     workspaceChanges?: () => WorkspaceChangeSource | undefined;
+    /**
+     * Ceiling of one judge request, read per acceptance (a row setting). Absent
+     * keeps the default, so a programmatic mount still judges.
+     */
+    callTimeoutMs?: () => number;
+    /**
+     * Total ceiling of one acceptance attempt, read per acceptance (a row
+     * setting). Absent keeps the default.
+     */
+    budgetMs?: () => number;
     logger: {
         warn(message: string, ...rest: unknown[]): void;
     };

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

@@ -15,18 +15,45 @@ export declare const VERIFICATION_MAX_TRACE_CHARS = 80000;
 export declare const VERIFICATION_MAX_ENTRY_CHARS = 4000;
 /** Largest per-finding text kept from one judge answer. */
 export declare const VERIFICATION_MAX_FINDING_CHARS = 400;
-/** Findings kept per judge answer and per acceptance. */
+/** Largest verbatim citation kept from one finding. */
+export declare const VERIFICATION_MAX_QUOTE_CHARS = 600;
+/** Largest requirement/observation/gap statement kept from one finding. */
+export declare const VERIFICATION_MAX_PROBLEM_CHARS = 400;
+/** Structured findings kept per judge answer and per acceptance. */
 export declare const VERIFICATION_MAX_FINDINGS_PER_CALL = 3;
-export declare const VERIFICATION_MAX_FINDINGS = 6;
-/** One judge request's ceiling and its retry budget. */
-export declare const VERIFICATION_CALL_TIMEOUT_MS = 120000;
+export declare const VERIFICATION_MAX_FINDINGS = 12;
+/**
+ * Default ceiling of ONE judge request. The effective ceiling is a row setting
+ * (`goalVerificationCallTimeoutSeconds`), read live by the gate, because 120s was
+ * tight for a reasoning model reading an 80,000 character trace with a 16,384
+ * token output cap: every timeout it produced was charged as an acceptance
+ * anomaly against a budget that then failed the card.
+ */
+export declare const VERIFICATION_CALL_TIMEOUT_MS = 150000;
 export declare const VERIFICATION_MAX_TOKENS = 16384;
 export declare const VERIFICATION_TEMPERATURE = 0.2;
 export declare const VERIFICATION_REQUEST_ATTEMPTS = 3;
 /** Redaction patterns, mirrored from the verifier's defaults. */
 export declare const VERIFICATION_REDACT_PATTERNS: readonly string[];
 /** Why one acceptance could not produce a verdict. */
-export type VerificationErrorKind = 'route-unavailable' | 'timeout' | 'auth' | 'parse' | 'request' | 'aborted';
+export type VerificationErrorKind = 'route-unavailable' | 'timeout' | 'auth' | 'parse' | 'request' | 'aborted' | 'budget';
+/**
+ * The time one acceptance attempt may still spend.
+ *
+ * `deadline` is the instant the whole attempt runs out; `callTimeoutMs` is the
+ * ceiling of a single judge call. The pair is what ties the retry budget to the
+ * acceptance budget: a call is not started unless its own ceiling still fits
+ * inside what is left, because starting one the outer budget will abort anyway
+ * only burns wall time and turns a slow machine into an anomaly.
+ */
+export interface AcceptanceBudget {
+    /** Absolute instant (ms epoch) the acceptance attempt runs out at. */
+    deadline: number;
+    /** Ceiling of one judge call in milliseconds. */
+    callTimeoutMs: number;
+    /** Clock the caller runs on, injected so tests drive it deterministically. */
+    now: () => number;
+}
 /** An acceptance anomaly: never a quality verdict, always recorded as one. */
 export declare class VerificationError extends Error {
     readonly kind: VerificationErrorKind;
@@ -89,8 +116,8 @@ export interface AcceptanceResult {
  * Run one acceptance: every criterion is judged twice, the odd round with the
  * A/B slots swapped, and the per-round scores are mapped back and averaged per
  * criterion.
- * @param input - the judge route, evidence, threshold and cancellation.
- * @returns the recorded attempt (quality verdict or anomaly).
+ * @param input - the judge route, evidence, threshold, time budget and cancellation.
+ * @returns the recorded attempt (quality verdict, anomaly, or budget stop).
  */
 export declare function runAcceptance(input: {
     llm: LlmRuntime;
@@ -99,6 +126,10 @@ export declare function runAcceptance(input: {
     threshold: number;
     index: number;
     signal: AbortSignal;
+    /** Instant (ms epoch) the attempt runs out at; defaults to now plus the default budget. */
+    deadline?: number;
+    /** Ceiling of one judge call; defaults to {@link VERIFICATION_CALL_TIMEOUT_MS}. */
+    callTimeoutMs?: number;
     /** Host-observed workspace changes, rendered as the prompt's reference context. */
     context?: string;
     /** How many changed files that context shows. */

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

@@ -1,6 +1,7 @@
-import { type ExecutionOutcome, type ExecutionRecord, type TaskRecord } from './core/tasks.ts';
+import { type ExecutionOutcome, type ExecutionRecord, type ScheduleMode, type TaskRecord } from './core/tasks.ts';
+import type { CardDefaults } from './core/card-defaults.ts';
 import { type TaskBoardAction, type TaskBoardSchedulerSnapshot } from './protocol.ts';
-import type { ExecutionVerification } from './core/verification.ts';
+import { type ExecutionVerification } from './core/verification.ts';
 import { type TaskPermission } from './core/handover.ts';
 export interface LedgerState {
     revision: number;
@@ -35,7 +36,10 @@ export interface OpenExecutionReference {
 /** Minimal value copy used by the Host scheduler. */
 export interface DueScheduleReference {
     readonly taskId: string;
-    readonly cron: string;
+    /** Whether this due rule is a recurring cron rule or a single planned instant. */
+    readonly mode: ScheduleMode;
+    /** Cron expression of a recurring rule; absent on a one-shot. */
+    readonly cron?: string;
     /** Zone this rule's wall clock is read in. */
     readonly timeZone: string;
     readonly nextRunAt: number;
@@ -44,6 +48,24 @@ export interface DueScheduleReference {
 export interface LedgerRuntimeView {
     readonly armedSchedules: number;
     readonly openExecutions: readonly OpenExecutionReference[];
+    /**
+     * Session ids of every open execution, including the ones
+     * {@link openExecutions} skips because their own outcome is already
+     * recorded. A caller that asks whether the board still observes any session
+     * must use this list: a deferred cascade parent is settled by its members,
+     * but it is still an open execution.
+     */
+    readonly openSessionIds: readonly string[];
+    /**
+     * Whether this document holds anything the session roster can still decide:
+     * an open execution that needs inspecting, or a card in the running column
+     * whose verdict may arrive from a settle this process never saw.
+     *
+     * A board with no running card, no open execution and no armed schedule has
+     * no use for the roster at all, which is what lets the Host poll stand down
+     * instead of re-reading every persisted session forever.
+     */
+    readonly needsSessionState: boolean;
 }
 /**
  * Best-effort single-letter process state ('R','S','D','Z',...) or undefined
@@ -104,9 +126,12 @@ export declare class HostTaskLedger {
      * instead of remounting the row.
      */
     private depthLimit;
+    /** Live reader of the deployment's new-card defaults (a volatile config read). */
+    private readonly cardDefaults;
     constructor(dir?: string, now?: () => number, options?: {
         sessionDefaultPermission?: TaskPermission | (() => TaskPermission);
         maxSubtaskDepth?: number;
+        cardDefaults?: () => CardDefaults;
     });
     /** Current subtask depth limit (1..3). */
     get maxSubtaskDepth(): number;
@@ -125,7 +150,7 @@ export declare class HostTaskLedger {
     };
     state(): LedgerState;
     /**
-     * Runtime-only projection for the 5 s Host poll. It copies just primitive
+     * Runtime-only projection for the Host poll. It copies just primitive
      * identifiers and timestamps, never the complete task/execution history or
      * an authoritative mutable object from the ledger.
      */
@@ -152,9 +177,45 @@ export declare class HostTaskLedger {
     /**
      * Open the cascade one due schedule triggers: an empty array means nothing
      * ran (already running, or a participant whose elevated permission is still
-     * unconfirmed), and the rule rolls to its next occurrence either way.
+     * unconfirmed, a one-shot whose instant was missed, or an exhausted budget),
+     * and the rule's own state says which.
+     *
+     * The run budget is enforced HERE, inside the single ledger writer: a rule
+     * whose counter already reached its cap is stopped instead of opened, so no
+     * restart, repeated timer fire or re-arm can overrun it.
+     * @param taskId - the task whose rule came due.
+     * @param triggeredAt - the instant the occurrence came due.
+     * @returns the executions this occurrence opened.
+     */
+    openScheduled(taskId: string, triggeredAt: number): OpenedRun[];
+    /**
+     * Record a due occurrence that opened no execution: roll a recurring rule to
+     * its next occurrence (budget untouched), or stop it when there is none. A
+     * one-shot has no second occurrence, so it always stops here with the reason.
+     */
+    private skipOccurrence;
+    /** Apply a schedule-occurrence transition and persist it atomically. */
+    private progressSchedule;
+    /**
+     * Refund the one scheduled run an occurrence consumed before its launch
+     * failed without creating a session (see
+     * {@link applyScheduleRefund}). Called by the service on the failed-launch
+     * path only; a manual run and a launch that did reach a session are never
+     * refunded. A no-op for a task with no rule, so a failed cascade member does
+     * not touch anything.
+     * @param taskId - the task whose occurrence is being refunded.
+     * @param now - clock instant (ms epoch).
+     */
+    refundScheduledOccurrence(taskId: string, now: number): void;
+    /**
+     * Boot / resume recovery: skip every occurrence that came due while the board
+     * was not running through it. A recurring rule rolls to its next future
+     * target; a one-shot whose instant has passed is stopped as missed, because
+     * there is no later occurrence left to run. Rendering the missed occurrence
+     * is deliberately not attempted: the ACL of a card that fired hours ago is
+     * stale, and the board's own recovery contract is "missed triggers are
+     * skipped, never replayed".
      */
-    openScheduled(taskId: string, nextRunAt: number | undefined, triggeredAt: number): OpenedRun[];
     skipMissed(now: number): void;
     setScheduler(patch: Partial<TaskBoardSchedulerSnapshot>): void;
     /**
@@ -169,6 +230,14 @@ export declare class HostTaskLedger {
     getTask(id: string): TaskRecord | undefined;
     saveTaskRecord(task: TaskRecord): void;
     private apply;
+    /**
+     * Whether a creation-time schedule request is usable. A one-shot must carry
+     * a whole-millisecond instant in the future; a recurring rule must carry a
+     * valid expression with a reachable occurrence and, when capped, a positive
+     * whole run budget. An unusable zone is refused rather than reinterpreted as
+     * the Host zone.
+     */
+    private validScheduleRequest;
     /**
      * The binding that makes a run illegal, if any.
      *
@@ -194,15 +263,18 @@ export declare class HostTaskLedger {
     /** Whether a task or any of its subtasks still has an open execution. */
     private subtreeHasOpenExecution;
     /**
-     * Open one execution per cascade participant (the requested task and its
-     * on-board descendants, within the depth limit) under a single run group, and
-     * commit the ledger once. The returned runs are ordered root-first, so the
-     * Host launches the parent before its subtasks.
+     * Open one execution per cascade participant that still has work (the
+     * requested task and its on-board descendants, within the depth limit) under
+     * a single run group, and commit the ledger once. A descendant in 'done' is
+     * not a participant ({@link joinsCascadeRun}). The returned runs are ordered
+     * root-first, so the Host launches the parent before its subtasks.
      * @param root - the task the user ran.
      * @param now - clock instant (ms epoch).
      * @param initiator - the DSH session that asked for the run (audit only).
      * @param rerun - true to reset the root to 'todo' before starting it.
-     * @param nextRunAt - when set, the root's schedule also rolls forward.
+     * @param progress - when set, this run was a due occurrence and the root's
+     *   rule is advanced (counter, next target, stop/skip record) in the same
+     *   atomic commit that opened the executions.
      */
     private startCascade;
     /**
@@ -248,6 +320,14 @@ export declare class HostTaskLedger {
      * @returns whether the document changed.
      */
     private closeTeamMembers;
+    /**
+     * Re-align every armed rule at load/import. A recurring rule is recomputed
+     * from the current instant; a one-shot is armed at its planned instant when
+     * that is still in the future, and stopped as missed once it has passed
+     * (there is no later occurrence to run). A recurring rule recomputed past an
+     * occurrence records the skip, so the board can show that a fire was passed
+     * over rather than silently rewinding.
+     */
     private repairSchedules;
     private reconcileInterruptedStarts;
     /**

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

@@ -1,7 +1,9 @@
-import type { TypertGateway } from '@deepseek-ai/dsh-api-gateway';
+import { Context } from '@deepseek-ai/cordis';
+import type { InvokeRemoteRequest, TypertGateway } from '@deepseek-ai/dsh-api-gateway';
 import type { SessionSummary } from '@deepseek-ai/dsh-api-session-controller/types';
 import type { CommandResult } from '@deepseek-ai/dsh-commands/types';
 import type { Workspace } from '@deepseek-ai/dsh-workspace/types';
+import type { ModelCatalogView } from './core/verification.ts';
 import type { TaskRecord } from './core/tasks.ts';
 /**
  * Host services needed to validate a task's workspace before creating a
@@ -10,12 +12,47 @@ import type { TaskRecord } from './core/tasks.ts';
 export interface TaskBoardWorkspaceRegistry {
     list(): readonly Workspace[];
 }
+/**
+ * The peer every gateway request names: derived from the public
+ * `InvokeRemoteRequest` type so this package needs no direct dependency on
+ * `@deepseek-ai/dsh-typert-protocol` for the shape.
+ */
+export type GatewayPeer = InvokeRemoteRequest['peer'];
 interface GatewayRequest {
     namespace: string;
     method: string;
     args: Record<string, unknown>;
+    peer: GatewayPeer;
     signal?: AbortSignal;
 }
+/**
+ * Mint the in-process owner peer this plugin's Host calls speak for.
+ *
+ * The 0.2.1 gateway made `peer` mandatory on every request, and the
+ * authorization layer reads only `peer.principal`: a principal of
+ * `{ kind: 'owner' }` is how host-local code states that the call IS the local
+ * user driving their own Host, so the gateway answers it directly instead of
+ * running a remote-access decision (only non-owner principals are judged).
+ * That is exactly the task board's position — it creates, renames, prompts,
+ * and reads sessions as the Host itself, which before 0.2.1 was the implicit
+ * privilege of every in-process caller. The board claims owner explicitly, and
+ * only ever inside its own Host process: no wire field can set a principal,
+ * and this plugin never forwards a browser-supplied one.
+ *
+ * `interactions` stays `'none'`: the board only invokes methods and opens the
+ * short `session/follow` stream. The gateway's interactions check gates
+ * exactly the forwarded-event endpoints (opening an event stream, answering a
+ * waterfall), which this caller never touches; an `'answer'` peer would
+ * additionally receive forwarded Host events, a capability the board neither
+ * needs nor wants.
+ *
+ * The peer's signal aborts once `ctx` disposes, so streams opened for it end
+ * with the plugin fiber, and `dispose()` is idempotent with racing calls
+ * sharing one completion. The id carries no credential — the protocol fixes
+ * `principal` as the only identity persisted in a session log — so a fresh
+ * unique id per mount is sufficient.
+ */
+export declare function createOwnerPeer(ctx: Context): GatewayPeer;
 interface SessionGateway {
     invoke(request: GatewayRequest): Promise<unknown>;
     stream?(request: GatewayRequest): Promise<AsyncIterable<unknown>>;
@@ -78,15 +115,16 @@ export interface PromptContext {
     /** True when those members run as teammates inside this session (Team Lead). */
     team?: boolean;
     /**
-     * Scheduled-run provenance: the instant the cron rule actually fired and the
-     * IANA zone its wall clock was read in. Present only for a cron-triggered
-     * run, so the model can resolve an unqualified date in the run's own terms
-     * instead of guessing from the Host clock (issue #1722).
+     * Scheduled-run provenance: the instant the rule actually fired, its kind,
+     * and the IANA zone its wall clock was read in. Present only for a
+     * timer-triggered run, so the model can resolve an unqualified date in the
+     * run's own terms instead of guessing from the Host clock (issue #1722).
      */
     schedule?: {
         triggeredAt: number;
         timeZone: string;
-        cron: string;
+        mode: 'cron' | 'once';
+        cron?: string;
     };
 }
 /**
@@ -110,15 +148,25 @@ export declare class HostExecutionRunner {
     private readonly gateway;
     private readonly commands?;
     private readonly workspaceRegistry?;
-    /** Newest scanned event sequence per session with no matching execution end. */
+    /**
+     * Newest event sequence per session whose COMPLETE history walk (reaching
+     * the execution boundary) found no matching execution end. A later walk may
+     * trust everything at or below it and examine only newer records.
+     */
     private readonly scanMemos;
     private readonly unavailableAttempts;
     private readonly unavailableBackoffMs;
+    /**
+     * The peer every request speaks for. Production passes the peer bound to the
+     * plugin fiber; a bare runner (unit tests around fake gateways) gets one
+     * bound to a fresh root context instead.
+     */
+    private readonly ownerPeer;
     private unsupportedSessionListWarned;
     constructor(gateway: SessionGateway | TypertGateway, commands?: SessionCommandDispatcher | undefined, workspaceRegistry?: TaskBoardWorkspaceRegistry | undefined, unavailableRetry?: {
         attempts?: number;
         backoffMs?: number;
-    });
+    }, ownerPeer?: GatewayPeer);
     private invoke;
     private stream;
     /**
@@ -144,6 +192,26 @@ export declare class HostExecutionRunner {
         promptContext?: PromptContext;
         onSession?: (sessionId: string) => void;
         onGoalArmed?: (armed: boolean) => void;
+        /**
+         * GLOBAL native /goal switch, resolved by the caller ONCE per execution and
+         * carried here so the decision is frozen for this launch.
+         *
+         * Frozen deliberately: a settings edit made while the run is in flight must
+         * not arm, disarm or otherwise change the goal/acceptance contract of a run
+         * already running. Absent means off — the default for every deployment that
+         * never touched the switch, including cards written before the option
+         * existed. A plain single turn is what an off switch produces; the task-level
+         * `goalRun` still applies on top of it (both must ASK for a goal).
+         */
+        goalEnabled?: boolean;
+        /**
+         * The host model catalog, read ONCE per execution by the caller. The card's
+         * pinned reasoning effort is sent only when this catalog declares it for the
+         * route the execution runs at, so one snapshot decides both the acceptance
+         * contract and the effort this run freezes. Absent means "no capability
+         * evidence": an effort is then not sent at all.
+         */
+        catalog?: ModelCatalogView;
     }): Promise<string>;
     /**
      * Fail closed when a reused session records a different Agent preset than
@@ -160,10 +228,30 @@ export declare class HostExecutionRunner {
      * @param pinned - the preset id the task pins, when it pins one.
      */
     private assertReusedPreset;
+    /**
+     * Split a `provider/model` pin. A pin without a provider keeps only the model
+     * id: the provider is the one the host catalog declares for it, resolved at
+     * launch because the session wire contract requires a provider.
+     */
+    private static pinnedRoute;
+    /**
+     * The route a card that pins no model actually runs at: the session's own
+     * recorded selection (the durable fold the GUI reads; `next` is the pending
+     * user choice, `lastUsed` what the last request consumed), or — for a session
+     * that has selected none yet, which is exactly a session that would start at
+     * the deployment default — the host default from the catalog.
+     *
+     * A route that cannot be READ is undefined and the effort is not sent:
+     * falling back to the host default there would silently switch the model of a
+     * session this run only meant to continue.
+     */
+    private sessionRoute;
     /**
      * Re-assert the pinned execution contract on a session and queue the task
      * prompt. Shared by the fresh-session and reuse paths so both apply exactly
-     * the same permission/model pins before the prompt.
+     * the same permission/model/effort pins before the prompt. A session that
+     * refuses a selection carrying a catalog-confirmed effort throws here, so the
+     * prompt is never queued behind a run at the wrong level.
      */
     private pinAndPrompt;
     /**
@@ -182,11 +270,21 @@ export declare class HostExecutionRunner {
      * dsh's goal-round driver keeps starting continuation rounds until the agent
      * marks it complete (see {@link goalVerdict} for how the run settles).
      *
-     * Opt-out: a task whose `goalRun` is an explicit false runs one plain turn.
+     * Two switches gate the arming, and BOTH must ask for it:
+     * - the GLOBAL native-/goal switch (`goalEnabled`, default OFF), frozen when
+     *   this execution started; and
+     * - the task's own `goalRun` (absent means off, only an explicit true opts
+     *   the card into a goal run).
+     *
      * A refusal (no command dispatcher, no `/goal` command in this cohort, an
-     * objective the command rejects) is reported and the run continues as that
-     * plain turn: the task was asked to run, and a missing goal mode must not
-     * lose the work.
+     * objective the command rejects) is reported and the run continues as a plain
+     * turn: the task was asked to run, and a missing goal mode must not lose the
+     * work.
+     * @param sessionId - the session to arm in.
+     * @param task - the task being run.
+     * @param context - the run's prompt context.
+     * @param goalEnabled - the GLOBAL switch, frozen for this execution.
+     * @returns whether `/goal` was really armed.
      */
     private armGoal;
     /**