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

package/src/core/schedule.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. */
@@ -20,10 +41,10 @@ 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
 }
 
 /** Inclusive ranges per field, in cron order. */
@@ -35,6 +56,141 @@ const FIELD_RANGES: ReadonlyArray<readonly [number, number]> = [
   [0, 7], // weekdays (7 = Sunday, normalized below)
 ]
 
+/** Fallback zone when the process reports no usable IANA zone. */
+export const HOST_TIME_ZONE_FALLBACK = 'UTC'
+
+/** IANA `Area/Location`, plus the bare `UTC` the platform reports. */
+const IANA_ZONE = /^[A-Za-z][A-Za-z0-9_+.-]*(?:\/[A-Za-z0-9_+.-]+)+$/
+
+/** One resolved wall-clock reading in some zone. */
+export interface ZonedParts {
+  year: number
+  month: number
+  day: number
+  hour: number
+  minute: number
+}
+
+/** Cached formatters: constructing an Intl formatter dominates the cost of a resolve. */
+const FORMATTERS = new Map<string, Intl.DateTimeFormat>()
+
+function zoneFormatter(timeZone: string): Intl.DateTimeFormat {
+  let formatter = FORMATTERS.get(timeZone)
+  if (formatter === undefined) {
+    formatter = new Intl.DateTimeFormat('en-US', {
+      timeZone,
+      hourCycle: 'h23',
+      year: 'numeric',
+      month: '2-digit',
+      day: '2-digit',
+      hour: '2-digit',
+      minute: '2-digit',
+    })
+    FORMATTERS.set(timeZone, formatter)
+  }
+  return formatter
+}
+
+/**
+ * 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 function partsInZone(timeZone: string, epochMs: number): ZonedParts {
+  const fields: Record<string, string> = {}
+  for (const part of zoneFormatter(timeZone).formatToParts(new Date(epochMs))) {
+    if (part.type !== 'literal') fields[part.type] = part.value
+  }
+  return {
+    year: Number(fields.year),
+    month: Number(fields.month),
+    day: Number(fields.day),
+    hour: Number(fields.hour),
+    minute: Number(fields.minute),
+  }
+}
+
+/** The zone's UTC offset in effect at one instant, in milliseconds. */
+function offsetAt(timeZone: string, epochMs: number): number {
+  const parts = partsInZone(timeZone, epochMs)
+  return Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute) - epochMs
+}
+
+/**
+ * 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 function zonedEpoch(
+  timeZone: string,
+  year: number,
+  month: number,
+  day: number,
+  hour: number,
+  minute: number,
+): number | undefined {
+  const naive = Date.UTC(year, month - 1, day, hour, minute)
+  const offsets = new Set([
+    offsetAt(timeZone, naive - 86_400_000),
+    offsetAt(timeZone, naive),
+    offsetAt(timeZone, naive + 86_400_000),
+  ])
+  let earliest: number | undefined
+  for (const offset of offsets) {
+    const candidate = naive - offset
+    const parts = partsInZone(timeZone, candidate)
+    if (parts.year !== year || parts.month !== month || parts.day !== day) continue
+    if (parts.hour !== hour || parts.minute !== minute) continue
+    if (earliest === undefined || candidate < earliest) earliest = candidate
+  }
+  return earliest
+}
+
+/**
+ * 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 function resolveHostTimeZone(): string {
+  try {
+    const zone = Intl.DateTimeFormat().resolvedOptions().timeZone
+    return typeof zone === 'string' && zone !== '' ? zone : HOST_TIME_ZONE_FALLBACK
+  } catch {
+    return HOST_TIME_ZONE_FALLBACK
+  }
+}
+
+/**
+ * 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 function isValidTimeZone(value: string): boolean {
+  if (value.trim() !== value || value === '') return false
+  if (value !== 'UTC' && !IANA_ZONE.test(value)) return false
+  try {
+    return new Intl.DateTimeFormat('en-US', { timeZone: value }).resolvedOptions().timeZone !== undefined
+  } catch {
+    return false
+  }
+}
+
 /**
  * Parse a 5-field cron expression.
  * @returns the match sets, or null when the expression is invalid.
@@ -57,11 +213,11 @@ export function parseCron(expr: string): CronSchedule | null {
     days: sets[2],
     months: sets[3],
     weekdays,
-    // Only the literal '*' marks a field unrestricted: an explicit full
-    // enumeration such as '1-31' is a restricted field and must not collapse
-    // into the wildcard (it participates in day/weekday OR semantics).
-    dayWildcard: fields[2] === '*',
-    weekdayWildcard: fields[4] === '*',
+    // Vixie selects the day branch from the field TEXT: only a field starting
+    // with '*' is starred. A written-out range such as '1-31' is restricted and
+    // still participates in the OR/AND choice.
+    dayStarred: fields[2].startsWith('*'),
+    weekdayStarred: fields[4].startsWith('*'),
   }
 }
 
@@ -71,57 +227,61 @@ export 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 function nextRunAtMs(expr: string, fromMs: number): number | undefined {
+export function nextRunAtMs(expr: string, fromMs: number, timeZone?: string): number | undefined {
   const schedule = parseCron(expr)
   if (schedule === null) return undefined
   if (!hasPossibleCalendarDay(schedule)) return undefined
-  const from = new Date(fromMs)
+  const zone = timeZone ?? resolveHostTimeZone()
+  const start = partsInZone(zone, fromMs)
   const limitMs = fromMs + 5 * 366 * 24 * 60 * 60 * 1000
 
   const sortedMinutes = [...schedule.minutes].sort((a, b) => a - b)
   const sortedHours = [...schedule.hours].sort((a, b) => a - b)
   const sortedMonths = [...schedule.months].sort((a, b) => a - b)
 
-  let year = from.getFullYear()
-  let month = from.getMonth() + 1
-  let day = from.getDate()
-  let hour = from.getHours()
-  // Strictly after fromMs: the old scan started from the next minute.
-  let minute = from.getMinutes() + 1
+  let year = start.year
+  let month = start.month
+  let day = start.day
+  let hour = start.hour
+  // Strictly after fromMs: the walk starts from the next minute.
+  let minute = start.minute + 1
 
-  while (new Date(year, month - 1, 1, 0, 0, 0, 0).getTime() <= limitMs) {
+  while (Date.UTC(year, month - 1, 1) <= limitMs + 86_400_000) {
     for (const candidateMonth of sortedMonths) {
       if (candidateMonth < month) continue
-      const daysInMonth = new Date(year, candidateMonth, 0).getDate()
+      const daysInMonth = new Date(Date.UTC(year, candidateMonth, 0)).getUTCDate()
       const dayStart = candidateMonth === month ? day : 1
       for (let candidateDay = dayStart; candidateDay <= daysInMonth; candidateDay += 1) {
-        const dayProbe = new Date(year, candidateMonth - 1, candidateDay, 0, 0, 0, 0)
-        if (!dayCandidate(schedule, dayProbe)) continue
+        if (!dayCandidate(schedule, year, candidateMonth, candidateDay)) continue
         const hourStart = candidateMonth === month && candidateDay === day ? hour : 0
         for (const candidateHour of sortedHours) {
           if (candidateHour < hourStart) continue
           const minuteStart = candidateMonth === month && candidateDay === day && candidateHour === hour ? minute : 0
           for (const candidateMinute of sortedMinutes) {
             if (candidateMinute < minuteStart) continue
-            const candidate = new Date(year, candidateMonth - 1, candidateDay, candidateHour, candidateMinute, 0, 0)
-            const time = candidate.getTime()
+            const time = zonedEpoch(zone, year, candidateMonth, candidateDay, candidateHour, candidateMinute)
+            if (time === undefined) continue
             if (time <= fromMs) continue
             if (time > limitMs) return undefined
-            if (matches(schedule, candidate)) return time
+            return time
           }
         }
       }
@@ -135,18 +295,22 @@ export function nextRunAtMs(expr: string, fromMs: number): number | undefined {
   return undefined
 }
 
-/** Day/weekday OR gate shared by {@link matches} and the candidate scan. */
-function dayCandidate(schedule: CronSchedule, date: Date): boolean {
-  const dayMatches = schedule.days.has(date.getDate())
-  const weekdayMatches = schedule.weekdays.has(date.getDay())
-  if (schedule.dayWildcard) return weekdayMatches
-  if (schedule.weekdayWildcard) return dayMatches
-  return dayMatches || weekdayMatches
+/**
+ * The Vixie day gate shared by the candidate walk. Both fields restricted is
+ * OR; any other combination is AND, because a starred field matches every
+ * value and so cannot widen the result.
+ */
+function dayCandidate(schedule: CronSchedule, year: number, month: number, day: number): boolean {
+  const dayMatches = schedule.days.has(day)
+  // Day of week is a property of the calendar date, so it is zone-independent.
+  const weekdayMatches = schedule.weekdays.has(new Date(Date.UTC(year, month - 1, day)).getUTCDay())
+  if (!schedule.dayStarred && !schedule.weekdayStarred) return dayMatches || weekdayMatches
+  return dayMatches && weekdayMatches
 }
 
 /** Reject impossible month/day pairs without spending the multi-year scan. */
 function hasPossibleCalendarDay(schedule: CronSchedule): boolean {
-  if (schedule.dayWildcard || !schedule.weekdayWildcard) return true
+  if (schedule.dayStarred || !schedule.weekdayStarred) return true
   const maximumDay = new Map<number, number>([
     [1, 31], [2, 29], [3, 31], [4, 30], [5, 31], [6, 30],
     [7, 31], [8, 31], [9, 30], [10, 31], [11, 30], [12, 31],
@@ -194,14 +358,6 @@ function parseField(field: string, min: number, max: number, out: Set<number>):
   return true
 }
 
-/** Day/weekday OR semantics: a restricted day field alone gates, and vice versa. */
-function matches(schedule: CronSchedule, date: Date): boolean {
-  if (!schedule.minutes.has(date.getMinutes())) return false
-  if (!schedule.hours.has(date.getHours())) return false
-  if (!schedule.months.has(date.getMonth() + 1)) return false
-  return dayCandidate(schedule, date)
-}
-
 function isDigits(value: string): boolean {
   return /^\d+$/.test(value)
 }

package/src/core/store.ts

@@ -9,12 +9,14 @@
  * channel later); tests run against the in-memory backend and a jsdom
  * localStorage backend.
  */
-import { isValidCron } from './schedule.ts'
+import { isValidCron, isValidTimeZone } 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'
+import { normalizeTaskIntegrations } from './extension.ts'
+import { normalizeVerification } from './verification.ts'
 
 /** Persistence seam for the task ledger. */
 export interface TaskStore {
@@ -67,7 +69,11 @@ function isTaskRecordShape(value: unknown): value is Omit<TaskRecord, 'status'>
   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
+  if (record.integrations !== undefined && (typeof record.integrations !== 'object' || record.integrations === null || Array.isArray(record.integrations))) return false
+  if (record.hidden !== undefined && typeof record.hidden !== 'boolean') return false
   if (record.reuseSession !== undefined && typeof record.reuseSession !== 'boolean') return false
+  if (record.goalRun !== undefined && typeof record.goalRun !== 'boolean') return false
+  if (record.skipVerification !== undefined && typeof record.skipVerification !== 'boolean') return false
   if (!Array.isArray(record.executions)) return false
   for (const execution of record.executions) {
     if (typeof execution !== 'object' || execution === null) return false
@@ -81,6 +87,9 @@ function isTaskRecordShape(value: unknown): value is Omit<TaskRecord, 'status'>
     if (entry.initiatedBy !== undefined && typeof entry.initiatedBy !== 'string') return false
     if (entry.frozenBy !== undefined && typeof entry.frozenBy !== 'string') return false
     if (entry.frozenAt !== undefined && typeof entry.frozenAt !== 'number') return false
+    // The acceptance block is repaired like every other optional field: an
+    // unusable one is dropped, which can only make the board MORE strict.
+    if (entry.verification !== undefined && normalizeVerification(entry.verification) === undefined) return false
   }
   return true
 }
@@ -108,9 +117,14 @@ function normalizeSchedule(schedule: unknown): ScheduleRule | undefined {
   // schedule instead of being dropped for later repair.
   if (typeof rule.cron !== 'string') return undefined
   if (rule.cron.trim() === '' || !isValidCron(rule.cron)) return undefined
+  // A stored zone survives only when this runtime can resolve it; an unusable
+  // name is dropped (the rule then follows the Host zone) instead of being
+  // kept to fail every later resolve.
+  const timeZone = typeof rule.timeZone === 'string' && isValidTimeZone(rule.timeZone) ? rule.timeZone : undefined
   return {
     enabled: rule.enabled === true,
     cron: rule.cron,
+    ...(timeZone === undefined ? {} : { timeZone }),
     nextRunAt: typeof rule.nextRunAt === 'number' ? rule.nextRunAt : undefined,
     lastTriggeredAt: typeof rule.lastTriggeredAt === 'number' ? rule.lastTriggeredAt : undefined,
   }
@@ -193,6 +207,9 @@ export function parseLedger(raw: string | null): TaskRecord[] {
       runGroupId: normalizeTargetId(execution.runGroupId),
       ownResult: isExecutionOutcome(execution.ownResult) ? execution.ownResult : undefined,
       ownError: typeof execution.ownError === 'string' ? execution.ownError : undefined,
+      // A malformed acceptance block is dropped rather than dropping the
+      // execution record: the board then treats that run as unverified.
+      verification: normalizeVerification(execution.verification),
     }))
     // Execution targets are normalized like the schedule: blank strings
     // clear the pin and unknown permission strings from a future version
@@ -202,6 +219,12 @@ export function parseLedger(raw: string | null): TaskRecord[] {
     task.archivedAt = typeof row.archivedAt === 'number' && Number.isFinite(row.archivedAt) ? row.archivedAt : undefined
     task.permission = isTaskPermission(row.permission) ? row.permission as TaskPermission : undefined
     task.reuseSession = row.reuseSession === true ? true : undefined
+    // The goal opt-in is stored only when it is OFF: absent means the default
+    // (start each run with /goal), so a hand-edited true normalizes back to it.
+    task.goalRun = row.goalRun === false ? false : undefined
+    // The acceptance opt-out is stored only when it is ON: absent inherits the
+    // board-wide switch, so a hand-edited false normalizes back to inherit.
+    task.skipVerification = row.skipVerification === true ? true : undefined
     task.freeze = normalizeFreeze(row.freeze)
     task.handover = normalizeHandover(row.handover)
     // Tags are repaired field by field like the schedule: a malformed entry is
@@ -209,6 +232,8 @@ export function parseLedger(raw: string | null): TaskRecord[] {
     // dropping the task row.
     task.tags = normalizeTags(row.tags)
     task.permissionConfirmedAt = typeof row.permissionConfirmedAt === 'number' && Number.isFinite(row.permissionConfirmedAt) ? row.permissionConfirmedAt : undefined
+    task.integrations = normalizeTaskIntegrations(row.integrations)
+    task.hidden = row.hidden === true ? true : undefined
     tasks.push(task)
   }
   return tasks

package/src/core/subtask.ts

@@ -36,6 +36,31 @@ export function isExecutionOutcome(value: unknown): value is ExecutionOutcome {
   return value === 'succeeded' || value === 'failed' || value === 'cancelled'
 }
 
+/**
+ * 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 function buildLineageIndex(tasks: readonly TaskRecord[]): LineageIndex {
+  const byId = new Map<string, TaskRecord>()
+  const childrenByParent = new Map<string, TaskRecord[]>()
+  for (const task of tasks) {
+    byId.set(task.id, task)
+    if (task.parentId === undefined) continue
+    const siblings = childrenByParent.get(task.parentId)
+    if (siblings === undefined) childrenByParent.set(task.parentId, [task])
+    else siblings.push(task)
+  }
+  return { byId, childrenByParent }
+}
+
 function indexOf(tasks: readonly TaskRecord[]): Map<string, TaskRecord> {
   return new Map(tasks.map(task => [task.id, task]))
 }
@@ -46,8 +71,8 @@ function indexOf(tasks: readonly TaskRecord[]): Map<string, TaskRecord> {
  * 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)
+export function ancestorChain(tasks: readonly TaskRecord[], task: TaskRecord, lineage?: LineageIndex): TaskRecord[] {
+  const index = lineage?.byId ?? indexOf(tasks)
   const chain: TaskRecord[] = []
   const seen = new Set<string>([task.id])
   let current = task.parentId === undefined ? undefined : index.get(task.parentId)
@@ -61,13 +86,14 @@ export function ancestorChain(tasks: readonly TaskRecord[], task: TaskRecord): T
 }
 
 /** 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
+export function taskDepth(tasks: readonly TaskRecord[], id: string, lineage?: LineageIndex): number {
+  const task = (lineage?.byId ?? indexOf(tasks)).get(id)
+  return task === undefined ? 0 : ancestorChain(tasks, task, lineage).length
 }
 
 /** Direct subtasks of a task, in ledger order. */
-export function directSubtasks(tasks: readonly TaskRecord[], id: string): TaskRecord[] {
+export function directSubtasks(tasks: readonly TaskRecord[], id: string, lineage?: LineageIndex): TaskRecord[] {
+  if (lineage !== undefined) return [...(lineage.childrenByParent.get(id) ?? [])]
   return tasks.filter(task => task.parentId === id)
 }
 
@@ -75,15 +101,18 @@ export function directSubtasks(tasks: readonly TaskRecord[], id: string): TaskRe
  * 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[] {
+export function descendantTasks(tasks: readonly TaskRecord[], id: string, maxSubtaskDepth: number, lineage?: LineageIndex): 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
+      const children = lineage === undefined
+        ? tasks.filter(task => task.parentId === parentId)
+        : lineage.childrenByParent.get(parentId) ?? []
+      for (const task of children) {
+        if (visited.has(task.id)) continue
         visited.add(task.id)
         found.push(task)
         next.push(task.id)
@@ -99,13 +128,13 @@ export function descendantTasks(tasks: readonly TaskRecord[], id: string, maxSub
  * 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 {
+export function subtreeHeight(tasks: readonly TaskRecord[], id: string, visited: ReadonlySet<string> = new Set<string>(), lineage?: LineageIndex): number {
   if (visited.has(id)) return 0
   const seen = new Set([...visited, id])
-  const children = directSubtasks(tasks, id)
+  const children = directSubtasks(tasks, id, lineage)
   if (children.length === 0) return 0
   let height = 0
-  for (const child of children) height = Math.max(height, 1 + subtreeHeight(tasks, child.id, seen))
+  for (const child of children) height = Math.max(height, 1 + subtreeHeight(tasks, child.id, seen, lineage))
   return Math.min(height, SUBTASK_DEPTH_MAX)
 }
 
@@ -137,16 +166,17 @@ export function checkParentLink(
   childId: string,
   parentId: string | null,
   maxSubtaskDepth: number,
+  lineage?: LineageIndex,
 ): ParentLinkCheck {
-  const child = tasks.find(task => task.id === childId)
+  const child = lineage === undefined ? tasks.find(task => task.id === childId) : lineage.byId.get(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)
+  const parent = lineage === undefined ? tasks.find(task => task.id === parentId) : lineage.byId.get(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 (descendantTasks(tasks, childId, SUBTASK_DEPTH_MAX, lineage).some(task => task.id === parentId)) return { ok: false, reason: 'cycle' }
+  const depth = taskDepth(tasks, parentId, lineage) + 1 + subtreeHeight(tasks, childId, new Set<string>(), lineage)
   if (depth > maxSubtaskDepth) return { ok: false, reason: 'depth-exceeded' }
   return { ok: true }
 }
@@ -241,18 +271,43 @@ export function effectiveTaskPermission(task: TaskRecord): TaskRecord['permissio
  */
 /**
  * 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 function teammateName(title: string, token: string): string {
+export function teammateName(title: string, token: string, memberId?: 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}`
+  const member = memberId === undefined || memberId === '' ? undefined : stableTag(memberId)
+  return [slug === '' ? 'subtask' : slug, member, suffix === '' ? 'run' : suffix]
+    .filter((part): part is string => part !== undefined)
+    .join('-')
+}
+
+/**
+ * A stable 4-hex tag for one member id. The name is derived twice for the same
+ * member — once for the Lead's prompt and once for the spawn request — so the
+ * tag must be a pure function of the id, never of a clock or a counter. FNV-1a
+ * keeps it dependency-free in `core/`, which both halves compile.
+ */
+function stableTag(value: string): string {
+  let hash = 0x811c9dc5
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index)
+    hash = Math.imul(hash, 0x01000193) >>> 0
+  }
+  return hash.toString(16).padStart(8, '0').slice(0, 4)
 }
 
 export function resolveExecutionTargets(