docs(e2e): clarify subtask drain invariants from code review

Author: edelauna

apps/vscode-e2e/AGENTS.md

@@ -121,6 +121,17 @@ Example:
 
 The `model` field can be added to either match when a test targets a specific model.
 
+## Delaying a fixture response (simulating a slow or hung provider)
+
+Use `streamingProfile: { ttft: <ms> }` on a fixture, not a flat `latency: <ms>`, when a test needs
+to simulate a slow or hung provider (e.g. to cancel an in-flight request mid-stream). `ttft` delays
+only the first SSE chunk, so the pending window is exactly the configured value. Flat `latency`
+delays _every_ chunk, and aimock never observes client disconnects — after a test cancels the
+request, a flat-latency stream keeps flushing chunks server-side for `chunks × latency` before
+reaching the dead socket, which can interleave with the next test's request against the same mock
+server. See `SUBTASK_API_HANG_RESPONSE_LATENCY_MS` in `fixtures/subtasks.ts` for an example,
+including the bounded post-test drain the calling suite uses to wait out that window.
+
 ## 404 errors in logs are expected
 
 Background API calls from the extension (usage collection, initialization) hit aimock with no matching fixture and return 404. These do **not** affect test results — the tests still pass. You'll see `[OpenRouter] API error: { message: '404 No fixture matched' }` in the output; this is normal.

apps/vscode-e2e/src/fixtures/subtasks.ts

@@ -35,6 +35,8 @@ export const SUBTASK_API_HANG_PARENT_RESULT = "API hang parent resumed"
 
 // How long the API-hang child's first mocked response stays pending before its first SSE
 // chunk. Shared with the subtask suite so its post-test drain waits exactly one window.
+// Correctness depends on no flat `latency` (fixture or LLMock default) being set on that
+// fixture — a flat latency would apply to every chunk after the first, not just the ttft.
 export const SUBTASK_API_HANG_RESPONSE_LATENCY_MS = 15_000
 
 // Abandon-subtask scenario (#559) — separate markers to avoid sequenceIndex collisions with the
@@ -270,9 +272,8 @@ export function addSubtaskFixtures(mock: InstanceType<typeof LLMock>) {
 		// applies `latency` to EVERY chunk and never observes client disconnects, so after the test
 		// cancels, a flat-latency stream would stay pending server-side for chunks × latency before
 		// flushing to the dead socket. With ttft the pending window is exactly
-		// SUBTASK_API_HANG_RESPONSE_LATENCY_MS, which is what the suite's post-test drain waits out.
-		// This relies on no flat `latency` (fixture or LLMock default) being set — a flat latency
-		// would still apply to every chunk after the first.
+		// SUBTASK_API_HANG_RESPONSE_LATENCY_MS (see its doc comment for the no-flat-latency
+		// invariant this relies on), which is what the suite's post-test drain waits out.
 		streamingProfile: { ttft: SUBTASK_API_HANG_RESPONSE_LATENCY_MS },
 		response: {
 			toolCalls: [

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

@@ -70,9 +70,12 @@ const findAimockRequest = (entries: AimockJournalEntry[], expectedText: string,
 		)
 	})
 
-// Returns the journal timestamp of the matching request so callers can anchor
-// post-test drains to the exact request this test created.
-const waitForAimockRequestContaining = async (expectedText: string, excludeText?: string) => {
+// Waits for a matching request to appear in the aimock journal and returns its journal
+// timestamp, so callers can anchor post-test drains to the exact request this test created.
+const waitForAimockRequestContaining = async (
+	expectedText: string,
+	excludeText?: string,
+): Promise<number | undefined> => {
 	let matchedAt: number | undefined
 
 	await waitFor(async () => {
@@ -83,8 +86,9 @@ const waitForAimockRequestContaining = async (expectedText: string, excludeText?
 	return matchedAt
 }
 
-// Grace period after the delayed window for aimock to flush the stream's remaining
-// chunks to the dead socket.
+// Grace period after the delayed window for aimock to flush the stream's remaining chunks to
+// the dead socket. 500ms is an empirical margin for that flush plus socket teardown; if this
+// suite becomes flaky again on slow CI runners, widen this value first.
 const SUBTASK_API_HANG_DRAIN_GRACE_MS = 500
 
 // aimock does not observe client disconnects: after the API-hang child request is cancelled,