Report cancelled and interrupted workers truthfully

Author: TheGreatAxios

docs/TELEMETRY.md

@@ -109,6 +109,10 @@ a truthy value (`1`, `true`, …) to restore per-call spans for debugging.
 Leaf `runSubAgent` workers do not emit `$ai_*`; worker rollups travel on
 `subagent_end` instead. Both TUI and exec install the same turn observer, so a
 worker ending during an active parent turn carries that turn's `parent_trace_id`.
+Pre-progress operator aborts settle with `status=cancelled` and
+`stop_reason=cancelled` even when the worker promise rejects. An interrupt that
+keeps a worker resumable settles with `status=interrupted` and the same
+`stop_reason=cancelled`; terminal events never report a still-running status.
 
 A deterministic representative fixture uses 10 parent turns with 80 parent tool
 calls and 4 workers totaling 24 turns and 96 tool calls. The former per-call and

src/subagent/agent-fleet.ts

@@ -549,9 +549,16 @@ export function createSpawnAgentTool(deps: AgentFleetDeps): AgentTool {
       const finalizeEnd = (setupFailed = false): void => {
         if (endFinalized) return;
         endFinalized = true;
+        const terminalSession = deps.sessions.get(session.id);
+        const status =
+          terminalSession?.status === "cancelled"
+            ? "cancelled"
+            : terminalSession?.lifecycleStatus === "interrupted"
+              ? "interrupted"
+              : (terminalSession?.status ?? "completed");
         captureSubagentEnd(telemetry, {
           agentName,
-          status: setupFailed ? "failed" : (deps.sessions.get(session.id)?.status ?? "completed"),
+          status: setupFailed ? "failed" : status,
           durationMs: Date.now() - startedAt,
           model: settlement?.model ?? provider.model,
           stopReason: setupFailed ? "setup_error" : (settlement?.terminal_reason ?? "error"),
@@ -731,6 +738,7 @@ export function createSpawnAgentTool(deps: AgentFleetDeps): AgentTool {
           // that never saw interrupt_agent (or raced it) cannot hang.
           if (result.interrupted === true) {
             keepWorktreeAlive = true;
+            deps.sessions.interruptOne(session.id);
             deps.fleetRecords.interrupt(session.id, result.report);
             return;
           }

src/subagent/run-settlement.test.ts

@@ -120,3 +120,65 @@ test("rejected workers settle prior rollups with the latest observed model", asy
   });
   expect(Object.isFrozen(settlement)).toBe(true);
 });
+
+test("pre-progress cancellation settles as cancelled without changing rejection", async () => {
+  const cwd = await mkdtemp(join(tmpdir(), "corbits-run-cancelled-"));
+  const controller = new AbortController();
+  const originalError = new DOMException("operator cancelled", "AbortError");
+  controller.abort(originalError);
+  let settlement: Readonly<SubAgentRunSettlement> | undefined;
+
+  const caught = await withMockedModuleDuring(
+    import.meta.resolve("../agent/live-tool-dispatch.js"),
+    (real: typeof import("../agent/live-tool-dispatch.js")) => ({
+      ...real,
+      createAgentWithLiveToolDispatch: async () => ({
+        send: async () => {
+          throw new Error("send must not start after cancellation");
+        },
+        stream: () => (async function* () {})(),
+        deliver: () => {},
+        close: async () => {},
+        setSource: () => {},
+        setSources: () => {},
+        history: async () => [],
+        checkpoints: async () => [],
+        readAt: async () => [],
+        blobReader: {},
+      }),
+    }),
+    async () => {
+      const { runSubAgent } = await import("./run.js");
+      try {
+        await runSubAgent({
+          cwd,
+          workdirBase: join(cwd, ".ctx"),
+          permissionGate,
+          provider: {
+            providerName: "initial",
+            baseURL: "http://localhost",
+            model: "initial-model",
+          },
+          description: "cancelled settlement probe",
+          prompt: "do not start",
+          signal: controller.signal,
+          onRunSettled: (summary) => {
+            settlement = summary;
+          },
+        });
+      } catch (error) {
+        return error;
+      }
+      throw new Error("expected runSubAgent to reject");
+    },
+  );
+
+  expect(caught).toBe(originalError);
+  expect(settlement).toMatchObject({
+    turn_count: 0,
+    error_count: 1,
+    model: "initial-model",
+    terminal_reason: "cancelled",
+  });
+  expect(Object.isFrozen(settlement)).toBe(true);
+});

src/subagent/run.ts

@@ -383,6 +383,7 @@ export async function runSubAgent(params: RunSubAgentParams): Promise<RunSubAgen
     return result;
   } catch (error) {
     errorCount = 1;
+    if (isSubAgentCancelError(error, params.signal)) terminalReason = "cancelled";
     throw error;
   } finally {
     try {

src/subagent/spawn-agent-worktree.test.ts

@@ -67,6 +67,14 @@ async function pathExists(path: string): Promise<boolean> {
   }
 }
 
+async function waitFor(predicate: () => boolean | Promise<boolean>): Promise<void> {
+  for (let attempt = 0; attempt < 500; attempt++) {
+    if (await predicate()) return;
+    await new Promise((resolve) => setTimeout(resolve, 1));
+  }
+  throw new Error("condition was not reached");
+}
+
 function deferred<T>(): {
   promise: Promise<T>;
   resolve: (v: T) => void;
@@ -170,6 +178,62 @@ describe("spawn_agent worktree isolation", () => {
     expect(typeof ends[0]?.properties.duration_ms).toBe("number");
   });
 
+  test("pairs pre-progress cancellation with a cancelled terminal event", async () => {
+    const repo = await makeRepo();
+    tempDirs.push(repo);
+    const { telemetry, events } = telemetryCapture();
+    const sessions = createSubAgentSessionStore();
+    const tool = createSpawnAgentTool({
+      permissionGate: testPermissionGate,
+      cwd: repo,
+      getWorkdirBase: () => repo,
+      provider,
+      telemetry,
+      run: async (params) => {
+        params.onRunSettled?.({
+          turn_count: 0,
+          input_tokens: 0,
+          output_tokens: 0,
+          cache_read_tokens: 0,
+          cache_write_tokens: 0,
+          reasoning_tokens: 0,
+          tool_call_count: 0,
+          tool_error_count: 0,
+          error_count: 1,
+          duration_ms: 1,
+          model: "test-model",
+          terminal_reason: "cancelled",
+        });
+        const error = new Error("aborted");
+        error.name = "AbortError";
+        throw error;
+      },
+      sessions,
+      fleetRecords: createFleetRecords(),
+    });
+    if (tool.kind !== "full") throw new Error("expected full tool");
+
+    const result = await tool.handler(
+      {
+        id: "cancelled-spawn",
+        name: "spawn_agent",
+        arguments: { description: "cancelled", prompt: "Do the work", intent: "explore" },
+      },
+      new AbortController().signal,
+    );
+
+    expect(result.isError).not.toBe(true);
+    await waitFor(() => events.some((event) => event.event === "subagent_end"));
+    expect(sessions.list()[0]?.status).toBe("cancelled");
+    expect(events.filter((event) => event.event === "subagent_start")).toHaveLength(1);
+    const ends = events.filter((event) => event.event === "subagent_end");
+    expect(ends).toHaveLength(1);
+    expect(ends[0]?.properties).toMatchObject({
+      status: "cancelled",
+      stop_reason: "cancelled",
+    });
+  });
+
   test("defers worktree cleanup while the session is retained for followup", async () => {
     const repo = await makeRepo();
     tempDirs.push(repo);
@@ -229,13 +293,17 @@ describe("spawn_agent worktree isolation", () => {
 
     const settle = deferred<RunSubAgentResult>();
     let workerCwd: string | undefined;
+    let settlementCount = 0;
+    let settlementWasFrozen = false;
+    const { telemetry, events } = telemetryCapture();
     const sessions = createSubAgentSessionStore();
     const tool = createSpawnAgentTool({
       permissionGate: testPermissionGate,
       cwd: repo,
       getWorkdirBase: () => workdirBase,
       provider,
       useWorktree: true,
+      telemetry,
       run: async (params) => {
         workerCwd = params.cwd;
         params.onAgentReady?.({
@@ -244,7 +312,25 @@ describe("spawn_agent worktree isolation", () => {
           followup: async () => "",
           deliver: () => {},
         });
-        return settle.promise;
+        const result = await settle.promise;
+        const summary = Object.freeze({
+          turn_count: 0,
+          input_tokens: 0,
+          output_tokens: 0,
+          cache_read_tokens: 0,
+          cache_write_tokens: 0,
+          reasoning_tokens: 0,
+          tool_call_count: 0,
+          tool_error_count: 0,
+          error_count: 0,
+          duration_ms: 1,
+          model: "test-model",
+          terminal_reason: "cancelled" as const,
+        });
+        settlementCount += 1;
+        settlementWasFrozen = Object.isFrozen(summary);
+        params.onRunSettled?.(summary);
+        return result;
       },
       sessions,
       fleetRecords: createFleetRecords(),
@@ -263,10 +349,20 @@ describe("spawn_agent worktree isolation", () => {
 
     settle.resolve({
       report: "## Summary\nStopped.\n## Findings\npartial\n## Blockers\ninterrupted\n## Paths\n",
+      stopReason: "cancelled",
       interrupted: true,
     });
-    await new Promise((resolve) => setTimeout(resolve, 50));
+    await waitFor(() => events.some((event) => event.event === "subagent_end"));
 
+    expect(settlementCount).toBe(1);
+    expect(settlementWasFrozen).toBe(true);
+    expect(sessions.get(agentId)?.lifecycleStatus).toBe("interrupted");
+    const ends = events.filter((event) => event.event === "subagent_end");
+    expect(ends).toHaveLength(1);
+    expect(ends[0]?.properties).toMatchObject({
+      status: "interrupted",
+      stop_reason: "cancelled",
+    });
     expect(workerCwd).toBeDefined();
     expect(await pathExists(workerCwd!)).toBe(true);
 
@@ -305,9 +401,11 @@ describe("spawn_agent worktree isolation", () => {
       },
       new AbortController().signal,
     );
-    await new Promise((resolve) => setTimeout(resolve, 50));
+    await waitFor(() => workerCwd !== undefined);
+    if (workerCwd === undefined) throw new Error("worker cwd was not captured");
+    const completedWorkerCwd = workerCwd;
+    await waitFor(async () => !(await pathExists(completedWorkerCwd)));
 
-    expect(workerCwd).toBeDefined();
-    expect(await pathExists(workerCwd!)).toBe(false);
+    expect(await pathExists(completedWorkerCwd)).toBe(false);
   });
 });

src/subagent/task-tool-worktree.test.ts

@@ -178,6 +178,53 @@ describe("createTaskTool worktree isolation", () => {
     expect(typeof ends[0]?.properties.duration_ms).toBe("number");
   });
 
+  test("pairs pre-progress cancellation with a cancelled terminal event", async () => {
+    const repo = await makeRepo();
+    tempDirs.push(repo);
+    const { telemetry, events } = telemetryCapture();
+    const tool = createTaskTool({
+      permissionGate: testPermissionGate,
+      cwd: repo,
+      getWorkdirBase: () => repo,
+      provider,
+      telemetry,
+      run: async (params) => {
+        params.onRunSettled?.({
+          turn_count: 0,
+          input_tokens: 0,
+          output_tokens: 0,
+          cache_read_tokens: 0,
+          cache_write_tokens: 0,
+          reasoning_tokens: 0,
+          tool_call_count: 0,
+          tool_error_count: 0,
+          error_count: 1,
+          duration_ms: 1,
+          model: "test-model",
+          terminal_reason: "cancelled",
+        });
+        const error = new Error("aborted");
+        error.name = "AbortError";
+        throw error;
+      },
+    });
+
+    const result = await callTask(tool, {
+      description: "cancelled job",
+      prompt: "Do the work",
+      intent: "explore",
+    });
+
+    expect(result).toContain("cancelled by operator");
+    expect(events.filter((event) => event.event === "subagent_start")).toHaveLength(1);
+    const ends = events.filter((event) => event.event === "subagent_end");
+    expect(ends).toHaveLength(1);
+    expect(ends[0]?.properties).toMatchObject({
+      status: "cancelled",
+      stop_reason: "cancelled",
+    });
+  });
+
   test("preserves a worktree the sub-agent left dirty, with a notice in the report", async () => {
     const repo = await makeRepo();
     tempDirs.push(repo);