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

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

@@ -0,0 +1,283 @@
+/**
+ * The task board's external provider extension contract.
+ *
+ * This module is the single source of truth for how another plugin adds a
+ * provider surface to the task board: the cordis service name both halves
+ * publish, the API version they negotiate, the child seats a provider renders
+ * into, the host capability face a provider implements against, and the client
+ * capability face the board's browser half provides. It is framework-free and
+ * shared by the host and browser programs; the only imported SDK type is
+ * type-only, so the browser bundle never pulls a value out of an SDK package.
+ *
+ * @module dsh-task-board/core/extension
+ */
+import type { ToolDefinition } from '@deepseek-ai/dsh-tools';
+import type { ExecutionOutcome, TaskRecord, TaskStatus } from './tasks.ts';
+/** Cordis service name the host and browser halves each publish. */
+export declare const TASK_BOARD_SERVICE_NAME = "taskBoard";
+/**
+ * Contract version of {@link TASK_BOARD_SERVICE_NAME}. A provider declares the
+ * version it was built against; the board refuses (visibly) any other version
+ * instead of guessing at a stale shape.
+ */
+export declare const TASK_BOARD_API_VERSION = 1;
+/** Child seat a provider registers its task-detail section into. */
+export declare const TASK_BOARD_DETAIL_SECTION = "task-board.detail.section";
+/** Child seat a provider registers its settings section into. */
+export declare const TASK_BOARD_SETTINGS_SECTION = "task-board.settings.section";
+/** Child seat a provider registers its card decoration into. */
+export declare const TASK_BOARD_CARD_DECORATION = "task-board.card.decoration";
+/** Every child seat the board declares for extensions, in render order. */
+export declare const TASK_BOARD_EXTENSION_SEATS: readonly string[];
+/**
+ * Largest accepted extension payload, in bytes of its JSON serialization. One
+ * integration entry — and one action payload — may carry schema the board does
+ * not interpret, but never enough of it to bloat the ledger or the action
+ * channel.
+ */
+export declare const TASK_BOARD_PAYLOAD_LIMIT_BYTES: number;
+/** One opaque provider payload the board stores and forwards without interpreting. */
+export type TaskBoardExtensionPayload = Record<string, unknown>;
+/**
+ * Validate one extension payload: a pure JSON object whose serialization fits
+ * {@link TASK_BOARD_PAYLOAD_LIMIT_BYTES}. Arrays, primitives and non-plain
+ * objects are refused; the board never interprets the keys.
+ * @param value - candidate payload.
+ * @returns whether the value is an acceptable opaque payload.
+ */
+export declare function isTaskBoardExtensionPayload(value: unknown): value is TaskBoardExtensionPayload;
+/** Byte length of a value's JSON serialization, or undefined when it does not serialize. */
+export declare function taskBoardPayloadBytes(value: unknown): number | undefined;
+/**
+ * Normalize a task's whole integrations container: a plain JSON object whose
+ * values are each an opaque provider payload within the size limit. A malformed
+ * container normalizes to undefined (the field is dropped), and one malformed
+ * entry is dropped alone so a single bad provider can never take a card — or
+ * another provider's data — with it.
+ * @param value - candidate container from the wire, the ledger, or a create input.
+ * @returns the cleaned container, or undefined when nothing usable remains.
+ */
+export declare function normalizeTaskIntegrations(value: unknown): Record<string, TaskBoardExtensionPayload> | undefined;
+/** One action a provider dispatches over the board's same-origin channel. */
+export interface TaskBoardExtensionActionRequest {
+    /** Id of the extension the action belongs to. */
+    extensionId: string;
+    /** Provider-owned action name, routed back to that extension's handleAction. */
+    action: string;
+    /** Task the action targets, when it targets one. */
+    taskId?: string;
+    /** Opaque provider payload, bounded like every other extension payload. */
+    payload?: TaskBoardExtensionPayload;
+}
+/**
+ * Deliver one extension action through the board's same-origin action channel.
+ * The extension never opens an HTTP surface of its own.
+ */
+export type TaskBoardExtensionDispatch = (request: TaskBoardExtensionActionRequest) => Promise<boolean>;
+/** Draft one provider creates a task from. */
+export interface TaskBoardTaskDraft {
+    title: string;
+    description: string;
+    prompt: string;
+    /** Column the created card opens in; absent means the board default (todo). */
+    status?: TaskStatus;
+    /** Parent card id, when the provider materializes a subtask. */
+    parentId?: string;
+    /**
+     * Workspace the execution must run in. Absent leaves the board's own
+     * inheritance rules in charge (the creating session's workspace for a root
+     * card, else the recent workspace at execution time), so a provider that has
+     * no reason to know better pins nothing.
+     */
+    workspaceId?: string;
+}
+/** Options of {@link TaskBoardTasksFace.create}. */
+export interface TaskBoardCreateOptions {
+    /** Opaque payload stored under the creating extension's id. */
+    payload?: TaskBoardExtensionPayload;
+    /** Create the card off-board: it exists in the ledger but is never shown on the board. */
+    hidden?: boolean;
+}
+/** One task linked to an extension, with that extension's own payload. */
+export interface TaskBoardLinkedTask {
+    task: TaskRecord;
+    payload: TaskBoardExtensionPayload;
+}
+/** Task reads and writes the board grants an extension. */
+export interface TaskBoardTasksFace {
+    /** Every task in the ledger, most recent mutation last. */
+    list(): readonly TaskRecord[];
+    /** One task by id, or undefined. */
+    get(taskId: string): TaskRecord | undefined;
+    /**
+     * Create a task through the board's own creation gate; the payload lands
+     * under the creating extension's id. Throws on a refused draft.
+     */
+    create(draft: TaskBoardTaskDraft, options?: TaskBoardCreateOptions): TaskRecord;
+    /**
+     * Patch a task's content. Reuses the board's own content gate: a task that
+     * has started executing keeps its recorded title/description/prompt.
+     * Throws when the card is frozen.
+     */
+    patchContent(taskId: string, patch: {
+        title?: string;
+        description?: string;
+        prompt?: string;
+    }): void;
+    /**
+     * Move a task through the board's existing status gates (running lock,
+     * permission confirmation gate). Throws on refusal.
+     */
+    setStatus(taskId: string, status: TaskStatus, initiator?: string): void;
+    /** Every task carrying this extension's payload. */
+    linked(): readonly TaskBoardLinkedTask[];
+}
+/** Storage face for one extension's own payload on a task. */
+export interface TaskBoardIntegrationFace {
+    /** Read this extension's payload, or undefined when the task carries none. */
+    read(taskId: string): TaskBoardExtensionPayload | undefined;
+    /**
+     * Shallow-merge this extension's payload into the task: the given keys
+     * replace the stored ones, and a key explicitly set to undefined clears it.
+     * The board stores the result opaquely; a non-JSON or oversized payload is
+     * refused.
+     */
+    write(taskId: string, payload: TaskBoardExtensionPayload): void;
+}
+/** Status-change notification. */
+export interface TaskBoardStatusChangedEvent {
+    taskId: string;
+    status: TaskStatus;
+    previous: TaskStatus;
+    initiator?: string;
+}
+/** Execution-settlement notification. */
+export interface TaskBoardExecutionSettledEvent {
+    taskId: string;
+    executionId: string;
+    outcome: ExecutionOutcome;
+    error?: string;
+}
+/** Task-deletion notification. */
+export interface TaskBoardTaskDeletedEvent {
+    taskId: string;
+}
+/**
+ * Event subscriptions an extension registers for. Every callback runs isolated:
+ * a throw is logged and never interrupts the board's own execution path.
+ */
+export interface TaskBoardEventFace {
+    onStatusChanged(callback: (event: TaskBoardStatusChangedEvent) => void): () => void;
+    onExecutionSettled(callback: (event: TaskBoardExecutionSettledEvent) => void): () => void;
+    onTaskDeleted(callback: (event: TaskBoardTaskDeletedEvent) => void): () => void;
+}
+/**
+ * Host capability face handed to one extension while it is started. The face
+ * lives for the extension's enabled lifetime; the board revokes it by calling
+ * the extension's stop().
+ */
+export interface TaskBoardExtensionHost {
+    tasks: TaskBoardTasksFace;
+    integration: TaskBoardIntegrationFace;
+    events: TaskBoardEventFace;
+    /**
+     * Publish this extension's read-only summary; it lands in the snapshot's
+     * extensions[id] for the extension's browser half to render.
+     */
+    publish(summary: TaskBoardExtensionPayload): void;
+    /** Register one model-visible tool; the returned disposer unregisters it. */
+    registerTool(definition: ToolDefinition): () => void;
+}
+/** One external provider contributed to the task board. */
+export interface TaskBoardExtension {
+    /** Stable extension id; also the key of this extension's integration payload. */
+    readonly id: string;
+    /** Contract version this extension was built against. */
+    readonly apiVersion: number;
+    /** Volatile per-extension switch; absent means enabled. Read at use time. */
+    enabled?(): boolean;
+    /** Acquire the capability face and start any provider-side work. */
+    start?(host: TaskBoardExtensionHost): void;
+    /** Release provider-side work. Never clears stored data. */
+    stop?(): void;
+    /** Route one dispatched action; the returned value goes back to the dispatcher. */
+    handleAction?(request: TaskBoardExtensionActionRequest): unknown | Promise<unknown>;
+}
+/** Board mirror an extension's browser half observes. */
+export interface TaskBoardClientMirror {
+    /** Whether the board's master switch currently runs the extension faces. */
+    enabled: boolean;
+    /** Tasks the board currently holds. */
+    tasks: readonly TaskRecord[];
+    /** Published extension summaries, keyed by extension id (opaque to the board). */
+    extensions: Readonly<Record<string, unknown>>;
+}
+/** Whether a task should be shown on the board; false hides it. */
+export type TaskBoardVisibilityPredicate = (task: TaskRecord) => boolean;
+/**
+ * Client capability face the board's browser half provides. A provider's
+ * browser half resolves it from the shared cordis service name; it never
+ * value-imports the board package.
+ */
+export interface TaskBoardClientFace {
+    /** Deliver one action through the board's same-origin action channel. */
+    dispatch(request: TaskBoardExtensionActionRequest): Promise<boolean>;
+    /** Register one card visibility predicate; the returned disposer removes it. */
+    registerVisibility(predicate: TaskBoardVisibilityPredicate): () => void;
+    /** Subscribe to the board mirror. */
+    subscribe(callback: (mirror: TaskBoardClientMirror) => void): () => void;
+    /** Read the current board mirror. */
+    snapshot(): TaskBoardClientMirror;
+}
+/** Owner props of the task-detail seat. */
+export interface TaskBoardDetailSectionProps {
+    task: TaskRecord;
+    dispatch: TaskBoardExtensionDispatch;
+}
+/** Owner props of the settings seat. */
+export interface TaskBoardSettingsSectionProps {
+    dispatch: TaskBoardExtensionDispatch;
+}
+/** Owner props of the card-decoration seat. */
+export interface TaskBoardCardDecorationProps {
+    task: TaskRecord;
+}
+/**
+ * Host-half service face published under {@link TASK_BOARD_SERVICE_NAME}. A
+ * provider package's host half resolves this from the shared cordis service
+ * and registers its extension; the board's ledger never crosses this boundary.
+ */
+export interface TaskBoardHostFace {
+    /**
+     * Admit one provider extension. Idempotent by extension id; the returned
+     * disposer releases it without clearing stored data.
+     */
+    registerExtension(extension: TaskBoardExtension): () => void;
+    /** Whether the board currently runs a given extension (board x extension). */
+    isExtensionEnabled(extensionId: string): boolean;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /**
+         * The board's extension service. The host half publishes
+         * {@link TaskBoardHostFace}; the browser half publishes
+         * {@link TaskBoardClientFace} under the same name. The two halves never run
+         * in one process, so the browser half resolves its face through
+         * {@link resolveTaskBoardClientFace} and this shared declaration names the
+         * host face that registration-side consumers type against.
+         */
+        taskBoard: TaskBoardHostFace;
+    }
+}
+/** The narrow context seat {@link resolveTaskBoardClientFace} needs. */
+export interface TaskBoardClientContextSeat {
+    get(name: string): unknown;
+}
+/**
+ * Resolve the browser half's client capability face by service name. Returns
+ * undefined when the board is not loaded or the service is not served, so a
+ * provider's browser half can degrade instead of throwing.
+ * @param ctx - client context.
+ * @returns the client face, or undefined.
+ */
+export declare function resolveTaskBoardClientFace(ctx: TaskBoardClientContextSeat): TaskBoardClientFace | undefined;

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

