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

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

@@ -0,0 +1,35 @@
+/**
+ * The default-agent-preset picker of the settings card's new-card-defaults
+ * topic.
+ *
+ * It renders the rows the create dialog's own mode picker renders — built-in
+ * presets first, then user presets, each labelled with its default and
+ * unavailable suffixes (board/preset-label.ts owns both) — and it renders a
+ * preset that cannot compose a session as a row that is visible but NOT
+ * selectable, so the board never stores a default no session could be composed
+ * from.
+ *
+ * The shared ChoiceField cannot express that: its choices carry no disabled
+ * state, and a stored pin the roster no longer serves would render as an empty
+ * trigger rather than as the unavailable preset it is. Both need a native
+ * `<select>` (the fallback the shared SelectField itself takes under an
+ * appearance skin), styled with the settings card's own field classes so the
+ * control stays a sibling of the fields beside it.
+ */
+import type { ExecutionPresetOption } from '../core/controller.ts';
+import type { FieldProps } from './PluginSettingsCard.tsx';
+/** Props of the default-preset field: the shared field contract plus the roster. */
+export interface CardDefaultPresetFieldProps extends FieldProps {
+    /**
+     * The deployment's agent-preset roster, or undefined while its runtime read
+     * has not answered: an unread roster offers the inherit choice alone instead
+     * of calling every stored pin "removed".
+     */
+    presets: readonly ExecutionPresetOption[] | undefined;
+}
+/**
+ * Render the default-preset select.
+ * @param props - the field contract and the roster to list.
+ * @returns the field.
+ */
+export declare function CardDefaultPresetField(props: CardDefaultPresetFieldProps): import("react").JSX.Element;

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

@@ -7,6 +7,7 @@ import type { InjectFace, PropsLocale, PropsRenderSlots, PropsRuntime } from '@d
 import type { SnapshotStore } from '@deepseek-ai/dsh-client-store';
 import type { ConfigForm } from '@deepseek-ai/dsh-client-ui-settings/client';
 import type { TaskBoardExtensionDispatch } from '../core/extension.ts';
