feat(TaskRegistry): introduce TaskRegistry and migrate clineStack

Author: edelauna

src/__tests__/helpers/provider-stub.ts

@@ -1,11 +1,16 @@
 import { ClineProvider } from "../../core/webview/ClineProvider"
+import { TaskRegistry } from "../../core/task/TaskRegistry"
+import { type Task } from "../../core/task/Task"
 
 /**
  * Augments a plain stub object with the instance fields and bound methods that
  * ClineProvider methods read from `this` (runDelegationTransition,
  * delegationTransitionLocks, cancelledDelegationChildIds, cancellingDelegationChildIds),
  * so tests can call private methods via `(ClineProvider.prototype as any).method.call(stub, …)`
  * without instantiating a real ClineProvider.
+ *
+ * Pass `tasks` (array of Task mocks) to pre-seed the registry in stack order.
+ * The legacy `clineStack` key is accepted and converted automatically.
  */
 export function makeProviderStub<T extends object>(stub: T): T {
 	const s = stub as any
@@ -14,6 +19,16 @@ export function makeProviderStub<T extends object>(stub: T): T {
 	s.cancelledDelegationChildIds ??= new Set()
 	s.log ??= vi.fn()
 	s.taskHistoryStore ??= { get: () => undefined }
+
+	// Convert legacy clineStack array into a TaskRegistry
+	if (!s.taskRegistry) {
+		const registry = new TaskRegistry()
+		const seed: Task[] = s.clineStack ?? s.tasks ?? []
+		for (const t of seed) registry.push(t)
+		s.taskRegistry = registry
+	}
+	delete s.clineStack
+
 	s.runDelegationTransition = proto.runDelegationTransition.bind(s)
 	s.removeClineFromStack ??= proto.removeClineFromStack.bind(s)
 	s.evictCurrentTask ??= proto.evictCurrentTask.bind(s)

src/__tests__/removeClineFromStack-delegation.spec.ts

@@ -4,7 +4,7 @@ import { describe, it, expect, vi } from "vitest"
 import { ClineProvider } from "../core/webview/ClineProvider"
 import { makeProviderStub } from "./helpers/provider-stub"
 
-// After the refactor: removeClineFromStack() is pure lifecycle — it pops, aborts, and
+// After the refactor: removeClineFromStack() is pure lifecycle — it removes the focused task, aborts, and
 // cleans up listeners. It does NOT mutate delegation metadata. All delegated→active
 // transitions are owned by reopenParentFromDelegation() (normal child completion) or
 // markDelegatedChildInterrupted() (live eviction via navigation / new-task / clear).
@@ -49,17 +49,47 @@ function buildMockProvider(opts: {
 }
 
 describe("ClineProvider.removeClineFromStack() — pure lifecycle, no delegation side effects", () => {
-	it("pops the task, aborts it, and clears listeners", async () => {
+	it("removes the focused task, aborts it, and clears listeners", async () => {
 		const { provider, childTask } = buildMockProvider({ childTaskId: "child-1" })
-		expect(provider.clineStack).toHaveLength(1)
+		expect((provider as any).taskRegistry.length).toBe(1)
 
 		await (ClineProvider.prototype as any).removeClineFromStack.call(provider)
 
-		expect(provider.clineStack).toHaveLength(0)
+		expect((provider as any).taskRegistry.length).toBe(0)
 		expect(childTask.abortTask).toHaveBeenCalledWith(true)
 		expect(childTask.emit).toHaveBeenCalledWith(expect.stringContaining("taskUnfocused"))
 	})
 
+	it("removes the focused task even when it is not the top stack entry", async () => {
+		const focusedTask = {
+			taskId: "focused-1",
+			instanceId: "focused-inst",
+			emit: vi.fn(),
+			abortTask: vi.fn().mockResolvedValue(undefined),
+		}
+		const topTask = {
+			taskId: "top-1",
+			instanceId: "top-inst",
+			emit: vi.fn(),
+			abortTask: vi.fn().mockResolvedValue(undefined),
+		}
+		const provider = makeProviderStub({
+			tasks: [focusedTask, topTask] as any[],
+			taskEventListeners: new Map(),
+			log: vi.fn(),
+			getTaskWithId: vi.fn(),
+			updateTaskHistory: vi.fn(),
+		})
+		;(provider as any).taskRegistry.setCurrent("focused-1")
+
+		await (ClineProvider.prototype as any).removeClineFromStack.call(provider)
+
+		expect((provider as any).taskRegistry.taskIds).toEqual(["top-1"])
+		expect((provider as any).taskRegistry.current).toBe(topTask)
+		expect(focusedTask.abortTask).toHaveBeenCalledWith(true)
+		expect(topTask.abortTask).not.toHaveBeenCalled()
+	})
+
 	it("does NOT mutate parent metadata when a delegated child is popped (repair removed)", async () => {
 		const { provider, updateTaskHistory, getTaskWithId } = buildMockProvider({
 			childTaskId: "child-1",
@@ -74,7 +104,7 @@ describe("ClineProvider.removeClineFromStack() — pure lifecycle, no delegation
 
 		await (ClineProvider.prototype as any).removeClineFromStack.call(provider)
 
-		expect(provider.clineStack).toHaveLength(0)
+		expect((provider as any).taskRegistry.length).toBe(0)
 		// Navigation/disposal must never silently flip the parent to active
 		expect(getTaskWithId).not.toHaveBeenCalled()
 		expect(updateTaskHistory).not.toHaveBeenCalled()
@@ -94,7 +124,7 @@ describe("ClineProvider.removeClineFromStack() — pure lifecycle, no delegation
 
 		await (ClineProvider.prototype as any).removeClineFromStack.call(provider)
 
-		expect(provider.clineStack).toHaveLength(0)
+		expect((provider as any).taskRegistry.length).toBe(0)
 		expect(getTaskWithId).not.toHaveBeenCalled()
 		expect(updateTaskHistory).not.toHaveBeenCalled()
 	})
@@ -106,7 +136,7 @@ describe("ClineProvider.removeClineFromStack() — pure lifecycle, no delegation
 
 		await (ClineProvider.prototype as any).removeClineFromStack.call(provider)
 
-		expect(provider.clineStack).toHaveLength(0)
+		expect((provider as any).taskRegistry.length).toBe(0)
 		expect(getTaskWithId).not.toHaveBeenCalled()
 		expect(updateTaskHistory).not.toHaveBeenCalled()
 	})
@@ -490,7 +520,7 @@ describe("ClineProvider.evictCurrentTask() — active delegated child path", ()
 
 		await (ClineProvider.prototype as any).evictCurrentTask.call(provider)
 
-		expect(provider.clineStack).toHaveLength(0)
+		expect((provider as any).taskRegistry.length).toBe(0)
 		expect(markDelegatedChildInterrupted).toHaveBeenCalledWith({ childTaskId, parentTaskId })
 	})
 

src/__tests__/single-open-invariant.spec.ts

@@ -2,6 +2,7 @@
 
 import { describe, it, expect, vi, beforeEach } from "vitest"
 import { ClineProvider } from "../core/webview/ClineProvider"
+import { TaskRegistry } from "../core/task/TaskRegistry"
 import { API } from "../extension/api"
 import * as ProfileValidatorMod from "../shared/ProfileValidator"
 
@@ -39,10 +40,11 @@ describe("Single-open-task invariant", () => {
 		const removeClineFromStack = vi.fn().mockResolvedValue(undefined)
 		const addClineToStack = vi.fn().mockResolvedValue(undefined)
 
-		const existingTask = { taskId: "existing-1" }
+		const existingTask = { taskId: "existing-1", abort: false, abandoned: false }
+		const registry = new TaskRegistry()
+		registry.push(existingTask as any)
 		const provider = {
-			// Simulate an existing task present in stack
-			clineStack: [existingTask],
+			taskRegistry: registry,
 			getCurrentTask: vi.fn(() => existingTask),
 			taskHistoryStore: { get: vi.fn(() => undefined) },
 			markDelegatedChildInterrupted: vi.fn().mockResolvedValue(undefined),
@@ -85,10 +87,12 @@ describe("Single-open-task invariant", () => {
 
 		const removeClineFromStack = vi.fn().mockResolvedValue(undefined)
 		const addClineToStack = vi.fn().mockResolvedValue(undefined)
-		const parentTask = { taskId: "parent-1" }
+		const parentTask = { taskId: "parent-1", abort: false, abandoned: false }
+		const registry2 = new TaskRegistry()
+		registry2.push(parentTask as any)
 
 		const provider = {
-			clineStack: [parentTask],
+			taskRegistry: registry2,
 			setValues: vi.fn(),
 			getState: vi.fn().mockResolvedValue({
 				apiConfiguration: { apiProvider: "anthropic", consecutiveMistakeLimit: 0 },

src/core/task/TaskRegistry.ts

@@ -0,0 +1,114 @@
+import { type Task } from "./Task"
+
+/**
+ * Expand-Contract adapter replacing `clineStack: Task[]` in ClineProvider.
+ *
+ * Phase A+B: adapter is live, all 23 call sites migrated, concurrent access
+ * methods available. Maintains a LIFO stack of task IDs alongside a Map for
+ * O(1) lookup. Invariant: tasks.size === stack.length at all times.
+ *
+ * Phase C (future): remove internal stack once all callers use map-based access.
+ */
+export class TaskRegistry {
+	private tasks = new Map<string, Task>()
+	private stack: string[] = []
+	private _currentTaskId: string | undefined
+
+	push(task: Task): void {
+		if (this.tasks.has(task.taskId)) {
+			this.remove(task.taskId)
+		}
+		this.tasks.set(task.taskId, task)
+		this.stack.push(task.taskId)
+		this._currentTaskId = task.taskId
+	}
+
+	pop(): Task | undefined {
+		const id = this.stack.pop()
+		if (id === undefined) return undefined
+		const task = this.tasks.get(id)
+		this.tasks.delete(id)
+		if (this._currentTaskId === id) {
+			this._currentTaskId = this.stack[this.stack.length - 1]
+		}
+		return task
+	}
+
+	get current(): Task | undefined {
+		return this._currentTaskId !== undefined ? this.tasks.get(this._currentTaskId) : undefined
+	}
+
+	/**
+	 * Switch UI focus to a different task without mutating the stack order.
+	 * Throws if the taskId is not in the registry.
+	 */
+	setCurrent(taskId: string): void {
+		if (!this.tasks.has(taskId)) {
+			throw new Error(`[TaskRegistry] setCurrent: unknown taskId ${taskId}`)
+		}
+		this._currentTaskId = taskId
+	}
+
+	getById(id: string): Task | undefined {
+		return this.tasks.get(id)
+	}
+
+	getAll(): Task[] {
+		return this.stack.map((id) => this.tasks.get(id)!)
+	}
+
+	/** All tasks that are not aborted or abandoned. */
+	getRunning(): Task[] {
+		return this.getAll().filter((t) => !t.abort && !t.abandoned)
+	}
+
+	/** True only if the task is in the registry and is not aborted or abandoned. */
+	hasRunning(taskId: string): boolean {
+		const t = this.tasks.get(taskId)
+		return t !== undefined && !t.abort && !t.abandoned
+	}
+
+	/** Remove a task by ID regardless of its stack position. */
+	remove(taskId: string): Task | undefined {
+		const task = this.tasks.get(taskId)
+		if (task === undefined) return undefined
+		this.tasks.delete(taskId)
+		const idx = this.stack.indexOf(taskId)
+		if (idx !== -1) this.stack.splice(idx, 1)
+		if (this._currentTaskId === taskId) {
+			this._currentTaskId = this.stack[this.stack.length - 1]
+		}
+		return task
+	}
+
+	/**
+	 * Replace a task in-place: same stack index, same current pointer.
+	 * Used by rehydration so focus and stack order are both preserved.
+	 * Throws if taskId is not in the registry.
+	 */
+	replace(taskId: string, replacement: Task): Task {
+		const idx = this.stack.indexOf(taskId)
+		if (idx === -1) {
+			throw new Error(`[TaskRegistry] replace: unknown taskId ${taskId}`)
+		}
+		if (replacement.taskId !== taskId && this.tasks.has(replacement.taskId)) {
+			throw new Error(`[TaskRegistry] replace: duplicate taskId ${replacement.taskId}`)
+		}
+		const old = this.tasks.get(taskId)!
+		this.tasks.delete(taskId)
+		this.tasks.set(replacement.taskId, replacement)
+		this.stack[idx] = replacement.taskId
+		if (this._currentTaskId === taskId) {
+			this._currentTaskId = replacement.taskId
+		}
+		return old
+	}
+
+	get length(): number {
+		return this.stack.length
+	}
+
+	get taskIds(): string[] {
+		return [...this.stack]
+	}
+}