@@ -35,7 +35,11 @@ export declare const HANDOVER_MAX_REFERENCE_BYTES = 512;
 export declare const HANDOVER_MAX_TOTAL_BYTES: number;
 /** Per target-id (workspace/preset) byte cap. */
 export declare const HANDOVER_MAX_TARGET_BYTES = 256;
-/** The board's notion of the deployment session-default permission (fail-safe default). */
+/**
+ * Fail-safe baseline for the confirmation gate: what it falls back to when the
+ * deployment pins no baseline of its own and the Host's default permission
+ * preset cannot be read. Every elevation above it stays gated.
+ */
 export declare const DEFAULT_SESSION_PERMISSION: TaskPermission;
 /** Permission elevation rank (higher = more authority). */
 export declare const PERMISSION_RANK: ReadonlyMap<TaskPermission, number>;
@@ -51,6 +55,14 @@ export declare function handoverOf(input: TaskHandoverInput, now: number): TaskH
 export declare function effectivePermission(task: Pick<TaskRecord, 'permission' | 'handover'>): TaskPermission | undefined;
 /** Whether a binding's permission is elevated above the session default. */
 export declare function exceedsSessionDefault(permission: TaskPermission | undefined, sessionDefault: TaskPermission): boolean;
+/**
+ * Whether a session running at `holder` already carries `permission`: the
+ * permission is absent, or its rank does not exceed the holder's. A teammate
+ * inherits the Lead session's permission and cannot be narrowed below it, so a
+ * subtask's own pin is carried by a team run exactly when this holds, and a pin
+ * it does not carry would be silently dropped instead.
+ */
+export declare function permissionCarriedBy(holder: TaskPermission, permission: TaskPermission | undefined): boolean;
 /**
  * The confirmation-gate predicate: an elevated permission without a human
  * confirmation stamp. Manual run/rerun and cron must refuse such a card.

package/lib/types/core/issue-form.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Issue-form vocabulary the card excerpt recognizes.
+ *
+ * Issue forms from an issue tracker (and the zh templates this family's repositories use)
+ * write the same section headings and empty-field placeholders on every issue.
+ * The patterns are data about those forms, not UI copy, so they live in the
+ * shared core rather than in a locale dictionary; the browser half imports them.
+ *
+ * @module @linxin666/dsh-client-ui-task-board/core/issue-form
+ */
+/** Section headings whose body is the issue's own summary (zh and en forms). */
+export declare const SUMMARY_HEADING: RegExp;
+/** Values an issue form writes for an empty field. */
+export declare const EMPTY_FIELD: RegExp;
+/** A trailing colon (ASCII or full-width) after a heading. */
+export declare const HEADING_COLON: RegExp;