+import type { ExecutionPresetOption } from '../core/controller.ts';
 import { type CardActions, type CardShell, type FieldState as CardFieldState } from './settings-form.ts';
 /** The task-board fields this card edits (the namespace's full schema). */
 export interface TaskBoardSettings {
@@ -20,6 +21,12 @@ export interface TaskBoardSettings {
     maxSubtaskDepth?: number;
     /** Roster-poll cadence in seconds while the board has work to reconcile. */
     sessionPollSeconds?: number;
+    /**
+     * How many run launches may be in flight at once (1..16, default 3). One run
+     * opens its whole subtree, so this bounds the burst of sessions a single run
+     * action creates; members enter the running column in batches, none is dropped.
+     */
+    runLaunchWidth?: number;
     /**
      * GLOBAL native /goal switch (default off): the master control over whether
      * this board starts a run with dsh's built-in /goal at all. Frozen per
@@ -32,6 +39,20 @@ export interface TaskBoardSettings {
     goalVerificationModel?: string;
     /** Judge reasoning effort; blank inherits the host default level. */
     goalVerificationReasoningEffort?: string;
+    /**
+     * Agent preset the create dialog of this board opens with. Blank pins
+     * nothing, so a new card follows the deployment default as before.
+     */
+    cardDefaultMode?: string;
+    /** Permission the create dialog opens with; blank applies no default. */
+    cardDefaultPermission?: string;
+    /** Execution model route the create dialog opens with; blank applies none. */
+    cardDefaultModel?: string;
+    /**
+     * Reasoning level bound to `cardDefaultModel`; it applies only while a
+     * card's final model IS that configured route, and is inert without one.
+     */
+    cardDefaultReasoningEffort?: string;
 }
 /** What the task-board card renders. */
 export interface TaskBoardSettingsCardState extends CardShell {
@@ -45,6 +66,8 @@ export interface TaskBoardSettingsCardState extends CardShell {
     maxSubtaskDepth: CardFieldState;
     /** Roster-poll cadence field. */
     sessionPollSeconds: CardFieldState;
+    /** Run-launch admission width field. */
+    runLaunchWidth: CardFieldState;
     /** GLOBAL native /goal switch. */
     goalRunEnabled: CardFieldState;
     /** Goal-acceptance switch. */
@@ -53,6 +76,20 @@ export interface TaskBoardSettingsCardState extends CardShell {
     goalVerificationModel: CardFieldState;
     /** Judge reasoning-effort field. */
     goalVerificationReasoningEffort: CardFieldState;
+    /** New-card default agent preset. */
+    cardDefaultMode: CardFieldState;
+    /** New-card default permission. */
+    cardDefaultPermission: CardFieldState;
+    /** New-card default model route. */
+    cardDefaultModel: CardFieldState;
+    /** New-card default reasoning level. */
+    cardDefaultReasoningEffort: CardFieldState;
+    /**
+     * The deployment's agent-preset roster, published by the runtime read the
+     * plugin wires; undefined until it answers, which leaves the default-preset
+     * field offering the inherit choice alone.
+     */
+    presets?: readonly ExecutionPresetOption[];
 }
 /** The registration-side face the card's slot entry injects. */
 export interface TaskBoardSettingsCardFace extends CardActions {
@@ -68,9 +105,21 @@ export declare class TaskBoardSettingsCardController {
     private readonly dispatch;
     private readonly form;
     private readonly store;
+    /** The deployment's agent-preset roster, once its runtime read has answered. */
+    private presets;
     /** @param scope - the bound configuration form for the `task-board` namespace. */
     constructor(scope: ConfigForm<TaskBoardSettings>, dispatch: TaskBoardExtensionDispatch);
     private projection;
+    /**
+     * Publish the deployment's agent-preset roster to the default-preset field.
+     * The roster is a runtime fact read outside this card (src/client/index.ts
+     * wires it once for both the board's pickers and this topic); it can arrive
+     * late or not at all, and until it does the field lists the inherit choice
+     * alone. This never blocks a save: a deployment that serves no roster still
+     * has a writable settings document.
+     * @param presets - the roster rows.
+     */
+    setPresetRoster(presets: readonly ExecutionPresetOption[]): void;
     /**
      * Build the face the card's slot registration injects.
      * @returns the card's snapshot and its form actions.

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

@@ -0,0 +1,25 @@
+/**
+ * Reasoning-effort field: one picker shared by both execution-target editors
+ * (the create dialog and the detail page), so the two never describe the same
+ * capability differently. The levels are the ones the picked model's catalog
+ * entry declares; an empty value is a real choice — "follow the model or Host
+ * default" — and is the default state.
+ *
+ * A stored level the roster no longer lists (the model left the roster, or its
+ * adapter changed) stays shown and labelled, but is not offered again, so the
+ * field never silently shows a different value than the one the card will ask
+ * for while the choosable set stays exactly the levels the model declares.
+ */
+import type { ExecutionModelOption } from '../../core/controller.ts';
+/** The controlled reasoning-effort picker. */
+export declare function ReasoningEffortField({ models, modelId, value, pending, onChange }: {
+    /** The roster the picked model is looked up in. */
+    models: readonly ExecutionModelOption[];
+    /** The model this card pins; '' means "no pin". */
+    modelId: string;
+    /** The selected effort; '' means "follow the model or Host default". */
+    value: string;
+    /** Whether a mutation is in flight (the field locks with the rest of the form). */
+    pending: boolean;
+    onChange: (next: string) => void;
+}): import("react").JSX.Element;

package/lib/types/client/board/model-options.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Execution model options: the picker rows built from the official
+ * `session/modelCatalog` reply, and the reasoning-effort derivation both
+ * execution-target editors read off them (the create dialog and the detail
+ * page share one contract here, so they cannot promise different levels).
+ *
+ * The pickers must offer each model's real reasoning levels, which only the
+ * catalog declares — so the reply is normalized once, here, instead of every
+ * picker re-reading the wire shape. The fallback discovery path carries no
+ * capability metadata at all; its rows stay silent about reasoning rather than
+ * claiming a model supports none.
+ */
+import type { ExecutionModelOption } from '../../core/controller.ts';
+import type { TaskBoardKey } from '../locales.ts';
+/**
+ * Normalize a `session/modelCatalog` reply into picker rows: one row per model
+ * of every provider group, keyed by the qualified route an execution pins.
+ * @param value - the raw catalog reply.
+ * @returns the rows, empty when the reply is unreadable.
+ */
+export declare function modelOptionsFromCatalog(value: unknown): ExecutionModelOption[];
+/**
+ * Normalize the flat `llm/discoverModels` list into picker rows. That reply
+ * names models only, so every row leaves the reasoning capability unknown.
+ * @param value - the raw discovery list.
+ * @returns the rows, empty when the list is unreadable.
+ */
+export declare function modelOptionsFromDiscoveredModels(value: unknown): ExecutionModelOption[];
+/**
+ * The picker rows of a model roster: the qualified `provider/model` route as
+ * the value a pin stores, and the provider beside the model name so two
+ * providers offering one model name stay distinguishable.
+ * @param models - the roster rows.
+ * @returns the choice rows, in roster order.
+ */
+export declare function modelChoiceRows(models: readonly ExecutionModelOption[]): Array<{
+    value: string;
+    label: string;
+}>;
+/**
+ * The capability row the roster publishes for one model route.
+ * @returns undefined when no model is pinned, or the roster does not describe
+ * the pinned one — an unknown model is not the same as a model without
+ * reasoning.
+ */
+export declare function reasoningOfModel(models: readonly ExecutionModelOption[], modelId: string): ExecutionModelOption['reasoning'] | undefined;
+/**
+ * The effort ids the picker offers for a model, in catalog order.
+ * @returns an empty list when the model is unpinned, unknown, declares no
+ * reasoning, or publishes no selectable level.
+ */
+export declare function reasoningEffortsFor(models: readonly ExecutionModelOption[], modelId: string): string[];
+/** Whether the effort picker may be operated: a pinned model with declared, selectable levels. */
+export declare function reasoningPickerEnabled(models: readonly ExecutionModelOption[], modelId: string): boolean;
+/**
+ * The effort to keep when the picked model changes. Only a model that declares
+ * its levels can invalidate one: a model the roster cannot describe keeps the
+ * stored value, because the roster has no grounds to call it invalid.
+ * @param effort - the effort currently stored/selected ('' = follow the default).
+ * @returns the effort to keep.
+ */
+export declare function reconcileReasoningEffort(models: readonly ExecutionModelOption[], modelId: string, effort: string): string;
+/**
+ * The copy explaining why the picker is in its current state. One lookup for
+ * both editors, so the create dialog and the detail page never drift apart.
+ */
+export declare function reasoningHintKey(models: readonly ExecutionModelOption[], modelId: string): TaskBoardKey;

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

@@ -20,3 +20,24 @@ export declare function presetLabel(preset: Pick<ExecutionPresetOption, 'id' | '
  * marks with `isDefault`.
  */
 export declare function inheritPresetLabel(presets: readonly ExecutionPresetOption[]): string;
+/** One preset row a picker renders: the stored id, its label, and whether it may be picked. */
+export interface PresetChoiceRow {
+    /** The value a pin stores. */
+    id: string;
+    /** Display label, already carrying the default and unavailable suffixes. */
+    label: string;
+    /** True when the preset cannot compose a session: the row is shown but not selectable. */
+    disabled: boolean;
+}
+/**
+ * The picker rows of one roster, split into the built-in and the user presets.
+ * Both pickers render these rows — the create dialog's mode select and the
+ * settings card's default-preset field — so their wording and their
+ * unavailable rows cannot drift apart.
+ * @param presets - the roster options.
+ * @returns one row list per group, in roster order.
+ */
+export declare function presetChoiceRows(presets: readonly ExecutionPresetOption[]): {
+    builtin: PresetChoiceRow[];
+    custom: PresetChoiceRow[];
+};

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

@@ -0,0 +1,45 @@
+/**
+ * The agent-preset roster the execution-target pickers read: one read of the
+ * generated api-remotes face, and its normalization into the option rows the
+ * board controller and the settings card's new-card-defaults topic both
+ * consume.
+ *
+ * The roster is a runtime fact of the deployment, not ledger state. The
+ * namespace mounts with the official api-remotes assembly, so the read itself
+ * is wired through a scoped inject at the call site (see src/client/index.ts);
+ * this module owns only the shape both consumers agree on, so neither has to
+ * know how the wire face answers.
+ */
+import type { ClientRemote } from '@deepseek-ai/dsh-api-remotes/client';
+import type { ExecutionPresetOption } from '../../core/controller.ts';
+/** The generated Remote namespace the mode pickers read their roster from. */
+export type PresetRemote = ClientRemote['agentPresets'];
+/** One agent-preset row the wire face answers with. */
+export interface PresetRosterRow {
+    id: string;
+    name?: string;
+    description?: string;
+    /** Why this preset cannot compose a session; absent when it can. */
+    broken?: string;
+    isDefault: boolean;
+}
+/**
+ * Read the agent-preset roster of one deployment. The caller passes the
+ * namespace resolved inside its scoped inject, so a host that serves no such
+ * namespace never reaches here; a host that serves it answers `ok: false`
+ * instead, which leaves the caller's options untouched.
+ * @param remote - the `remote.agentPresets` namespace.
+ * @returns the roster, or a failed read the caller ignores.
+ */
+export declare function readPresetRoster(remote: PresetRemote): Promise<{
+    ok: boolean;
+    presets: readonly PresetRosterRow[];
+}>;
+/**
+ * Normalize one roster into the picker rows the UI consumes. A preset that
+ * cannot compose a session keeps its `broken` reason: the pickers show it and
+ * disable it, so a missing preset never looks like a missing roster.
+ * @param presets - the roster rows.
+ * @returns the picker options.
+ */
+export declare function presetOptionsFromRoster(presets: readonly PresetRosterRow[]): ExecutionPresetOption[];

package/lib/types/client/board/team-run-promotion.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Team-run promotion for a parent card that just gained a subtask. A card with
+ * subtasks is exactly what the Agent Team mode is for, so the two join actions
+ * (create a subtask, link an existing task) opt the parent in — but only after
+ * the Host confirmed the join, and only where the deployment serves Agent
+ * Teams. A refused join changes nothing, and a parent that already opted in is
+ * left alone rather than rewritten.
+ *
+ * Nothing here runs on mount or from a render effect: an existing card is only
+ * ever touched by the user's own join action, so switching the option off by
+ * hand stays off.
+ */
+import type { BoardController } from '../../core/controller.ts';
+import type { TaskRecord } from '../../core/tasks.ts';
+/**
+ * Whether a join would promote this parent: the deployment serves Agent Teams
+ * and the parent has not opted in yet.
+ * @param controller - the board controller (the snapshot carries both facts).
+ * @param parent - the task that gained a subtask, if there is one.
+ */
+export declare function parentAwaitsTeamRunPromotion(controller: BoardController, parent: TaskRecord | undefined): boolean;
+/**
+ * Opt the parent in after the Host confirmed the join.
+ * @returns true when the opt-in was written; false when it did not apply.
+ */
+export declare function promoteParentForTeamRun(controller: BoardController, parent: TaskRecord | undefined): Promise<boolean>;

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

@@ -244,6 +244,14 @@ export declare const zh: {
     'exec.permission.danger-full-access': string;
     'exec.model.default': string;
     'exec.model.unknown': string;
+    'exec.reasoning': string;
+    'exec.reasoning.inherit': string;
+    'exec.reasoning.unknown': string;
+    'exec.reasoning.hint.pickModel': string;
+    'exec.reasoning.hint.unknownModel': string;
+    'exec.reasoning.hint.noEfforts': string;
+    'exec.reasoning.hint.inherit': string;
+    'exec.teamRunAutoHint': string;
     'exec.reuseSession': string;
     'exec.teamRun': string;
     'exec.teamRunHint': string;
@@ -288,6 +296,8 @@ export declare const zh: {
     'settings.maxSubtaskDepth': string;
     'settings.maxSubtaskDepthHint': string;
     'settings.maxSubtaskDepthOption': string;
+    'settings.runLaunchWidth': string;
+    'settings.runLaunchWidthHint': string;
     'settings.runBehaviorTitle': string;
     'settings.runBehaviorCardHint': string;
     'settings.goalRunGlobal': string;
@@ -317,6 +327,11 @@ export declare const zh: {
     'settings.goalVerificationEffortFallback': string;
     'settings.goalVerificationEffortFallbackNone': string;
     'settings.goalVerificationModelInvalid': string;
+    'settings.cardDefaultsTitle': string;
+    'settings.cardDefaultsCardHint': string;
+    'settings.cardDefaultModeHint': string;
+    'settings.cardDefaultPermissionHint': string;
+    'settings.cardDefaultModelHint': string;
     'running.executing': string;
     'running.verifying': string;
     'running.repairing': string;
@@ -391,6 +406,7 @@ export declare const zh: {
     'detail.subtasks.detach': string;
     'detail.subtasks.runningLock': string;
     'detail.subtasks.runHint': string;
+    'detail.subtasks.runHintSettled': string;
     'detail.subtasks.waiting': string;
     'detail.subtasks.depthLimit': string;
     'detail.subtasks.hostOnly': string;

package/lib/types/core/card-defaults.d.ts

@@ -0,0 +1,78 @@
+/**
+ * New-card defaults: the execution targets a freshly created card starts from,
+ * and how they combine with what the caller picked and with the card a subtask
+ * or a duplicate is created from.
+ *
+ * Framework-free (no cordis, no runtime imports) because BOTH halves compile
+ * it: the Host resolves the seed when it writes the card, and the browser
+ * resolves the same seed to open the new-task dialog on it. One pure function
+ * is the only place the rules live, so the dialog and the ledger cannot drift.
+ *
+ * Every target is resolved in ONE order: what the caller picked wins over the
+ * value carried over from the card this one is created from, which wins over
+ * the board's new-card defaults, and a target nothing supplies stays blank
+ * ("no pin, resolved at run time"). A duplicate is a copy of its source and a
+ * subtask is derived from its parent, so both keep the source's own pins and
+ * fill only the fields that source left unset.
+ *
+ * The permission of a PARENT is the one exception: it never participates. The
+ * permission is not copied onto a card at creation — doing so would also have
+ * to copy the parent's human confirmation to stay runnable, and a detached
+ * child would keep both, so one confirmed parent would mint unbounded confirmed
+ * elevated roots. It is resolved along the ancestor chain at launch instead
+ * (core/subtask.ts), which is what makes detaching remove the inheritance by
+ * construction. A duplicate is not a hierarchy link, so it copies the
+ * permission like every other target. The board's own default permission is not
+ * a parent binding either and does apply to a subtask; it only pre-fills the
+ * card, and a value above the session baseline still needs a human
+ * confirmation before the card may run.
+ *
+ * The reasoning level is bound to the model route it was chosen for and never
+ * crosses to another one:
+ *
+ *   - a level the caller picked is used as it stands;
+ *   - a caller that pinned a model of its own inherits no level at all, not
+ *     even one the same model happens to carry on the source card;
+ *   - otherwise the source card's level travels with the source value it was
+ *     stored on, exactly as the card's own model/level pair does, and wins over
+ *     the board default level, so a board that configures none behaves exactly
+ *     as the create path always has;
+ *   - a board default level applies only while the card's final model IS the
+ *     configured default model, and a blank default model makes it inert —
+ *     a level the resolved model does not declare could only be refused by
+ *     model selection at run time.
+ */
+import type { TaskRecord } from './tasks.ts';
+/** The board's configured new-card defaults; a blank target means "not set". */
+export interface CardDefaults {
+    /** Agent preset a new card starts from. */
+    mode?: string;
+    /** Permission a new card starts from. */
+    permission?: string;
+    /** Model a new card starts from. */
+    model?: string;
+    /** Reasoning level a new card starts from, for the model above. */
+    reasoningEffort?: string;
+}
+/** The card a new one is created from, and how it is derived from it. */
+export interface CardTargetSource {
+    /** A copy of the source card, or a subtask of it. */
+    kind: 'duplicate' | 'parent';
+    /** The source card's execution targets. */
+    task: Pick<TaskRecord, 'mode' | 'permission' | 'model' | 'reasoningEffort'>;
+}
+/** The resolved targets of the card about to be created; blank means "unset". */
+export interface CardTargetSeed {
+    mode: string;
+    permission: string;
+    model: string;
+    reasoningEffort: string;
+}
+/**
+ * Resolve the execution targets a new card starts from.
+ * @param defaults - the board's configured new-card defaults, if any.
+ * @param source - the card this one is created from (a duplicate or a parent), if any.
+ * @param picked - what the caller chose explicitly; a non-blank value wins.
+ * @returns the four targets, blank where nothing supplies a value.
+ */
+export declare function resolveCardTargets(defaults: CardDefaults | undefined, source: CardTargetSource | undefined, picked?: Partial<CardTargetSeed>): CardTargetSeed;

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

@@ -100,6 +100,17 @@ export interface ExecutionModelOption {
     name?: string;
     label?: string;
     provider?: string;
+    /**
+     * Reasoning metadata the adapter declares for this exact route. An effort
+     * picker is offered only while `supported`, and its choices are `efforts` —
+     * the ids the target model really accepts, so the UI never offers (or keeps)
+     * a level the model would reject. Absent means the deployment published no
+     * capability for this model; the card value is then left untouched.
+     */
+    reasoning?: {
+        supported: boolean;
+        efforts?: readonly string[];
+    };
 }
 /** The execution-target option sets the UI feeds into the controller. */
 export interface ExecutionOptionsSnapshot {
@@ -112,7 +123,7 @@ export interface ExecutionOptionsSnapshot {
  * (revision/scheduler/power); a full snapshot also carries the deployment
  * constants the UI reads (session default permission, subtask depth).
  */
-export type HostMirror = Pick<TaskBoardSnapshot, 'revision' | 'scheduler' | 'power' | 'sessionDefaultPermission' | 'maxSubtaskDepth' | 'teamRunAvailable' | 'goalRunEnabled' | 'extensions'>;
+export type HostMirror = Pick<TaskBoardSnapshot, 'revision' | 'scheduler' | 'power' | 'sessionDefaultPermission' | 'maxSubtaskDepth' | 'teamRunAvailable' | 'goalRunEnabled' | 'cardDefaults' | 'extensions'>;
 /** Immutable controller snapshot for UI subscriptions. */
 export interface ControllerSnapshot {
     tasks: readonly TaskRecord[];
@@ -187,6 +198,19 @@ export declare class BoardController {
     isHostBacked(): boolean;
     /** Retry initial migration/state synchronization after an explicit Host error. */
     retryHostSync(): Promise<boolean>;
+    /**
+     * Re-read the authoritative Host snapshot.
+     *
+     * The board's volatile deployment configuration — the new-card defaults among
+     * it — is republished the moment the settings document is written, but the SSE
+     * frame that republish emits carries the value as of BEFORE the write (the
+     * loader hands the update to the fiber while the new document is not yet
+     * visible to it), so a mirror that followed frames alone would stay one edit
+     * behind and the create dialog would prefill from the previous defaults for
+     * the rest of the session. The surface that owns the write asks for the
+     * snapshot again instead of trusting the frame.
+     */
+    refreshHostState(): void;
     /**
      * Show the board. The layout owns which panel the center column renders, so
      * the state flip and the panel selection travel together here; a composition
@@ -359,12 +383,13 @@ export declare class BoardController {
      */
     private mirrorDepth;
     /**
-     * Project a Host snapshot onto the browser's mirror. SSE frames and partial
-     * snapshots carry only the volatile subset (revision/scheduler/power), so the
-     * deployment constants the UI reads — the session-default permission the
-     * confirmation banner compares against and the subtask depth limit — are
-     * carried over from the last full snapshot instead of being dropped by a
-     * heartbeat frame.
+     * Project a Host snapshot onto the browser's mirror. Every snapshot the
+     * transport serves is a full document (bootstrap/state/action all answer
+     * `TaskBoardHostService.snapshot()`), so the deployment constants the UI reads
+     * — the session-default permission the confirmation banner compares against,
+     * the subtask depth limit, the platform switches and the extensions a provider
+     * published — are taken as published, carried over only where the snapshot
+     * itself omits the key.
      */
     private mirrorOf;
     private refreshRemote;

package/lib/types/core/launch-width.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Run-launch admission width: the one bound on how many sessions this board
+ * starts at the same time.
+ *
+ * One board action opens a whole subtree, and a team run hands every member of
+ * it to the Lead at once, so without a bound the Host asks DSH for dozens of
+ * sessions in a single tick. The repository's own measured guidance caps heavy
+ * implementation subagents at three (docs/multi-agent-resources.md) and no
+ * runtime mechanism enforced it; this setting is that mechanism.
+ *
+ * The bounds and the default live here rather than in either half, exactly like
+ * the roster cadence: the settings card validates a draft against the same
+ * range the Host clamps a hand-edited configuration to, and a programmatic
+ * mount that names no width gets the default.
+ *
+ * @module dsh-task-board/core/launch-width
+ */
+/** Width used when neither the settings document nor the mount names one. */
+export declare const DEFAULT_RUN_LAUNCH_WIDTH = 3;
+/** Narrowest accepted width: one launch at a time. */
+export declare const RUN_LAUNCH_WIDTH_MIN = 1;
+/** Widest accepted width. */
+export declare const RUN_LAUNCH_WIDTH_MAX = 16;
+/**
+ * Clamp a configured width into the supported range. A value the schema would
+ * refuse (non-finite, below the floor, above the ceiling) still leaves the
+ * board launching: an out-of-range setting never stalls a run.
+ * @param width - configured width, or undefined for the default.
+ * @returns the effective width.
+ */
+export declare function normalizeRunLaunchWidth(width: number | undefined): number;

package/lib/types/core/reasoning-effort.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Which reasoning effort one execution may actually send.
+ *
+ * The rule lives here, in one pure place, so the launch path cannot drift from
+ * what the picker promises: an effort is sent ONLY for the exact model route
+ * whose adapter declares that id. An unsupported value is dropped rather than
+ * passed through — the Host validates the selection against the same
+ * capability (`resolveCallConfig` rejects an unsupported effort) and the whole
+ * model selection would fail with it. An absent effort stays absent: the SDK
+ * then materializes the model's own default, which is exactly what "inherit
+ * the model" means.
+ *
+ * A card that pins a bare model id also gets its provider resolved here: the
+ * session wire contract requires `provider` (ModelSelection), so the catalog is
+ * the only place that can complete the documented `provider/model` or model-id
+ * pin.
+ */
+import type { CatalogModel, ModelCatalogView } from './verification.ts';
+/** One execution route an effort resolves against: `provider/model`, or a bare model id. */
+export interface ReasoningRoute {
+    provider?: string;
+    model: string;
+}
+/** The catalog entry a route names, once the catalog can complete it. */
+export interface DeclaredReasoningRoute {
+    provider: string;
+    model: string;
+    /** The adapter's reasoning metadata; absent when it exposes none. */
+    reasoning?: CatalogModel['reasoning'];
+}
+/** What one card's effort resolves to for one route. */
+export interface ReasoningEffortDecision {
+    /** The effort to send; absent means "send none". */
+    effort?: string;
+    /** The card's own value when it will NOT be sent. */
+    dropped?: string;
+}
+/** Trim one optional effort: blank text means "not set", like every other pinned target. */
+export declare function normalizeReasoningEffort(value: string | undefined): string | undefined;
+/**
+ * Complete one route through the host catalog: a qualified route must match its
+ * provider group, and a bare model id matches the first group carrying it —
+ * which is the provider the request then names.
+ * @param catalog - the host model catalog, when this deployment serves one.
+ * @param route - the route as the card pins it.
+ * @returns the completed route with its reasoning metadata, or undefined when
+ *   the catalog declares no such model.
+ */
+export declare function declaredRoute(catalog: ModelCatalogView | undefined, route: ReasoningRoute): DeclaredReasoningRoute | undefined;
+/**
+ * Resolve the effort one execution sends.
+ * @param requested - the card's stored effort (absent or blank = inherit).
+ * @param catalog - the host model catalog, when this deployment serves one.
+ * @param route - the route the execution will actually run at.
+ * @returns the effort to send, or the dropped value that will not be sent.
+ */
+export declare function resolveReasoningEffort(requested: string | undefined, catalog: ModelCatalogView | undefined, route: ReasoningRoute | undefined): ReasoningEffortDecision;

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

@@ -76,11 +76,32 @@ export interface ParentLinkCheck {
 export declare function checkParentLink(tasks: readonly TaskRecord[], childId: string, parentId: string | null, maxSubtaskDepth: number, lineage?: LineageIndex): ParentLinkCheck;
 /**
  * The tasks one run request opens executions for: the requested task first,
- * then its on-board descendants within the configured depth. Archived tasks
- * never run; a participant that already has an open execution is skipped by
- * the caller, which cannot start it twice.
+ * then its on-board descendants within the configured depth. This is the
+ * SHAPE of a cascade — every walk that must see the whole tree (settlement,
+ * archive/restore, the running lock) reads it. The run path filters it with
+ * {@link joinsCascadeRun}: archived tasks never run, a participant that already
+ * has an open execution is skipped by the caller, which cannot start it twice,
+ * and a finished descendant is left alone.
  */
 export declare function cascadeTargets(tasks: readonly TaskRecord[], rootId: string, maxSubtaskDepth: number): TaskRecord[];
+/**
+ * Whether a cascade member takes part in a new run.
+ *
+ * The task the user ran is always a member: the request names that card, and
+ * the operator asked for it to run whatever its column says. A descendant does
+ * not join once it sits in the `done` column — its work is finished, so running
+ * the parent again is a run of the parent, never a second execution of work
+ * that is already done. The rule keys on the column alone, so it covers both a
+ * subtask that ran and one an operator moved to done by hand, and it holds for
+ * every trigger: a manual run, a re-run, and a due occurrence of a schedule.
+ * A card whose own schedule is enabled settles back into `todo`, so a scheduled
+ * subtask stays a participant; to make a finished one run again, move it back
+ * to `todo` or run it on its own.
+ * @param task - the candidate member.
+ * @param rootId - the task the run request named.
+ * @returns false when this member is left alone by the run.
+ */
+export declare function joinsCascadeRun(task: TaskRecord, rootId: string): boolean;
 /** One still-open execution belonging to a cascade run group. */
 export interface OpenCascadeChild {
     taskId: string;
@@ -114,11 +135,12 @@ export declare function effectiveTaskPermission(task: TaskRecord): TaskRecord['p
 /**
  * Resolve the execution targets a (sub)task actually runs with: its own value
  * wins, and an unset target inherits the nearest ancestor up to the root.
- * Workspace, agent preset and model inherit the ancestor's PIN only — a
- * handover bundle is a per-card continuation artefact and is never inherited.
- * The permission inherits the ancestor's EFFECTIVE binding, and its human
- * confirmation travels with it, so a subtask of an already-confirmed elevated
- * card is runnable while a subtask's own unconfirmed binding stays gated.
+ * Workspace, agent preset, model and reasoning effort inherit the ancestor's
+ * PIN only — a handover bundle is a per-card continuation artefact and is never
+ * inherited. The permission inherits the ancestor's EFFECTIVE binding, and its
+ * human confirmation travels with it, so a subtask of an already-confirmed
+ * elevated card is runnable while a subtask's own unconfirmed binding stays
+ * gated.
  */
 /**
  * The immutable teammate name for one team-mode member. Teammate names are