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

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

* test: updating TaskPersistence vitest mocks

* fix(task-persistence): enforce status transition guard at upsertCore write boundary

* fix(delegation): guard concurrent rollback pop and add transition tests

* feat(ClineProvider): guarding parent, child transitions

* feat(ClineProvider): adding delegatedToId

* test(subtask): adding e2e test and apis for history tracking

---------

Co-authored-by: Naved  Merchant <naved.merchant@gmail.com>

Author: edelauna

apps/vscode-e2e/src/suite/subtasks.test.ts

@@ -150,6 +150,103 @@ suite("Roo Code Subtasks", function () {
 		}
 	})
 
+	test("delegated child completion persists parent and child history state", async () => {
+		const api = globalThis.api
+		const asks: Record<string, ClineMessage[]> = {}
+		const says: Record<string, ClineMessage[]> = {}
+
+		let delegationCompletedParentId: string | undefined
+		let delegationCompletedChildId: string | undefined
+		let delegationCompletedSummary: string | undefined
+
+		const messageHandler = ({ taskId, message }: { taskId: string; message: ClineMessage }) => {
+			if (message.type === "ask") {
+				asks[taskId] = asks[taskId] || []
+				asks[taskId].push(message)
+			}
+			if (message.type === "say" && message.partial === false) {
+				says[taskId] = says[taskId] || []
+				says[taskId].push(message)
+			}
+		}
+
+		const delegationCompletedHandler = (parentId: string, childId: string, summary: string) => {
+			delegationCompletedParentId = parentId
+			delegationCompletedChildId = childId
+			delegationCompletedSummary = summary
+		}
+
+		api.on(RooCodeEventName.Message, messageHandler)
+		api.on(RooCodeEventName.TaskDelegationCompleted, delegationCompletedHandler)
+
+		try {
+			const parentTaskId = await api.startNewTask({
+				configuration: {
+					mode: "ask",
+					alwaysAllowModeSwitch: true,
+					alwaysAllowSubtasks: true,
+					autoApprovalEnabled: true,
+					enableCheckpoints: false,
+				},
+				text: SUBTASK_PARENT_PROMPT,
+			})
+
+			let childTaskId: string | undefined
+			await waitFor(() => {
+				const stack = api.getCurrentTaskStack()
+				const current = stack[stack.length - 1]
+				if (current && current !== parentTaskId) {
+					childTaskId = current
+					return true
+				}
+				return false
+			})
+
+			await waitFor(() => asks[childTaskId!]?.some(({ ask }) => ask === "followup") ?? false)
+
+			// Send the answer, then wait for TaskDelegationCompleted. That event fires after
+			// atomicUpdatePair writes the persisted history but before the parent is re-created,
+			// so it is the right gate for history assertions. waitUntilCompleted alone is not
+			// sufficient because the resumed parent runs into a mock 404 and never emits
+			// TaskCompleted in the test environment.
+			await api.sendMessage(SUBTASK_CHILD_FOLLOWUP_ANSWER)
+			await waitFor(() => delegationCompletedParentId !== undefined)
+
+			assert.strictEqual(
+				delegationCompletedParentId,
+				parentTaskId,
+				"TaskDelegationCompleted should fire for parent",
+			)
+			assert.strictEqual(delegationCompletedChildId, childTaskId, "TaskDelegationCompleted should fire for child")
+			assert.strictEqual(delegationCompletedSummary, "9", "TaskDelegationCompleted summary should be '9'")
+
+			const parent = await api.getTaskHistoryItem(parentTaskId)
+			assert.ok(parent, "Parent history item should exist")
+			assert.strictEqual(parent.status, "active", "Parent status should be 'active' after child completes")
+			assert.strictEqual(parent.awaitingChildId, undefined, "Parent awaitingChildId should be cleared")
+			assert.strictEqual(parent.delegatedToId, undefined, "Parent delegatedToId should be cleared")
+			assert.strictEqual(parent.completedByChildId, childTaskId, "Parent completedByChildId should be the child")
+			assert.strictEqual(parent.completionResultSummary, "9", "Parent completionResultSummary should be '9'")
+			assert.ok(parent.childIds?.includes(childTaskId!), "Parent childIds should include the child")
+
+			const child = await api.getTaskHistoryItem(childTaskId!)
+			assert.ok(child, "Child history item should exist")
+			assert.strictEqual(child.status, "completed", "Child status should be 'completed'")
+			assert.strictEqual(child.parentTaskId, parentTaskId, "Child parentTaskId should point to parent")
+			assert.strictEqual(child.completionResultSummary, "9", "Child completionResultSummary should be '9'")
+		} finally {
+			api.off(RooCodeEventName.Message, messageHandler)
+			api.off(RooCodeEventName.TaskDelegationCompleted, delegationCompletedHandler)
+			if (api.getCurrentTaskStack().length > 0) {
+				await api.clearCurrentTask()
+			}
+			if (api.getCurrentTaskStack().length > 0) {
+				await api.clearCurrentTask()
+			}
+			await waitFor(() => api.getCurrentTaskStack().length === 0).catch(() => {})
+		}
+	})
+
 	// Race mitigation: skipDelegationRepair prevents removeClineFromStack from
 	// auto-resuming the parent when the child is cancelled (Race 2).
 	test("parent stays paused after subtask cancellation", async () => {

packages/types/src/api.ts

@@ -3,6 +3,7 @@ import type { Socket } from "net"
 
 import type { RooCodeEvents } from "./events.js"
 import type { RooCodeSettings } from "./global-settings.js"
+import type { HistoryItem } from "./history.js"
 import type { ProviderSettingsEntry, ProviderSettings } from "./provider-settings.js"
 import type { IpcMessage, IpcServerEvents } from "./ipc.js"
 
@@ -38,6 +39,12 @@ export interface RooCodeAPI extends EventEmitter<RooCodeAPIEvents> {
 	 * @returns True if the task is in the task history, false otherwise.
 	 */
 	isTaskInHistory(taskId: string): Promise<boolean>
+	/**
+	 * Returns the HistoryItem for a task by ID. Intended for use in tests only.
+	 * @param taskId The ID of the task.
+	 * @returns The HistoryItem, or undefined if not found.
+	 */
+	getTaskHistoryItem(taskId: string): Promise<HistoryItem | undefined>
 	/**
 	 * Returns the current task stack.
 	 * @returns An array of task IDs.

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

@@ -30,11 +30,15 @@ vi.mock("vscode", () => {
 vi.mock("../core/task-persistence/taskMessages", () => ({
 	readTaskMessages: vi.fn().mockResolvedValue([]),
 }))
-vi.mock("../core/task-persistence", () => ({
-	readApiMessages: vi.fn().mockResolvedValue([]),
-	saveApiMessages: vi.fn().mockResolvedValue(undefined),
-	saveTaskMessages: vi.fn().mockResolvedValue(undefined),
-}))
+vi.mock("../core/task-persistence", async (importOriginal) => {
+	const real = await importOriginal<typeof import("../core/task-persistence")>()
+	return {
+		...real,
+		readApiMessages: vi.fn().mockResolvedValue([]),
+		saveApiMessages: vi.fn().mockResolvedValue(undefined),
+		saveTaskMessages: vi.fn().mockResolvedValue(undefined),
+	}
+})
 
 import { ClineProvider } from "../core/webview/ClineProvider"
 import { readTaskMessages } from "../core/task-persistence/taskMessages"
@@ -130,9 +134,11 @@ describe("History resume delegation - parent metadata transitions", () => {
 		expect(firstId).toBe("child-1")
 		expect(secondId).toBe("parent-1")
 
-		// Verify child updater produces completed status
+		// Verify child updater produces completed status and persists completionResultSummary
+		// so startup reconciliation has the real result if the parent write fails.
 		const updatedChild = firstUpdater({ id: "child-1", status: "active" } as HistoryItem)
 		expect(updatedChild.status).toBe("completed")
+		expect(updatedChild.completionResultSummary).toBe("Child done")
 
 		// Verify parent updater produces active status with correct fields
 		const updatedParent = secondUpdater(parentHistoryItem as HistoryItem)
@@ -142,6 +148,7 @@ describe("History resume delegation - parent metadata transitions", () => {
 			completedByChildId: "child-1",
 			completionResultSummary: "Child done",
 			awaitingChildId: undefined,
+			delegatedToId: undefined,
 			childIds: ["child-1"],
 		})
 

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

@@ -44,7 +44,8 @@ vi.mock("vscode", () => {
 vi.mock("../core/task-persistence/taskMessages", () => ({
 	readTaskMessages: vi.fn().mockResolvedValue([]),
 }))
-vi.mock("../core/task-persistence", () => ({
+vi.mock("../core/task-persistence", async (importOriginal) => ({
+	...(await importOriginal<typeof import("../core/task-persistence")>()),
 	readApiMessages: vi.fn().mockResolvedValue([]),
 	saveApiMessages: vi.fn().mockResolvedValue(undefined),
 	saveTaskMessages: vi.fn().mockResolvedValue(undefined),

src/__tests__/provider-delegation.spec.ts

@@ -226,11 +226,20 @@ describe("ClineProvider.delegateParentAndOpenChild()", () => {
 			atomicReadAndUpdate: vi.fn().mockRejectedValue(persistError),
 		})
 
+		const child = { taskId: "child-1", start: childStart }
+		// Before createTask: getCurrentTask returns parent (used by step 3 close).
+		// After createTask: returns child so the rollback guard passes and the child is popped.
+		const getCurrentTask = vi.fn().mockReturnValue(parentTask)
+		const createTask = vi.fn().mockImplementation(async () => {
+			getCurrentTask.mockReturnValue(child)
+			return child
+		})
+
 		const provider = {
 			emit: vi.fn(),
-			getCurrentTask: vi.fn(() => parentTask),
+			getCurrentTask,
 			removeClineFromStack,
-			createTask: vi.fn().mockResolvedValue({ taskId: "child-1", start: childStart }),
+			createTask,
 			getTaskWithId,
 			handleModeSwitch: vi.fn().mockResolvedValue(undefined),
 			deleteTaskWithId,

src/__tests__/removeClineFromStack-delegation.spec.ts

@@ -79,6 +79,7 @@ describe("ClineProvider.removeClineFromStack() delegation awareness", () => {
 				id: "parent-1",
 				status: "active",
 				awaitingChildId: undefined,
+				delegatedToId: undefined,
 			}),
 		)