feat(subagent): classify doom-loop worker stops as loop_guard

The reactor's doom-loop guard already stops workers, but the run ended
as a plain error and its class survived only in the reactor message.
The doom_loop run end reaches the stream after the send rejects, so the
run notes it in its stream sink and rethrows a typed error once
teardown has drained the stream. A forced-stop reason would have taken
the salvage path and turned the failed lane into a done one.

The run also reports when its own teardown fails, which is the release
step behind a partial cleanup outcome.

Author: bwachman

src/subagent/run-loop-guard.test.ts

@@ -0,0 +1,150 @@
+import { describe, expect, test } from "bun:test";
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
+import type { ReactorEmittedEvent } from "@intx/inference";
+
+import {
+  callFleetTool,
+  createFleetDeps,
+  deferred,
+  fleetTools,
+  spawnAgentId,
+} from "./fleet-test-harness.js";
+import {
+  baseRunParams,
+  stubAgent,
+  tmpSubAgentCwd,
+  withStubbedAgent,
+} from "./run-test-harness.js";
+import { isSubAgentLoopGuardError } from "./terminal-failure.js";
+import type {
+  RunSubAgentParams,
+  RunSubAgentResult,
+  SubAgentRunSettlement,
+} from "./types.js";
+
+const DOOM_MESSAGE =
+  "Doom loop detected: an identical tool batch (grep, glob) executed 3 times consecutively";
+
+type Run = (params: RunSubAgentParams) => Promise<RunSubAgentResult>;
+
+/**
+ * Replays the vendored reactor's doom-loop shutdown as a worker sees it: the
+ * fatal reactor.error rejects the send first, and the `doom_loop` run end
+ * only reaches the stream after that rejection.
+ */
+async function withRunEndingIn<T>(
+  kind: string,
+  body: (run: Run, cwd: string) => Promise<T>,
+): Promise<T> {
+  const cwd = await tmpSubAgentCwd("loop-guard-");
+  const sendRejected = deferred<undefined>();
+  try {
+    return await withStubbedAgent(
+      stubAgent({
+        send: async () => {
+          setTimeout(() => sendRejected.resolve(undefined), 0);
+          throw new Error(`reactor error: ${DOOM_MESSAGE}`);
+        },
+        stream: () =>
+          (async function* (): AsyncGenerator<ReactorEmittedEvent> {
+            yield {
+              type: "inference.start",
+              seq: 1,
+              data: { sourceId: "test", model: "test-model", input: [] },
+            } as unknown as ReactorEmittedEvent;
+            await sendRejected.promise;
+            yield {
+              type: "reactor.error",
+              seq: 2,
+              data: { error: DOOM_MESSAGE, fatal: true },
+            } as unknown as ReactorEmittedEvent;
+            yield {
+              type: "message.run.ended",
+              seq: 3,
+              data: {
+                messageRunId: "run-1",
+                messageId: "msg-1",
+                status: "failed",
+                error: { message: DOOM_MESSAGE, kind },
+              },
+            } as unknown as ReactorEmittedEvent;
+          })(),
+      }),
+      async () => {
+        const { runSubAgent } = await import("./run.js");
+        return body(runSubAgent, cwd);
+      },
+    );
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+}
+
+async function spawnAndCollect(
+  run: Run,
+  cwd: string,
+): Promise<Record<string, unknown>> {
+  const deps = createFleetDeps(run, { cwd });
+  deps.getWorkdirBase = () => join(cwd, ".ctx");
+  const tools = fleetTools(deps);
+  const id = await spawnAgentId(tools.spawn, {
+    description: "discovery",
+    prompt: "find it",
+    intent: "explore",
+  });
+  const waited = await callFleetTool(tools.wait, {
+    targets: [id],
+    timeout_ms: 5_000,
+  });
+  const rows = waited.results as Record<string, unknown>[];
+  return rows[0] ?? {};
+}
+
+describe("loop-guard termination", () => {
+  test("runSubAgent rethrows a doom-loop stop as a typed loop-guard error", async () => {
+    await withRunEndingIn("doom_loop", async (run, cwd) => {
+      let settled: SubAgentRunSettlement | undefined;
+      let caught: unknown;
+      try {
+        await run(
+          baseRunParams(cwd, {
+            onRunSettled: (summary) => {
+              settled = summary;
+            },
+          }),
+        );
+      } catch (error) {
+        caught = error;
+      }
+      expect(isSubAgentLoopGuardError(caught)).toBe(true);
+      expect((caught as Error).message).toBe(`reactor error: ${DOOM_MESSAGE}`);
+      // Telemetry stop_reason is unchanged: the run still ends as "error".
+      expect(settled?.terminal_reason).toBe("error");
+    });
+  });
+
+  test("the parent sees loop_guard, distinct from a provider failure", async () => {
+    await withRunEndingIn("doom_loop", async (run, cwd) => {
+      const row = await spawnAndCollect(run, cwd);
+      expect(row.status).toBe("failed");
+      expect(row.error).toBe(`reactor error: ${DOOM_MESSAGE}`);
+      expect(row.failure).toMatchObject({
+        failure_class: "loop_guard",
+        recovery: { available: false, reason: "not_retryable" },
+      });
+      expect(row.provider_failure).toBeUndefined();
+      expect(row.continuable).toBeUndefined();
+    });
+  });
+
+  test("a failed run end of another kind is not a loop guard", async () => {
+    await withRunEndingIn("reactor_fatal", async (run, cwd) => {
+      const row = await spawnAndCollect(run, cwd);
+      expect(row.status).toBe("failed");
+      expect((row.failure as { failure_class?: string }).failure_class).toBe(
+        "error",
+      );
+    });
+  });
+});

src/subagent/run-terminal-cleanup.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, test } from "bun:test";
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
+
+import {
+  callFleetTool,
+  createFleetDeps,
+  fleetTools,
+  spawnAgentId,
+} from "./fleet-test-harness.js";
+import {
+  stubAgent,
+  tmpSubAgentCwd,
+  withPosixDispose,
+  withStubbedAgent,
+} from "./run-test-harness.js";
+
+describe("terminal failure cleanup outcome", () => {
+  test.each([
+    ["a clean teardown", async (): Promise<void> => undefined, "released"],
+    [
+      "a teardown that leaves children behind",
+      async (): Promise<void> => {
+        throw new Error("1 shell child process still live after 2000ms reap");
+      },
+      "partial",
+    ],
+  ] as const)("%s records cleanup %s", async (_label, dispose, expected) => {
+    const cwd = await tmpSubAgentCwd("terminal-cleanup-");
+    try {
+      await withPosixDispose(dispose, () =>
+        withStubbedAgent(
+          stubAgent({
+            send: async () => {
+              throw new Error("send exploded");
+            },
+          }),
+          async () => {
+            const { runSubAgent } = await import("./run.js");
+            const deps = createFleetDeps(runSubAgent, { cwd });
+            deps.getWorkdirBase = () => join(cwd, ".ctx");
+            const tools = fleetTools(deps);
+            const id = await spawnAgentId(tools.spawn, {
+              description: "cleanup probe",
+              prompt: "fail",
+              intent: "explore",
+            });
+            const waited = await callFleetTool(tools.wait, {
+              targets: [id],
+              timeout_ms: 5_000,
+            });
+            const row = (waited.results as Record<string, unknown>[])[0];
+            expect(row?.status).toBe("failed");
+            expect(
+              (row?.failure as { cleanup?: string } | undefined)?.cleanup,
+            ).toBe(expected);
+          },
+        ),
+      );
+    } finally {
+      await rm(cwd, { recursive: true, force: true });
+    }
+  });
+});

