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

package/src/core/controller.ts

@@ -17,7 +17,9 @@ import { applyArchiveTask, applyRestoreTask } from './use-cases/task-archive.ts'
 import { applyCreateTask } from './use-cases/task-create.ts'
 import { applyDeleteTask } from './use-cases/task-delete.ts'
 import { applyScheduleNextRun as applyScheduleRollForward, applySetSchedule } from './use-cases/task-schedule.ts'
+import { applySetParent } from './use-cases/task-parent.ts'
 import { applyUpdateTask, type TaskUpdatePatch } from './use-cases/task-update.ts'
+import { DEFAULT_SUBTASK_DEPTH } from './subtask.ts'
 import type {
   TaskBoardAction,
   TaskBoardEventPayload,
@@ -60,6 +62,21 @@ function currentOf(sessions: SessionsControllerFace | undefined): string | undef
   return sessions?.current()
 }
 
+/** Stable id shared by the board's sidebar panel row and its main-slot page. */
+export 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
@@ -70,6 +87,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
 }
 
 /**
@@ -111,6 +130,13 @@ export interface ExecutionOptionsSnapshot {
   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[]
@@ -126,7 +152,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. */
@@ -173,7 +199,7 @@ export class BoardController {
   private readonly pendingTaskIds = new Set<string>()
   private readonly taskQueues = new Map<string, Promise<void>>()
   private transportError: string | undefined
-  private hostState: Pick<TaskBoardSnapshot, 'revision' | 'scheduler' | 'power' | 'sessionDefaultPermission'> | undefined
+  private hostState: HostMirror | undefined
   private remoteSubscribed = false
   private remoteInitialization: Promise<boolean> | undefined
 
@@ -244,15 +270,31 @@ export class BoardController {
 
   // --- view state -------------------------------------------------------------
 
+  /**
+   * 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 {
     if (this.boardOpen) return
     this.boardOpen = true
     this.notify()
+    this.selectPanel(TASK_BOARD_PANEL_ID)
   }
 
+  /**
+   * 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 {
     this.boardOpen = false
     this.notify()
+    this.selectPanel(null)
   }
 
   toggleBoard(): void {
@@ -260,6 +302,30 @@ export class BoardController {
     else this.openBoard()
   }
 
+  /**
+   * 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 {
+    const open = panelId === TASK_BOARD_PANEL_ID
+    if (open === this.boardOpen) return
+    this.boardOpen = open
+    this.notify()
+  }
+
+  /** Ask the layout to select a panel; a shell that serves no layout face is a no-op. */
+  private selectPanel(panelId: string | null): void {
+    try {
+      this.deps.panel?.select(panelId)
+    } catch {
+      // The layout service throws by contract before its root entry mounts;
+      // the state flip above already stands, and the next selection retries.
+    }
+  }
+
   /**
    * Switch between the kanban columns and the archive view. Leaving the
    * archive view with an archived task still selected closes the selection —
@@ -291,7 +357,7 @@ export class BoardController {
 
   createTask(input: NewTaskInput): TaskRecord | undefined {
     const id = this.uuid()
-    const { task, tasks } = applyCreateTask(this.tasks, input, this.now(), id)
+    const { task, tasks } = applyCreateTask(this.tasks, input, this.now(), id, this.mirrorDepth())
     if (task === undefined) return undefined
     this.tasks = [...tasks]
     this.persistAndNotify()
@@ -302,7 +368,10 @@ export class BoardController {
   async createTaskConfirmed(input: NewTaskInput): Promise<TaskRecord | undefined> {
     if (this.deps.transport === undefined) return this.createTask(input)
     const id = this.uuid()
-    const preview = applyCreateTask(this.tasks, input, this.now(), id).task
+    // The preview must obey the SAME lineage gate the Host will: a browser-side
+    // default of one level would reject a legal subtask-of-subtask before the
+    // request is ever sent.
+    const preview = applyCreateTask(this.tasks, input, this.now(), id, this.mirrorDepth()).task
     if (preview === undefined) return undefined
     return await this.commitRemote({ kind: 'create', id, input }, id)
       ? this.tasks.find(task => task.id === id)
@@ -392,7 +461,7 @@ export class BoardController {
    * @returns true when applied.
    */
   archiveTask(id: string): boolean {
-    const { tasks, archived } = applyArchiveTask(this.tasks, id, this.now())
+    const { tasks, archived } = applyArchiveTask(this.tasks, id, this.now(), this.mirrorDepth())
     if (!archived) return false
     if (this.deps.transport !== undefined) {
       void this.commitRemote({ kind: 'archive', taskId: id }, id)
@@ -403,9 +472,27 @@ export class BoardController {
     return true
   }
 
+  /**
+   * 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.
+   */
+  async setParent(id: string, parentId: string | null): Promise<boolean> {
+    if (this.deps.transport === undefined) {
+      const result = applySetParent(this.tasks, id, parentId, this.now(), this.mirrorDepth())
+      if (!result.applied) return false
+      this.tasks = [...result.tasks]
+      this.persistAndNotify()
+      return true
+    }
+    return await this.commitRemote({ kind: 'set-parent', taskId: id, parentId }, id)
+  }
+
   /** Restore an archived task back onto the board (same status column). */
   restoreTask(id: string): boolean {
-    const { tasks, archived } = applyRestoreTask(this.tasks, id, this.now())
+    const { tasks, archived } = applyRestoreTask(this.tasks, id, this.now(), this.mirrorDepth())
     if (!archived) return false
     if (this.deps.transport !== undefined) {
       void this.commitRemote({ kind: 'restore', taskId: id }, id).then(restored => {
@@ -517,8 +604,8 @@ export 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.
    */
@@ -604,13 +691,44 @@ export class BoardController {
     if (event !== undefined && this.hostState !== undefined && event.revision === this.hostState.revision
       && typeof event.scheduler === 'object' && event.scheduler !== null
       && typeof event.power === 'object' && event.power !== null) {
-      this.hostState = { revision: event.revision, scheduler: event.scheduler, power: event.power }
+      this.hostState = { ...this.hostState, revision: event.revision, scheduler: event.scheduler, power: event.power }
       this.notify()
       return
     }
     void this.refreshRemote()
   }
 
+  /**
+   * 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(): number {
+    return this.hostState?.maxSubtaskDepth ?? DEFAULT_SUBTASK_DEPTH
+  }
+
+  /**
+   * 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(snapshot: TaskBoardSnapshot): HostMirror {
+    const sessionDefaultPermission = snapshot.sessionDefaultPermission ?? this.hostState?.sessionDefaultPermission
+    const maxSubtaskDepth = snapshot.maxSubtaskDepth ?? this.hostState?.maxSubtaskDepth
+    const teamRunAvailable = snapshot.teamRunAvailable ?? this.hostState?.teamRunAvailable
+    return {
+      revision: snapshot.revision,
+      scheduler: snapshot.scheduler,
+      power: snapshot.power,
+      ...(sessionDefaultPermission === undefined ? {} : { sessionDefaultPermission }),
+      ...(maxSubtaskDepth === undefined ? {} : { maxSubtaskDepth }),
+      ...(teamRunAvailable === undefined ? {} : { teamRunAvailable }),
+    }
+  }
+
   private async refreshRemote(preserveError?: string): Promise<boolean> {
     const transport = this.deps.transport
     if (transport === undefined) return true
@@ -634,7 +752,7 @@ export class BoardController {
     const sameGeneration = currentLedgerId === nextLedgerId
     if (sameGeneration && this.hostState !== undefined && snapshot.revision < this.hostState.revision) return false
     this.tasks = [...snapshot.tasks]
-    this.hostState = { revision: snapshot.revision, scheduler: snapshot.scheduler, power: snapshot.power }
+    this.hostState = this.mirrorOf(snapshot)
     this.transportError = undefined
     if (this.selectedTaskId !== undefined && !this.tasks.some(task => task.id === this.selectedTaskId)) {
       this.selectedTaskId = undefined

package/src/core/store.ts

@@ -11,6 +11,7 @@
  */
 import { isValidCron } from './schedule.ts'
 import { isTaskPermission, isTaskStatus, normalizeTags, normalizeTargetId, type ScheduleRule, type TaskFreeze, type TaskRecord, type TaskPermission, type TaskStatus } from './tasks.ts'
+import { isExecutionOutcome } from './subtask.ts'
 import type { TaskHandover } from './handover.ts'
 import { sanitizeFreezeSnapshot } from './freeze-snapshot.ts'
 import { sanitizeHandover } from './handover.ts'
@@ -62,6 +63,7 @@ function isTaskRecordShape(value: unknown): value is Omit<TaskRecord, 'status'>
   if (typeof record.prompt !== 'string') return false
   if (typeof record.createdAt !== 'number') return false
   if (typeof record.updatedAt !== 'number') return false
+  if (record.parentId !== undefined && typeof record.parentId !== 'string') return false
   if (record.workspaceId !== undefined && typeof record.workspaceId !== 'string') return false
   if (record.mode !== undefined && typeof record.mode !== 'string') return false
   if (record.permission !== undefined && typeof record.permission !== 'string') return false
@@ -179,6 +181,19 @@ export function parseLedger(raw: string | null): TaskRecord[] {
     // clear a malformed persisted rule rather than leave it in the row.
     const task: TaskRecord = { ...row, status: normalizeStatus(row.status) }
     task.schedule = normalizeSchedule(row.schedule)
+    // The lineage link is repaired like every other optional field: a blank or
+    // non-string parent id clears the link instead of dropping the row. Whether
+    // the link is structurally sound (parent exists, no cycle) is decided where
+    // the whole list is known (HostTaskLedger.parseHostTasks).
+    task.parentId = normalizeTargetId(row.parentId)
+    // Cascade bookkeeping on execution records is repaired field by field too,
+    // so a hand-edited ledger degrades a run group instead of the whole task.
+    task.executions = task.executions.map(execution => ({
+      ...execution,
+      runGroupId: normalizeTargetId(execution.runGroupId),
+      ownResult: isExecutionOutcome(execution.ownResult) ? execution.ownResult : undefined,
+      ownError: typeof execution.ownError === 'string' ? execution.ownError : undefined,
+    }))
     // Execution targets are normalized like the schedule: blank strings
     // clear the pin and unknown permission strings from a future version
     // fall back to the session default instead of dropping the row.

package/src/core/subtask.ts

@@ -0,0 +1,286 @@
+/**
+ * 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 const SUBTASK_DEPTH_MIN = 1
+/** Highest configurable subtask depth. */
+export const SUBTASK_DEPTH_MAX = 3
+/** Deployment default: one level of subtasks, and no subtask of a subtask. */
+export 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 function normalizeSubtaskDepth(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return DEFAULT_SUBTASK_DEPTH
+  const depth = Math.trunc(value)
+  if (depth < SUBTASK_DEPTH_MIN) return SUBTASK_DEPTH_MIN
+  if (depth > SUBTASK_DEPTH_MAX) return SUBTASK_DEPTH_MAX
+  return depth
+}
+
+/** Whether an unknown value is a settled execution outcome. */
+export function isExecutionOutcome(value: unknown): value is ExecutionOutcome {
+  return value === 'succeeded' || value === 'failed' || value === 'cancelled'
+}
+
+function indexOf(tasks: readonly TaskRecord[]): Map<string, TaskRecord> {
+  return new Map(tasks.map(task => [task.id, task]))
+}
+
+/**
+ * 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 function ancestorChain(tasks: readonly TaskRecord[], task: TaskRecord): TaskRecord[] {
+  const index = indexOf(tasks)
+  const chain: TaskRecord[] = []
+  const seen = new Set<string>([task.id])
+  let current = task.parentId === undefined ? undefined : index.get(task.parentId)
+  while (current !== undefined && chain.length < tasks.length) {
+    if (seen.has(current.id)) break
+    seen.add(current.id)
+    chain.push(current)
+    current = current.parentId === undefined ? undefined : index.get(current.parentId)
+  }
+  return chain
+}
+
+/** Root-to-task depth: a root task is 0, its subtask 1, and so on. */
+export function taskDepth(tasks: readonly TaskRecord[], id: string): number {
+  const task = indexOf(tasks).get(id)
+  return task === undefined ? 0 : ancestorChain(tasks, task).length
+}
+
+/** Direct subtasks of a task, in ledger order. */
+export function directSubtasks(tasks: readonly TaskRecord[], id: string): TaskRecord[] {
+  return tasks.filter(task => task.parentId === id)
+}
+
+/**
+ * Descendants of a task in breadth-first order, bounded by maxSubtaskDepth
+ * total depth. The visited set keeps a malformed ledger from looping.
+ */
+export function descendantTasks(tasks: readonly TaskRecord[], id: string, maxSubtaskDepth: number): TaskRecord[] {
+  const visited = new Set<string>([id])
+  const found: TaskRecord[] = []
+  let frontier = [id]
+  for (let depth = 1; depth <= maxSubtaskDepth && frontier.length > 0; depth += 1) {
+    const next: string[] = []
+    for (const parentId of frontier) {
+      for (const task of tasks) {
+        if (task.parentId !== parentId || visited.has(task.id)) continue
+        visited.add(task.id)
+        found.push(task)
+        next.push(task.id)
+      }
+    }
+    frontier = next
+  }
+  return found
+}
+
+/**
+ * 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 function subtreeHeight(tasks: readonly TaskRecord[], id: string, visited: ReadonlySet<string> = new Set<string>()): number {
+  if (visited.has(id)) return 0
+  const seen = new Set([...visited, id])
+  const children = directSubtasks(tasks, id)
+  if (children.length === 0) return 0
+  let height = 0
+  for (const child of children) height = Math.max(height, 1 + subtreeHeight(tasks, child.id, seen))
+  return Math.min(height, SUBTASK_DEPTH_MAX)
+}
+
+/** 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 function checkParentLink(
+  tasks: readonly TaskRecord[],
+  childId: string,
+  parentId: string | null,
+  maxSubtaskDepth: number,
+): ParentLinkCheck {
+  const child = tasks.find(task => task.id === childId)
+  if (child === undefined) return { ok: false, reason: 'unknown-task' }
+  if (parentId === null || parentId === '') return { ok: true }
+  if (parentId === childId) return { ok: false, reason: 'self-parent' }
+  const parent = tasks.find(task => task.id === parentId)
+  if (parent === undefined) return { ok: false, reason: 'unknown-parent' }
+  if (parent.archivedAt !== undefined) return { ok: false, reason: 'archived-parent' }
+  if (descendantTasks(tasks, childId, SUBTASK_DEPTH_MAX).some(task => task.id === parentId)) return { ok: false, reason: 'cycle' }
+  const depth = taskDepth(tasks, parentId) + 1 + subtreeHeight(tasks, childId)
+  if (depth > maxSubtaskDepth) return { ok: false, reason: 'depth-exceeded' }
+  return { ok: true }
+}
+
+/**
+ * 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 function cascadeTargets(
+  tasks: readonly TaskRecord[],
+  rootId: string,
+  maxSubtaskDepth: number,
+): TaskRecord[] {
+  const root = tasks.find(task => task.id === rootId)
+  if (root === undefined) return []
+  return [root, ...descendantTasks(tasks, rootId, maxSubtaskDepth)]
+}
+
+/** 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 function openGroupExecution(task: TaskRecord, runGroupId: string): ExecutionRecord | undefined {
+  return task.executions.find(execution => execution.runGroupId === runGroupId && execution.endedAt === 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 function pendingCascadeChildren(
+  tasks: readonly TaskRecord[],
+  parentTaskId: string,
+  runGroupId: string,
+): OpenCascadeChild[] {
+  const pending: OpenCascadeChild[] = []
+  for (const task of tasks) {
+    if (task.parentId !== parentTaskId) continue
+    const execution = openGroupExecution(task, runGroupId)
+    if (execution !== undefined) pending.push({ taskId: task.id, execution })
+  }
+  return pending
+}
+
+/**
+ * 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 function combineCascadeOutcome(
+  entries: readonly { result: ExecutionOutcome; error?: string }[],
+): { result: ExecutionOutcome; error: string | undefined } {
+  let result: ExecutionOutcome = 'succeeded'
+  let error: string | undefined
+  for (const entry of entries) {
+    if (entry.result === 'failed') {
+      if (result !== 'failed') error = undefined
+      result = 'failed'
+      if (error === undefined && entry.error !== undefined && entry.error !== '') error = entry.error
+      continue
+    }
+    if (entry.result === 'cancelled') {
+      if (result === 'succeeded') result = 'cancelled'
+      if (error === undefined && entry.error !== undefined && entry.error !== '') error = entry.error
+    }
+  }
+  return error === undefined ? { result, error: undefined } : { result, error }
+}
+
+/**
+ * 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 function effectiveTaskPermission(task: TaskRecord): TaskRecord['permission'] {
+  return task.handover?.permission ?? task.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 function teammateName(title: string, token: string): string {
+  const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 32).replace(/-+$/g, '')
+  const suffix = token.replace(/[^a-z0-9]/gi, '').slice(0, 8).toLowerCase()
+  return `${slug === '' ? 'subtask' : slug}-${suffix === '' ? 'run' : suffix}`
+}
+
+export function resolveExecutionTargets(
+  task: TaskRecord,
+  tasks: readonly TaskRecord[],
+  maxSubtaskDepth: number = SUBTASK_DEPTH_MAX,
+): TaskRecord {
+  if (task.parentId === undefined) return task
+  const chain = [task, ...ancestorChain(tasks, task).slice(0, maxSubtaskDepth)]
+  const first = (key: 'workspaceId' | 'mode' | 'model'): string | undefined => {
+    for (const candidate of chain) {
+      const value = candidate[key]
+      if (value !== undefined) return value
+    }
+    return undefined
+  }
+  const own = effectiveTaskPermission(task)
+  // An own binding (pin or handover) keeps its own confirmation stamp; only an
+  // absent one borrows the ancestor's binding AND that ancestor's stamp.
+  const owner = own === undefined
+    ? chain.slice(1).find(candidate => effectiveTaskPermission(candidate) !== undefined)
+    : undefined
+  return {
+    ...task,
+    workspaceId: first('workspaceId'),
+    mode: first('mode'),
+    model: first('model'),
+    permission: own ?? (owner === undefined ? undefined : effectiveTaskPermission(owner)),
+    permissionConfirmedAt: own === undefined ? owner?.permissionConfirmedAt : task.permissionConfirmedAt,
+  }
+}