feat(task-lifecycle): transition guard and startup delegation reconciliation

Author: edelauna

src/__tests__/helpers/provider-stub.ts

@@ -12,6 +12,7 @@ export function makeProviderStub<T extends object>(stub: T): T {
 	const proto = ClineProvider.prototype as any
 	s.delegationTransitionLocks ??= new Map()
 	s.cancelledDelegationChildIds ??= new Set()
+	s.log ??= vi.fn()
 	s.runDelegationTransition = proto.runDelegationTransition.bind(s)
 	return s
 }

src/__tests__/history-resume-delegation.spec.ts

@@ -33,6 +33,7 @@ vi.mock("../core/task-persistence", () => ({
 	readApiMessages: vi.fn().mockResolvedValue([]),
 	saveApiMessages: vi.fn().mockResolvedValue(undefined),
 	saveTaskMessages: vi.fn().mockResolvedValue(undefined),
+	assertValidTransition: vi.fn(),
 }))
 
 import { ClineProvider } from "../core/webview/ClineProvider"

src/core/task-persistence/TaskHistoryStore.ts

@@ -8,6 +8,28 @@ import { GlobalFileNames } from "../../shared/globalFileNames"
 import { safeWriteJson } from "../../utils/safeWriteJson"
 import { getStorageBasePath } from "../../utils/storage"
 
+/** Valid status values for a task's HistoryItem. */
+export type HistoryItemStatus = "active" | "delegated" | "completed"
+
+const VALID_TRANSITIONS: Record<HistoryItemStatus, HistoryItemStatus[]> = {
+	active: ["delegated", "completed"],
+	delegated: ["active"],
+	completed: [],
+}
+
+/**
+ * Asserts that a task status transition is valid, throwing if not.
+ *
+ * @throws {Error} When the transition is not allowed by the state machine.
+ */
+export function assertValidTransition(from: HistoryItemStatus | undefined, to: HistoryItemStatus): void {
+	const fromStatus: HistoryItemStatus = from ?? "active"
+	const validTargets = VALID_TRANSITIONS[fromStatus]
+	if (!validTargets.includes(to)) {
+		throw new Error(`Invalid task status transition: ${fromStatus} → ${to}`)
+	}
+}
+
 /**
  * Index file format for fast startup reads.
  */
