@linxin666/dsh-client-ui-task-board 0.4.1 → 0.4.3

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

@@ -15,6 +15,8 @@ export interface TaskBoardSettings {
     announceToAgent?: boolean;
     /** Prevent host idle sleep while sessions run or schedules are armed. */
     preventIdleSleep?: boolean;
+    /** Subtask depth limit (1..3); 1 means a single level of subtasks. */
+    maxSubtaskDepth?: number;
 }
 /** What the task-board card renders. */
 export interface TaskBoardSettingsCardState extends CardShell {
@@ -24,6 +26,8 @@ export interface TaskBoardSettingsCardState extends CardShell {
     announceToAgent: CardFieldState;
     /** Idle-system-sleep protection flag. */
     preventIdleSleep: CardFieldState;
+    /** Subtask depth limit field. */
+    maxSubtaskDepth: CardFieldState;
 }
 /** The registration-side face the card's slot entry injects. */
 export interface TaskBoardSettingsCardFace extends CardActions {

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

@@ -0,0 +1,11 @@
+import type { BoardController } from '../../core/controller.ts';
+import type { TaskRecord } from '../../core/tasks.ts';
+/** Link-subtask overlay props. */
+export interface LinkSubtaskModalProps {
+    controller: BoardController;
+    /** The task the picked card becomes a subtask of. */
+    parent: TaskRecord;
+    onClose: () => void;
+}
+/** Link-subtask overlay. */
+export declare function LinkSubtaskModal({ controller, parent, onClose }: LinkSubtaskModalProps): import("react").JSX.Element;

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

@@ -12,6 +12,12 @@ export interface NewTaskModalProps {
     defaultWorkspaceId?: string;
     /** Optional callback after successful duplication (e.g. to archive source). */
     onDuplicateSuccess?: (sourceTaskId: string) => Promise<void>;
+    /**
+     * Task the new card becomes a subtask of ("add subtask" from its detail
+     * view). The execution targets start from the parent's and the create action
+     * carries the parent link; unset targets inherit again at run time.
+     */
+    parentTask?: TaskRecord;
 }
 /** New-task form overlay. */
-export declare function NewTaskModal({ controller, onClose, initialTask, defaultWorkspaceId, onDuplicateSuccess }: NewTaskModalProps): import("react").JSX.Element;
+export declare function NewTaskModal({ controller, onClose, initialTask, defaultWorkspaceId, onDuplicateSuccess, parentTask }: NewTaskModalProps): import("react").JSX.Element;

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

@@ -2,11 +2,21 @@ import type { TaskRecord } from '../../core/tasks.ts';
 /** Compact relative/absolute time label. */
 export declare function formatHostTimestamp(ms: number, timeZone?: string): string;
 export declare function formatTime(ms: number, timeZone?: string): string;
-declare function TaskCardInner({ task, pending, timeZone, onClick }: {
+declare function TaskCardInner({ task, pending, timeZone, onClick, subtaskCount, isSubtask, subtasksDone, subtasksRunning, subtasksFailed, }: {
     task: TaskRecord;
     pending: boolean;
     timeZone?: string;
     onClick: () => void;
+    /** Direct subtasks of this card, shown as a badge (0 hides it). */
+    subtaskCount?: number;
+    /** Whether this card is itself a subtask. */
+    isSubtask?: boolean;
+    /** Direct subtasks already settled as done, for the roll-up badge. */
+    subtasksDone?: number;
+    /** Direct subtasks currently running, for the roll-up badge. */
+    subtasksRunning?: number;
+    /** Direct subtasks that failed, for the roll-up badge. */
+    subtasksFailed?: number;
 }): import("react").JSX.Element;
 /** Memoized card: re-renders only when the card's own task record changes. */
 export declare const TaskCard: import("react").MemoExoticComponent<typeof TaskCardInner>;

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

@@ -9,7 +9,7 @@
  * plugin must not take the GUI down.
  */
 import type { Context as ClientContext } from '@deepseek-ai/cordis';
-import type { ConfigForm } from '@deepseek-ai/dsh-client-ui-settings/client';
+import type { ConfigForm, ConfigForms } from '@deepseek-ai/dsh-client-ui-settings/client';
 import { type TaskBoardSettings } from './TaskBoardSettingsCard.tsx';
 import { type TaskBoardKey } from './locales.ts';
 /** Domain-owned description of one settings namespace a family card binds. */
@@ -94,3 +94,17 @@ export declare function apply(ctx: ClientContext): void;
  * @returns the form the settings card reads and writes.
  */
 export declare function bindSettingsForm(ctx: ClientContext): ConfigForm<TaskBoardSettings>;
+/**
+ * The profile entry id this package's own row carries, for a page that serves
+ * no family binder.
+ *
+ * The shared describe mirror is the only local evidence of which row id this
+ * profile actually serves, but it answers asynchronously: at plugin activation
+ * it usually holds nothing yet. An unanswered mirror therefore binds the
+ * aggregate row id rather than guessing among the candidates, and the binding
+ * is re-resolved once the mirror answers — see
+ * {@link createServedEntryForm}, which owns that rebinding.
+ * @param forms - the shared configuration forms service.
+ * @returns the entry id to bind before the mirror answers.
+ */
+export declare function servedEntryId(forms: ConfigForms): string;

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

@@ -156,12 +156,16 @@ export declare const zh: {
     'exec.mode.brokenSuffix': string;
     'exec.mode.removed': string;
     'exec.permission.default': string;
+    'exec.permission.inheritParent': string;
     'exec.permission.read-only': string;
     'exec.permission.workspace-write': string;
     'exec.permission.danger-full-access': string;
     'exec.model.default': string;
     'exec.model.unknown': string;
     'exec.reuseSession': string;
+    'exec.teamRun': string;
+    'exec.teamRunHint': string;
+    'exec.teamRunUnavailable': string;
     'exec.reuseSessionHint': string;
     'detail.executionSettings': string;
     'exec.hint': string;
@@ -192,6 +196,35 @@ export declare const zh: {
     'settings.unsaved': string;
     'settings.saveFailed': string;
     'settings.invalidNumber': string;
+    'settings.maxSubtaskDepth': string;
+    'settings.maxSubtaskDepthHint': string;
+    'settings.maxSubtaskDepthOption': string;
+    'detail.parent': string;
+    'detail.parent.open': string;
+    'detail.subtasks': string;
+    'detail.subtasks.empty': string;
+    'detail.subtasks.add': string;
+    'detail.subtasks.link': string;
+    'detail.subtasks.detach': string;
+    'detail.subtasks.runningLock': string;
+    'detail.subtasks.runHint': string;
+    'detail.subtasks.waiting': string;
+    'detail.subtasks.depthLimit': string;
+    'detail.subtasks.hostOnly': string;
+    'new.subtaskTitle': string;
+    'new.subtaskInherit': string;
+    'link.subtask.title': string;
+    'link.subtask.hint': string;
+    'link.subtask.empty': string;
+    'link.subtask.confirm': string;
+    'card.subtask': string;
+    'card.subtasks': string;
+    'card.subtasksFailed': string;
+    'card.subtasksRunning': string;
+    'card.subtasksBreakdown': string;
+    'board.hideSubtasks': string;
+    'board.showSubtasks': string;
+    'board.subtaskFilterHint': string;
 };
 /** en dictionary, complete against the zh key set. */
 export declare const en: Record<keyof typeof zh, string>;

package/lib/types/client/native-panel.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Native panel registration for the task board.
+ *
+ * The board is an official-style center-column panel, not a DOM takeover: it
+ * contributes a row into the sidebar shell's own global panel list
+ * (`sidebar.panellist`) and its page into the layout's keyed `main` slot. The
+ * shell then owns the row box, the label, the active highlight, the collapsed
+ * rail, the panel switch and the window-chrome interplay exactly as it does for
+ * the shipped Plugins and Schedule pages, so the board renders through the same
+ * container the desktop application's Plugins page uses.
+ *
+ * Both registrations go through `ctx.slots.inject`, which fires only once the
+ * owning shell entry has declared the seat: load order between this plugin and
+ * ui-layout / ui-sidebar therefore does not matter, and neither does a shell
+ * that cannot serve the seats (the callback simply never runs).
+ *
+ * @module @linxin666/dsh-client-ui-task-board/client
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+import { TASK_BOARD_PANEL_ID, type BoardController } from '../core/controller.ts';
+/** The panel id shared by the sidebar row and the main-slot occupant. */
+export { TASK_BOARD_PANEL_ID };
+/**
+ * The sidebar row glyph the shell asks for at its own size and active state.
+ * The shell owns the button, label, tooltip and rail geometry; this component
+ * draws only the glyph, like every other panel row.
+ *
+ * The glyph carries `data-dsh-panel-entry` because it is the only DOM the
+ * panel's own code owns inside that shell-owned row: the L2 contract (skins)
+ * resolves which row belongs to which plugin through it, since the shell
+ * stamps no per-entry hook of its own (see contracts/semantic-attrs-v1.md).
+ * @param props - the shell's icon share: square edge and selection state.
+ * @returns the decorative board glyph.
+ */
+export declare function TaskBoardPanelIcon({ size }: {
+    size: number;
+    active: boolean;
+}): React.ReactElement;
+/**
+ * The main-slot page. The layout mounts it only while the board is the selected
+ * panel, so the conversation keeps the center column untouched the rest of the
+ * time; the wrapper carries the pinned `data-dsh-taskboard-view` semantic
+ * anchor (L2 contract, skins) and the container query context the board's
+ * responsive rules read.
+ * @param props - the framework main-slot share plus this entry's injected face.
+ * @returns the board page.
+ */
+export declare function TaskBoardPanel({ controller }: {
+    controller: BoardController;
+}): React.ReactElement;
+/**
+ * Register the board's sidebar row and center-column page.
+ *
+ * Both seats are declared by shell plugins this package does not depend on at
+ * runtime, so each registration is wrapped in `ctx.slots.inject`: the callback
+ * runs only after the owning entry declares the seat, and a shell that never
+ * declares it leaves the board simply absent instead of failing boot.
+ * @param ctx - client root context (services: slots).
+ * @param controller - the board controller the page and the row drive.
+ * @returns disposer releasing both registrations.
+ */
+export declare function registerTaskBoardPanel(ctx: ClientContext, controller: BoardController): () => void;

package/lib/types/client/settings-entry-form.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Family settings form bound to the profile entry id a Host actually serves.
+ *
+ * Under the 0.1.7 settings model a form is addressed by PROFILE ENTRY ID, while
+ * a family card knows only its own settings namespace. The family binder
+ * (`ctx.get('webUiSettings')`, published by dsh-web-settings) resolves one onto
+ * the other and is the preferred transport; this module is the fallback for a
+ * page that serves no binder — the group plugin is not installed, or its client
+ * half has not applied yet (the aggregate mounts its children in order, and a
+ * child still waiting on its own injects publishes nothing).
+ *
+ * The shared describe mirror is the only local evidence of which row id this
+ * profile serves, but it answers asynchronously: at plugin activation it usually
+ * holds nothing yet. A one-shot guess therefore cannot be right for every
+ * deployment, and the form is bound once per session:
+ *
+ * - binding the bare namespace made every save answer `No configurable plugin
+ *   entry "<namespace>"` on an aggregate install (the namespace is not an entry
+ *   id there), which the card reported as "the deployment did not accept these
+ *   values";
+ * - binding the aggregate row id would break a standalone install, whose row id
+ *   is the namespace or the package's own `ui-*` row.
+ *
+ * So the fallback starts on the most likely row and REBINDS the moment the
+ * mirror names one of this package's rows. Until the mirror answers, the form
+ * reports the binding it holds (usually `loading`), which the card renders as an
+ * unavailable form rather than a doomed one.
+ */
+import type { ConfigForm, ConfigForms } from '@deepseek-ai/dsh-client-ui-settings/client';
+/** Options of {@link createServedEntryForm}. */
+export interface ServedEntryFormOptions<T> {
+    /** The shared configuration forms service (`ctx.configForms`). */
+    forms: ConfigForms;
+    /**
+     * Profile entry ids this package's rows carry, most likely first: the
+     * aggregate's generated row, the package's own standalone row, then the bare
+     * namespace. The first is the fallback while the mirror has no answer; the
+     * last is the answer when the mirror serves none of them.
+     */
+    entryIds: readonly string[];
+}
+/**
+ * Create a settings form bound to the profile entry id this Host serves, and
+ * rebound whenever the shared describe mirror names a different one of this
+ * package's rows.
+ * @param options - the shared forms service and this package's candidate row ids.
+ * @returns a form delegating to the currently resolved entry's own form.
+ */
+export declare function createServedEntryForm<T>(options: ServedEntryFormOptions<T>): ConfigForm<T>;

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

@@ -43,6 +43,19 @@ export interface SessionsControllerFace {
     /** Subscribe to catalog changes; selection ownership rides the same snapshot. */
     subscribe(fn: () => void): () => void;
 }
+/** Stable id shared by the board's sidebar panel row and its main-slot page. */
+export declare const TASK_BOARD_PANEL_ID = "task-board";
+/**
+ * The layout's panel-navigation face. The board no longer owns the center
+ * column at the DOM level: selecting the panel is the layout's business, and
+ * this is the one call that asks for it (null returns to the conversation).
+ * Optional, so a composition without the layout service keeps the board's
+ * pure state transitions testable.
+ */
+export interface PanelNavigationFace {
+    /** Select the board panel, or null to hand the column back to the conversation. */
+    select(panelId: string | null): void;
+}
 /** Controller dependencies (all swappable in tests). */
 export interface ControllerDeps {
     store: TaskStore;
@@ -53,6 +66,8 @@ export interface ControllerDeps {
     uuid?: () => string;
     /** Host-authoritative transport; absent keeps the legacy in-memory test path. */
     transport?: TaskBoardTransport;
+    /** Layout panel selection; absent keeps the board state-only (tests, shell-less hosts). */
+    panel?: PanelNavigationFace;
 }
 /**
  * Register one host directory as a DSH project (workspace). Wired by the
@@ -90,6 +105,12 @@ export interface ExecutionOptionsSnapshot {
     presets: readonly ExecutionPresetOption[];
     models?: readonly ExecutionModelOption[];
 }
+/**
+ * Host-owned state the browser mirrors. SSE frames carry the volatile subset
+ * (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'>;
 /** Immutable controller snapshot for UI subscriptions. */
 export interface ControllerSnapshot {
     tasks: readonly TaskRecord[];
@@ -105,7 +126,7 @@ export interface ControllerSnapshot {
     /** Whether this deployment can parse pasted text into task fields (issue #1540). */
     canParseTask?: boolean;
     transportError?: string;
-    host?: Pick<TaskBoardSnapshot, 'revision' | 'scheduler' | 'power' | 'sessionDefaultPermission'>;
+    host?: HostMirror;
 }
 /** The selected task (resolved from the ledger), or undefined. */
 export declare function selectedTaskOf(snapshot: ControllerSnapshot): TaskRecord | undefined;
@@ -143,9 +164,33 @@ export declare class BoardController {
     isHostBacked(): boolean;
     /** Retry initial migration/state synchronization after an explicit Host error. */
     retryHostSync(): Promise<boolean>;
+    /**
+     * 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
+     * with no layout face (tests, a shell-less host) still flips the state.
+     *
+     * The selection is requested AFTER the snapshot flips so a subscriber
+     * rendering against `boardOpen` never observes "open" while the shell still
+     * shows the conversation.
+     */
     openBoard(): void;
+    /**
+     * Return the center column to the conversation. The layout's own selection is
+     * the source of truth for what the column renders, so this asks for the
+     * conversation explicitly rather than only clearing local state.
+     */
     closeBoard(): void;
     toggleBoard(): void;
+    /**
+     * Reflect a panel selection that came from OUTSIDE this controller (the user
+     * clicked another sidebar row, or the layout dropped the panel id). Keeps
+     * `boardOpen` aligned with what the column actually shows without asking the
+     * layout to select anything back.
+     * @param panelId - the layout's current panel id, or null for the conversation.
+     */
+    syncPanelSelection(panelId: string | null): void;
+    /** Ask the layout to select a panel; a shell that serves no layout face is a no-op. */
+    private selectPanel;
     /**
      * Switch between the kanban columns and the archive view. Leaving the
      * archive view with an archived task still selected closes the selection —
@@ -195,6 +240,14 @@ export declare class BoardController {
      * @returns true when applied.
      */
     archiveTask(id: string): boolean;
+    /**
+     * Attach an existing task under a parent (or detach it with a null parent)
+     * through the Host. The lineage gate — parent exists and is on-board, no
+     * cycle, depth within the deployment limit — belongs to the Host; a refusal
+     * surfaces through the transport error like every other rejected action.
+     * @returns true when the link was accepted by the authority.
+     */
+    setParent(id: string, parentId: string | null): Promise<boolean>;
     /** Restore an archived task back onto the board (same status column). */
     restoreTask(id: string): boolean;
     /**
@@ -245,8 +298,8 @@ export declare class BoardController {
      * (background navigation, the Host runner creating and selecting a fresh
      * execution session, settlement, other plugins), so closing on `current`
      * changes would evict the board without the user asking. The board closes
-     * only on explicit user navigation: a sidebar session/workspace row click
-     * (board-mount onClickSidebarRow) or the board's own actions
+     * only on explicit user navigation: selecting another panel (the layout owns
+     * selection, and `syncPanelSelection` follows it) or the board's own actions
      * (openSession / close). Keeping the hook preserves the subscription
      * contract for future listeners.
      */
@@ -263,6 +316,21 @@ export declare class BoardController {
      * re-serialize the whole ledger per tab even while nothing changes.
      */
     private onRemoteEvent;
+    /**
+     * Deployment subtask depth limit the browser mirrors from the last Host
+     * snapshot; the fallback is the deployment default for the legacy path (no
+     * transport) and for the window before the first snapshot arrives.
+     */
+    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.
+     */
+    private mirrorOf;
     private refreshRemote;
     private acceptRemote;
     private notify;

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

@@ -0,0 +1,122 @@
+/**
+ * Subtask lineage: the depth gate, the ancestry/descendant queries, the
+ * cascade participant set one run request opens, the deferred settlement of a
+ * cascade parent, and the execution-target inheritance a subtask resolves at
+ * run time.
+ *
+ * Framework-free (no cordis, no runtime imports) so every rule is
+ * unit-testable in isolation. The Host ledger is the only authority; the
+ * browser mirrors these predicates to enable or disable controls, never to
+ * decide them.
+ */
+import type { ExecutionOutcome, ExecutionRecord, TaskRecord } from './tasks.ts';
+/** Lowest configurable subtask depth. */
+export declare const SUBTASK_DEPTH_MIN = 1;
+/** Highest configurable subtask depth. */
+export declare const SUBTASK_DEPTH_MAX = 3;
+/** Deployment default: one level of subtasks, and no subtask of a subtask. */
+export declare const DEFAULT_SUBTASK_DEPTH = 1;
+/**
+ * Clamp a configured depth into the supported range. Anything unusable
+ * (absent, non-numeric, not finite) falls back to the default, so a bad
+ * configuration narrows the tree instead of lifting the guard.
+ */
+export declare function normalizeSubtaskDepth(value: unknown): number;
+/** Whether an unknown value is a settled execution outcome. */
+export declare function isExecutionOutcome(value: unknown): value is ExecutionOutcome;
+/**
+ * Nearest-first ancestor chain of a task. The walk is cycle-safe and bounded
+ * by the ledger size rather than by the deployment maximum: a chain stored
+ * under a larger limit survives that limit being lowered, and restore and
+ * inheritance must still see all of it.
+ */
+export declare function ancestorChain(tasks: readonly TaskRecord[], task: TaskRecord): TaskRecord[];
+/** Root-to-task depth: a root task is 0, its subtask 1, and so on. */
+export declare function taskDepth(tasks: readonly TaskRecord[], id: string): number;
+/** Direct subtasks of a task, in ledger order. */
+export declare function directSubtasks(tasks: readonly TaskRecord[], id: string): TaskRecord[];
+/**
+ * Descendants of a task in breadth-first order, bounded by maxSubtaskDepth
+ * total depth. The visited set keeps a malformed ledger from looping.
+ */
+export declare function descendantTasks(tasks: readonly TaskRecord[], id: string, maxSubtaskDepth: number): TaskRecord[];
+/**
+ * Height of a task's own subtree (0 for a leaf), bounded by the hard maximum.
+ * The visited set makes the walk terminate on a cyclic hand-edited ledger
+ * instead of recursing until the stack overflows.
+ */
+export declare function subtreeHeight(tasks: readonly TaskRecord[], id: string, visited?: ReadonlySet<string>): number;
+/** Why a parent link was refused; also the source of the Host error text. */
+export type ParentLinkRejection = 'unknown-task' | 'unknown-parent' | 'archived-parent' | 'self-parent' | 'cycle' | 'depth-exceeded';
+export interface ParentLinkCheck {
+    /** True when the link (or the detachment) may be stored. */
+    ok: boolean;
+    /** Why it was refused; absent when ok. */
+    reason?: ParentLinkRejection;
+}
+/**
+ * Whether childId may be attached under parentId. A null parent detaches and
+ * is always allowed for a known task. Otherwise the link must name an
+ * on-board task that is neither the child itself nor one of its descendants,
+ * and the resulting depth (parent depth + 1 + the child own subtree height)
+ * must stay within maxSubtaskDepth.
+ */
+export declare function checkParentLink(tasks: readonly TaskRecord[], childId: string, parentId: string | null, maxSubtaskDepth: number): 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.
+ */
+export declare function cascadeTargets(tasks: readonly TaskRecord[], rootId: string, maxSubtaskDepth: number): TaskRecord[];
+/** One still-open execution belonging to a cascade run group. */
+export interface OpenCascadeChild {
+    taskId: string;
+    execution: ExecutionRecord;
+}
+/** The open execution of a task inside a run group, if it still exists. */
+export declare function openGroupExecution(task: TaskRecord, runGroupId: string): ExecutionRecord | undefined;
+/**
+ * The direct subtasks of parentTaskId whose execution in this run group is
+ * still open: the parent remaining waiters. The parent may settle once this
+ * list is empty and its own outcome is known.
+ */
+export declare function pendingCascadeChildren(tasks: readonly TaskRecord[], parentTaskId: string, runGroupId: string): OpenCascadeChild[];
+/**
+ * Fold a cascade parent own outcome and its children outcomes into one
+ * verdict: failure dominates, then cancellation, then success. The error text
+ * is the first failure, falling back to the first cancellation.
+ */
+export declare function combineCascadeOutcome(entries: readonly {
+    result: ExecutionOutcome;
+    error?: string;
+}[]): {
+    result: ExecutionOutcome;
+    error: string | undefined;
+};
+/**
+ * The permission a task would actually run under: its handover bundle's pin
+ * wins over the plain pin field, exactly as the runner resolves it.
+ */
+export declare function effectiveTaskPermission(task: TaskRecord): TaskRecord['permission'];
+/**
+ * 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.
+ */
+/**
+ * The immutable teammate name for one team-mode member. Teammate names are
+ * lower-kebab-case and must stay unique for the lifetime of the Team, so the
+ * run-group token is appended: two runs of the same tree never collide. A title
+ * with no ASCII word characters (a CJK title, for example) keeps a stable
+ * generic prefix and is still distinguished by the token.
+ * @param title - the member task's title.
+ * @param token - the run group id (the task id when no group is recorded).
+ * @returns the teammate name handed to the Agent Teams service.
+ */
+export declare function teammateName(title: string, token: string): string;
+export declare function resolveExecutionTargets(task: TaskRecord, tasks: readonly TaskRecord[], maxSubtaskDepth?: number): TaskRecord;

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

@@ -8,6 +8,8 @@ import type { FreezeSnapshot } from './freeze-snapshot.ts';
 import type { TaskHandover, TaskHandoverInput } from './handover.ts';
 /** Task lifecycle status, one per kanban column. */
 export type TaskStatus = 'backlog' | 'todo' | 'running' | 'done' | 'failed';
+/** Settled outcome of one execution attempt. */
+export type ExecutionOutcome = 'succeeded' | 'failed' | 'cancelled';
 /**
  * One real execution attempt: the run's own id, the dsh session that ran it
  * (filled once the session is created), and the settled outcome once the
@@ -23,7 +25,7 @@ export interface ExecutionRecord {
     /** When the run settled; absent while still running. */
     endedAt: number | undefined;
     /** Outcome once settled. */
-    result: 'succeeded' | 'failed' | 'cancelled' | undefined;
+    result: ExecutionOutcome | undefined;
     /** Human failure text when the run failed (prompt rejection or agent error). */
     error: string | undefined;
     /**
@@ -36,6 +38,20 @@ export interface ExecutionRecord {
     frozenAt?: number;
     /** Freeze source session captured from the card snapshot when the run opened. */
     frozenBy?: string;
+    /**
+     * Cascade run group shared by the parent execution and every descendant
+     * execution one run request opened. Absent on a plain single-task run.
+     */
+    runGroupId?: string;
+    /**
+     * A cascade parent's own session outcome, recorded as soon as its own turn
+     * settles and held while its subtask executions finish. The execution stays
+     * open (no `endedAt`) until the last child settles; the Host monitor skips
+     * an execution whose own outcome is already recorded.
+     */
+    ownResult?: ExecutionOutcome;
+    /** Human failure text that arrived with {@link ownResult}. */
+    ownError?: string;
 }
 /**
  * Maximum number of execution records retained per task. Older settled runs
@@ -140,6 +156,14 @@ export interface TaskRecord {
     description: string;
     /** The prompt sent to dsh when this task is executed. */
     prompt: string;
+    /**
+     * Parent task id: present only on a subtask. The Host owns the lineage gate
+     * (see `core/subtask.ts`), which refuses a cycle, an archived parent, and
+     * any link that would exceed `maxSubtaskDepth` — so every chain the Host
+     * wrote under the current setting is at most that many links long. Lowering
+     * the limit later neither rewrites nor deletes an already stored link.
+     */
+    parentId?: string;
     /** Current column. */
     status: TaskStatus;
     /** Creation instant (ms epoch). */
@@ -181,6 +205,15 @@ export interface TaskRecord {
      * {@link reusableSessionId}).
      */
     reuseSession?: boolean;
+    /**
+     * Run this task's subtree as an Agent Team instead of one Host-launched
+     * session per participant: the root becomes the Team Lead session and the
+     * Host spawns one teammate for each direct subtask inside it. Absent or false
+     * keeps the plain concurrent cascade. A deployment that does not serve the
+     * Agent Teams service refuses a team run instead of silently falling back,
+     * and a subtask's own permission pin cannot be honored in this mode.
+     */
+    teamRun?: boolean;
     /**
      * Frozen context snapshot for a continuation card; absent on plain tasks.
      * Sanitized before it enters the ledger (redaction, slash-command taint,
@@ -231,6 +264,12 @@ export interface NewTaskInput {
     title: string;
     description: string;
     prompt: string;
+    /**
+     * Parent task id, turning this creation into a subtask. Absent keeps a root
+     * task; the create use case validates the link (existence, depth) and
+     * inherits the parent's unset execution targets.
+     */
+    parentId?: string;
     /** Workspace the execution must run in; empty/absent = the recent workspace. */
     workspaceId?: string;
     /** Agent preset the execution session must be composed from; empty/absent = deployment default. */
@@ -241,6 +280,8 @@ export interface NewTaskInput {
     model?: string;
     /** Reuse the previous execution's session for later runs (issue #1419). */
     reuseSession?: boolean;
+    /** Run the subtree as an Agent Team (Team Lead session plus one teammate per direct subtask). */
+    teamRun?: boolean;
     /**
      * Optional scheduled-run rule requested at creation time (the new-task
      * dialog): an enable flag plus a 5-field cron expression. The create use
@@ -308,8 +349,10 @@ export declare function withSchedule(task: TaskRecord, patch: Partial<ScheduleRu
 /**
  * Open a fresh execution on a task: move it to 'running' and append a
  * running execution record. Returns the new task and the new execution.
+ * @param runGroupId - cascade run group, when this run also opened executions
+ *   for the task's subtasks (see `core/subtask.ts`).
  */
-export declare function startExecution(task: TaskRecord, now: number, executionId: string, initiatedBy?: string): {
+export declare function startExecution(task: TaskRecord, now: number, executionId: string, initiatedBy?: string, runGroupId?: string): {
     task: TaskRecord;
     execution: ExecutionRecord;
 };
@@ -318,6 +361,6 @@ export declare function startExecution(task: TaskRecord, now: number, executionI
  * matching column. No-op (returns the input task) when the execution is not
  * the task's latest or is already settled.
  */
-export declare function settleExecution(task: TaskRecord, executionId: string, outcome: 'succeeded' | 'failed' | 'cancelled', now: number, error: string | undefined): TaskRecord;
+export declare function settleExecution(task: TaskRecord, executionId: string, outcome: ExecutionOutcome, now: number, error: string | undefined): TaskRecord;
 /** A settled-execution summary string for the detail view. */
 export declare function executionLabel(execution: ExecutionRecord): string;

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

@@ -1,9 +1,3 @@
-/**
- * Archive/restore task use case: move a task off the main board and back,
- * whatever its status but `running`. The task keeps its status, execution history, and
- * transcript references, while archiving disarms any schedule so it cannot
- * create more execution records until the user restores and re-enables it.
- */
 import type { TaskRecord } from '../tasks.ts';
 /** Result of an archive transition. */
 export interface ArchiveTaskResult {
@@ -13,11 +7,14 @@ export interface ArchiveTaskResult {
     archived: boolean;
 }
 /**
- * Archive one task: only a `running` task stays on the board (its runner
- * still owns its lifecycle until the execution settles); every other status
- * can be archived. Archiving disarms a schedule; already-archived tasks are
- * a no-op.
+ * Archive one task and its subtasks: only a running member keeps the group on
+ * the board (its runner still owns its lifecycle until the execution settles);
+ * any other status can be archived. Archiving disarms schedules; an
+ * already-archived task is a no-op.
+ */
+export declare function applyArchiveTask(tasks: readonly TaskRecord[], id: string, now: number, maxSubtaskDepth?: number): ArchiveTaskResult;
+/**
+ * Restore one task back onto the main board, together with its ancestors (an
+ * on-board subtask must not point at an archived parent) and its subtasks.
  */
-export declare function applyArchiveTask(tasks: readonly TaskRecord[], id: string, now: number): ArchiveTaskResult;
-/** Restore one task back onto the main board (clears the archive marker). */
-export declare function applyRestoreTask(tasks: readonly TaskRecord[], id: string, now: number): ArchiveTaskResult;
+export declare function applyRestoreTask(tasks: readonly TaskRecord[], id: string, now: number, maxSubtaskDepth?: number): ArchiveTaskResult;