package/lib/types/core/package-name.d.ts

@@ -0,0 +1,9 @@
+/**
+ * npm identity of this plugin. The dsh-web-all degraded ledger is keyed by the
+ * real plugin package name of a family row, and this plugin's browser half
+ * must name its OWN row there to learn why its Host API is missing (issue
+ * #1730): the served bundle cannot derive the name, because a family row
+ * mounts the package from a versioned profile path. The host half spells the
+ * same name in its single-mount guard (src/index.ts); the two move together.
+ */
+export declare const TASK_BOARD_PACKAGE = "@linxin666/dsh-client-ui-task-board";

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

@@ -1,15 +1,36 @@
 /**
- * Minimal 5-field cron parsing and next-run computation for scheduled task
- * runs. Framework-free and dependency-free so the scheduler and controller
- * share one tiny pure module.
+ * Zone-aware 5-field cron parsing and next-run computation for scheduled task
+ * runs. Framework-free and dependency-free (Intl only) so the Host scheduler
+ * and the browser next-run preview share one tiny pure module.
  *
  * Grammar: five whitespace-separated fields, 分 时 日 月 周. Every field
  * supports the wildcard, step (wildcard or range + "/n"), single value,
  * inclusive range a-b, and comma lists mixing any of those. Ranges: minutes
  * 0-59, hours 0-23, days 1-31, months 1-12, weekdays 0-7 (0 and 7 both mean
- * Sunday). When both the day and weekday fields are restricted they combine
- * with OR semantics (standard cron). Invalid expressions parse to null and
- * are rejected by the UI/controller.
+ * Sunday). Invalid expressions parse to null and are rejected by the UI and
+ * the Host.
+ *
+ * Day semantics follow Vixie cron: a field is *starred* when its field text
+ * starts with `*`. When day-of-month and day-of-week are both restricted the
+ * fields combine with OR; otherwise they combine with AND. The distinction
+ * matters for a stepped star such as `*/2`, which still restricts the dates it
+ * matches, so `0 0 */2 * 1` means "the Mondays that fall on an even day of
+ * month" rather than "every even day, or every Monday".
+ *
+ * Time zone: every candidate wall clock is interpreted in an explicit IANA
+ * zone (the schedule's stored zone, or the Host zone when none is given).
+ * A wall clock that does not exist (spring-forward gap) is skipped, and an
+ * ambiguous wall clock (fall-back overlap) resolves to the earlier instant, so
+ * a repeated local minute fires exactly once. The Host-scheduler semantics are
+ * byte-identical to `@deepseek-ai/dsh-schedule`'s resolver, which was verified
+ * against it across twelve IANA zones (including 30-minute and 45-minute DST
+ * offsets and a date-line jump) and 300k decision instants.
+ *
+ * That upstream is on the experimental track and is NOT a dependency here (no
+ * import, no inject, no peer range), so a change to it fails no test. Re-run the
+ * differential check on any `dsh-schedule` release or cohort bump that moves it,
+ * and keep this comment honest; the re-verification trigger is recorded in
+ * [the owning Agent Note](../../../../.agents/notes/implemented/feature/2026-09-29-task-board-schedule-time-zone.md).
  */
 /** The parsed match sets of one cron expression. */
 export interface CronSchedule {
@@ -19,11 +40,61 @@ export interface CronSchedule {
     months: ReadonlySet<number>;
     /** Weekdays 0-6, 0 = Sunday (input 7 normalized to 0). */
     weekdays: ReadonlySet<number>;
-    /** Whether the day-of-month field was the literal '*' (unrestricted). */
-    dayWildcard: boolean;
-    /** Whether the weekday field was the literal '*' (unrestricted). */
-    weekdayWildcard: boolean;
+    /** Whether the day-of-month field text starts with `*` (Vixie starred). */
+    dayStarred: boolean;
+    /** Whether the weekday field text starts with `*` (Vixie starred). */
+    weekdayStarred: boolean;
+}
+/** Fallback zone when the process reports no usable IANA zone. */
+export declare const HOST_TIME_ZONE_FALLBACK = "UTC";
+/** One resolved wall-clock reading in some zone. */
+export interface ZonedParts {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
 }
+/**
+ * The wall-clock reading of one instant in an explicit zone. Reading through
+ * Intl (rather than the process `Date` accessors) is what makes the result
+ * independent of the Host's own TZ.
+ * @param timeZone - explicit IANA zone.
+ * @param epochMs - instant to read.
+ * @returns the zone-local calendar and clock fields.
+ */
+export declare function partsInZone(timeZone: string, epochMs: number): ZonedParts;
+/**
+ * Resolve a wall clock in an explicit zone to its instant.
+ *
+ * The offset is probed a day either side of the naive guess so both DST
+ * transitions are covered, then every candidate offset whose inverse maps back
+ * to the requested wall clock is kept. No survivor means the wall clock does
+ * not exist (a spring-forward gap); several means it is ambiguous (a fall-back
+ * overlap), and the earliest instant wins so the repeated clock is taken once.
+ * @param timeZone - explicit IANA zone.
+ * @param year - full calendar year.
+ * @param month - 1-12.
+ * @param day - day of month.
+ * @param hour - 0-23.
+ * @param minute - 0-59.
+ * @returns the instant in ms epoch, or undefined when the wall clock is skipped.
+ */
+export declare function zonedEpoch(timeZone: string, year: number, month: number, day: number, hour: number, minute: number): number | undefined;
+/**
+ * The Host process's IANA zone, used for schedules that store no zone of their
+ * own (a ledger written before zones were persisted).
+ * @returns a zone name Intl accepts, never empty.
+ */
+export declare function resolveHostTimeZone(): string;
+/**
+ * Whether a value names a zone this runtime can actually resolve. A stored
+ * zone is trusted only after it round-trips through Intl, so a typo or a zone
+ * that this ICU build does not know can never arm a schedule.
+ * @param value - candidate zone name.
+ * @returns true when the name is usable.
+ */
+export declare function isValidTimeZone(value: string): boolean;
 /**
  * Parse a 5-field cron expression.
  * @returns the match sets, or null when the expression is invalid.
@@ -32,18 +103,22 @@ export declare function parseCron(expr: string): CronSchedule | null;
 /** Whether the expression parses. */
 export declare function isValidCron(expr: string): boolean;
 /**
- * Compute the next matching instant after `fromMs` (ms epoch), in local time,
- * at minute granularity, strictly greater than `fromMs`. Returns the ms epoch
- * of the matching minute's start, or undefined when the calendar constraint
- * can never match (for example `0 0 30 2 *`). The five-year horizon includes
- * a full leap cycle, so a valid February 29 schedule remains reachable from
- * every non-leap year.
+ * Compute the next matching instant after `fromMs` strictly greater than it,
+ * interpreting the expression's wall clock in `timeZone` (the Host zone when
+ * omitted). Returns the ms epoch of the matching minute's start, or undefined
+ * when the calendar constraint can never match (for example `0 0 30 2 *`).
+ * The five-year horizon includes a full leap cycle, so a valid February 29
+ * schedule remains reachable from every non-leap year.
  *
  * Walks candidate year/month/day/hour/minute values straight from the parsed
  * field sets instead of scanning every minute: a sparse expression such as
  * `0 0 29 2 *` used to iterate ~1.5M wall-clock minutes before reaching the
- * next leap day. Wall-clock field construction + the final `matches` re-check
- * preserve the old minute scan's DST semantics exactly (nonexistent spring
- * minutes normalize forward and the repeated fall-back hour is never visited).
+ * next leap day. A candidate wall clock that the zone skips (spring-forward
+ * gap) is passed over, which is what makes the gap semantics fall out of the
+ * candidate walk rather than needing a separate rule.
+ * @param expr - 5-field cron expression.
+ * @param fromMs - exclusive lower bound, ms epoch.
+ * @param timeZone - explicit IANA zone; defaults to the Host zone.
+ * @returns the next trigger instant, or undefined when unreachable.
  */
-export declare function nextRunAtMs(expr: string, fromMs: number): number | undefined;
+export declare function nextRunAtMs(expr: string, fromMs: number, timeZone?: string): number | undefined;

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

@@ -24,28 +24,40 @@ export declare const DEFAULT_SUBTASK_DEPTH = 1;
 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;
+/**
+ * Reusable lineage index over ONE task list: the id lookup and the direct
+ * children per parent. A caller that runs several lineage queries over the same
+ * ledger (the link-subtask candidate gate runs one per task) builds this once
+ * instead of rescanning the list per query.
+ */
+export interface LineageIndex {
+    readonly byId: ReadonlyMap<string, TaskRecord>;
+    readonly childrenByParent: ReadonlyMap<string, readonly TaskRecord[]>;
+}
+/** Build the reusable index for a task list (ledger order preserved). */
+export declare function buildLineageIndex(tasks: readonly TaskRecord[]): LineageIndex;
 /**
  * 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[];
+export declare function ancestorChain(tasks: readonly TaskRecord[], task: TaskRecord, lineage?: LineageIndex): 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;
+export declare function taskDepth(tasks: readonly TaskRecord[], id: string, lineage?: LineageIndex): number;
 /** Direct subtasks of a task, in ledger order. */
-export declare function directSubtasks(tasks: readonly TaskRecord[], id: string): TaskRecord[];
+export declare function directSubtasks(tasks: readonly TaskRecord[], id: string, lineage?: LineageIndex): 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[];
+export declare function descendantTasks(tasks: readonly TaskRecord[], id: string, maxSubtaskDepth: number, lineage?: LineageIndex): 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;
+export declare function subtreeHeight(tasks: readonly TaskRecord[], id: string, visited?: ReadonlySet<string>, lineage?: LineageIndex): 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 {
@@ -61,7 +73,7 @@ export interface ParentLinkCheck {
  * 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;
+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
@@ -110,13 +122,20 @@ export declare function effectiveTaskPermission(task: TaskRecord): TaskRecord['p
  */
 /**
  * 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.
+ * lower-kebab-case and must stay unique for the lifetime of the Team: the
+ * run-group token separates two runs of the same tree, and the member
+ * discriminator separates two members of one run that reduce to the same slug.
+ *
+ * The discriminator is not cosmetic. A title with no ASCII word characters (a
+ * CJK title, for example) carries no slug at all, so every such title of one
+ * run group collides on the generic prefix; Agent Teams answers every member
+ * after the first with `teammate name "..." was already used in this Team`,
+ * and those subtasks never start. Two ASCII titles that share a slug
+ * (`AI 强度预测` next to `AI 配比优化`) collide the same way.
  * @param title - the member task's title.
  * @param token - the run group id (the task id when no group is recorded).
+ * @param memberId - the member task's id, which makes the name unique in the run.
  * @returns the teammate name handed to the Agent Teams service.
  */
-export declare function teammateName(title: string, token: string): string;
+export declare function teammateName(title: string, token: string, memberId?: string): string;
 export declare function resolveExecutionTargets(task: TaskRecord, tasks: readonly TaskRecord[], maxSubtaskDepth?: number): TaskRecord;