@@ -88,10 +110,13 @@ export class TaskHistoryStore {
 			// 2. Reconcile cache against actual task directories on disk
 			await this.reconcile()
 
-			// 3. Start fs.watch for cross-instance reactivity
+			// 3. Repair delegation inconsistencies left by a previous crash
+			await this.reconcileDelegationState()
+
+			// 4. Start fs.watch for cross-instance reactivity
 			this.startWatcher()
 
-			// 4. Start periodic reconciliation as a defensive fallback
+			// 5. Start periodic reconciliation as a defensive fallback
 			this.startPeriodicReconciliation()
 		} finally {
 			// Mark initialization as complete so callers awaiting `initialized` can proceed
@@ -158,30 +183,35 @@ export class TaskHistoryStore {
 	 * updates the in-memory Map, and schedules a debounced index write.
 	 */
 	async upsert(item: HistoryItem): Promise<HistoryItem[]> {
-		return this.withLock(async () => {
-			const existing = this.cache.get(item.id)
+		return this.withLock(() => this.upsertCore(item))
+	}
 
-			// Merge: preserve existing metadata unless explicitly overwritten
-			const merged = existing ? { ...existing, ...item } : item
+	/**
+	 * Core upsert logic — must only be called from within `withLock`.
+	 */
+	private async upsertCore(item: HistoryItem): Promise<HistoryItem[]> {
+		const existing = this.cache.get(item.id)
 
-			// Write per-task file (source of truth)
-			await this.writeTaskFile(merged)
+		// Merge: preserve existing metadata unless explicitly overwritten
+		const merged = existing ? { ...existing, ...item } : item
 
-			// Update in-memory cache
-			this.cache.set(merged.id, merged)
+		// Write per-task file (source of truth)
+		await this.writeTaskFile(merged)
 
-			// Schedule debounced index write
-			this.scheduleIndexWrite()
+		// Update in-memory cache
+		this.cache.set(merged.id, merged)
 
-			const all = this.getAll()
+		// Schedule debounced index write
+		this.scheduleIndexWrite()
 
-			// Call onWrite callback inside the lock for serialized write-through
-			if (this.onWrite) {
-				await this.onWrite(all)
-			}
+		const all = this.getAll()
 
-			return all
-		})
+		// Call onWrite callback inside the lock for serialized write-through
+		if (this.onWrite) {
+			await this.onWrite(all)
+		}
+
+		return all
 	}
 
 	/**
@@ -289,6 +319,80 @@ export class TaskHistoryStore {
 		})
 	}
 
+	/**
+	 * Repair delegation inconsistencies left by a crash mid-transition.
+	 *
+	 * Called once from `initialize()` after `reconcile()`. Runs inside `withLock` to
+	 * prevent interleaving with watcher-triggered reconcile() calls. Iterates until
+	 * convergence so that chained delegations (A→B→C) are fully resolved in one startup.
+	 *
+	 * Must NOT be called from within `withLock` — each upsertCore call holds the lock
+	 * for the duration of a single write, and the outer lock wraps the whole pass.
+	 *
+	 * Cases repaired per pass:
+	 * - Parent `delegated` with no `awaitingChildId` → parent → `active` (invalid state)
+	 * - Parent `delegated`, child not found → parent → `active` (orphaned delegation)
+	 * - Parent `delegated`, child `completed` → parent → `active` (interrupted handoff)
+	 *
+	 * A parent awaiting an `active` child is left as-is — the child is resumable.
+	 */
+	private async reconcileDelegationState(): Promise<void> {
+		return this.withLock(async () => {
+			let repairsInThisPass: number
+			do {
+				repairsInThisPass = 0
+				// Rebuild the lookup map each pass so repairs from the previous pass
+				// are visible when evaluating chained delegations.
+				const byId = new Map(this.getAll().map((i) => [i.id, i]))
+
+				for (const [, item] of byId) {
+					if (item.status !== "delegated") {
+						continue
+					}
+
+					if (!item.awaitingChildId) {
+						await this.upsertCore({ ...item, status: "active", delegatedToId: undefined })
+						console.warn(
+							`[TaskHistoryStore] Reconciled invalid delegation: task ${item.id} → active (no awaitingChildId)`,
+						)
+						repairsInThisPass++
+						continue
+					}
+
+					const child = byId.get(item.awaitingChildId)
+
+					if (!child) {
+						await this.upsertCore({
+							...item,
+							status: "active",
+							awaitingChildId: undefined,
+							delegatedToId: undefined,
+						})
+						console.warn(
+							`[TaskHistoryStore] Reconciled orphaned delegation: task ${item.id} → active (child ${item.awaitingChildId} not found)`,
+						)
+						repairsInThisPass++
+					} else if (child.status === "completed") {
+						await this.upsertCore({
+							...item,
+							status: "active",
+							awaitingChildId: undefined,
+							delegatedToId: undefined,
+							completedByChildId: child.id,
+							completionResultSummary:
+								child.completionResultSummary ?? "Task completed (recovered after interruption)",
+						})
+						console.warn(
+							`[TaskHistoryStore] Reconciled interrupted handoff: task ${item.id} → active (child ${item.awaitingChildId} already completed)`,
+						)
+						repairsInThisPass++
+					}
+					// child.status === "active" or "delegated" → leave as-is this pass
+				}
+			} while (repairsInThisPass > 0)
+		})
+	}
+
 	// ────────────────────────────── Cache invalidation ──────────────────────────────
 
 	/**