src/subagent/run.ts

@@ -207,6 +207,7 @@ import type {
 
 import type { TaskIntent } from "./report.js";
 import { runWithSubAgentIdentity } from "./identity-context.js";
+import { createSubAgentLoopGuardError } from "./terminal-failure.js";
 
 /**
  * Worker authorization denies without suspending, so Agent.send must settle
@@ -600,7 +601,9 @@ export async function runSubAgent(
   };
   let terminalReason: SubAgentTerminalReason = "error";
   let errorCount = 0;
-  const settlementState = { latestModel: params.provider.model };
+  const settlementState: RunSettlementState = {
+    latestModel: params.provider.model,
+  };
 
   try {
     const result = await runSubAgentInner(
@@ -612,8 +615,16 @@ export async function runSubAgent(
     return result;
   } catch (error) {
     errorCount = 1;
-    if (isSubAgentCancelError(error, params.signal))
+    if (isSubAgentCancelError(error, params.signal)) {
       terminalReason = "cancelled";
+      throw error;
+    }
+    // CL-10202: the inner finally has drained the stream by now, so a
+    // doom_loop run end the reactor emitted after rejecting the send has
+    // been seen. Telemetry keeps terminal_reason "error".
+    if (settlementState.loopGuardTripped === true) {
+      throw createSubAgentLoopGuardError(error);
+    }
     throw error;
   } finally {
     try {
@@ -624,6 +635,9 @@ export async function runSubAgent(
           duration_ms: Date.now() - startedAt,
           model: settlementState.latestModel,
           terminal_reason: terminalReason,
+          ...(settlementState.teardownFailed === true
+            ? { teardown_failed: true as const }
+            : {}),
         }),
       );
     } catch {
@@ -632,10 +646,17 @@ export async function runSubAgent(
   }
 }
 
+interface RunSettlementState {
+  latestModel: string;
+  /** The reactor ended a message run with `error.kind: "doom_loop"`. */
+  loopGuardTripped?: boolean;
+  teardownFailed?: boolean;
+}
+
 async function runSubAgentInner(
   params: RunSubAgentParams,
   telemetryRollup: SubAgentTelemetryRollup,
-  settlementState: { latestModel: string },
+  settlementState: RunSettlementState,
 ): Promise<RunSubAgentResult> {
   // Fleet-spawned workers skip the pricing-cache seed re-read; the parent
   // runtime already applied the process seed at boot.
@@ -1420,6 +1441,13 @@ async function runSubAgentInner(
     const runSettlement = createRunEventSettlement();
     const streamSink = (rawEvent: ReactorEmittedEvent): void => {
       runSettlement.handleEvent(rawEvent);
+      if (
+        rawEvent.type === "message.run.ended" &&
+        rawEvent.data.status === "failed" &&
+        rawEvent.data.error?.kind === "doom_loop"
+      ) {
+        settlementState.loopGuardTripped = true;
+      }
       const event = sanitizeDiagnosticValue(rawEvent, [
         readSourceCredentialMaterial(workerSource.credentialId).secret,
       ]) as ReactorEmittedEvent;
@@ -1911,7 +1939,10 @@ async function runSubAgentInner(
           posixTools,
         }),
         params.teardownDeadlineMs ?? DEFAULT_CLOSE_DEADLINE_MS,
-      );
+      ).catch((teardownError: unknown) => {
+        settlementState.teardownFailed = true;
+        throw teardownError;
+      });
     }
   }
 }