fix(agents): skip stale orphaned subagent sessions during restart recovery

chengzhichao-xydt · chengzhichao-xydt · commit 6ccc0c1bc362 · 2026-06-11T16:11:57.000+08:00
Add an isLiveUnendedSubagentRun guard in subagent orphan recovery so stale restart-aborted runs are finalized with an error instead of being resumed. This prevents resurrecting long-abandoned subagent runs after gateway restarts. - src/agents/subagent-orphan-recovery.ts: Import isLiveUnendedSubagentRun. Before recovery, check if the run is still live. Stale runs finalized inline via finalizeInterruptedSubagentRun. +27 lines. - src/agents/subagent-orphan-recovery.test.ts: 3 regression tests for stale/fresh/extended-timeout scenarios through the full production code path. +119 lines. - docs/tools/subagents.md: Update liveness-and-recovery section to describe stale-run finalization behavior. Fixes #90766
diff --git a/docs/tools/subagents.md b/docs/tools/subagents.md
@@ -605,10 +605,14 @@ stop counting as active/pending in `/subagents list`, status summaries,
 descendant completion gating, and per-session concurrency checks.
 
 After a gateway restart, stale unended restored runs are pruned unless
-their child session is marked `abortedLastRun: true`. Those
-restart-aborted child sessions remain recoverable through the sub-agent
-orphan recovery flow, which sends a synthetic resume message before
-clearing the aborted marker.
+their child session is marked `abortedLastRun: true`. The orphan
+recovery flow checks whether the run is still within the subagent
+run-liveness window before attempting automatic recovery.
+Restart-aborted runs that exceed the configured liveness window are
+finalized with an error instead of being resumed, so long-abandoned
+subagents are not resurrected by gateway restarts. Runs still within
+the window remain recoverable: the flow sends a synthetic resume
+message before clearing the aborted marker.
 
 Automatic restart recovery is bounded per child session. If the same
 sub-agent child is accepted for orphan recovery repeatedly inside the
diff --git a/src/agents/subagent-orphan-recovery.test.ts b/src/agents/subagent-orphan-recovery.test.ts
@@ -658,4 +658,123 @@ describe("subagent-orphan-recovery", () => {
     expect(finalizeParams.error).toContain("Automatic recovery failed after 2 attempts");
     expect(finalizeParams.error).toContain("service restart");
   });
+
+  // ── Stale-run liveness gate ──────────────────────────────────────────
+
+  it("finalizes stale restart-aborted runs inline instead of resuming", async () => {
+    const staleStartedAt = Date.now() - 3 * 60 * 60 * 1_000;
+    vi.mocked(sessions.loadSessionStore).mockReturnValue({
+      "agent:main:subagent:test-session-1": {
+        sessionId: "session-abc",
+        updatedAt: Date.now(),
+        abortedLastRun: true,
+      },
+    });
+
+    const activeRuns = createActiveRuns(
+      createTestRunRecord({
+        // started 3 hours ago — exceeds the 2-hour STALE_UNENDED_SUBAGENT_RUN_MS window
+        startedAt: staleStartedAt,
+        sessionStartedAt: staleStartedAt,
+        createdAt: staleStartedAt - 60_000,
+      }),
+    );
+
+    const result = await recoverOrphanedSubagentSessions({
+      getActiveRuns: () => activeRuns,
+    });
+
+    expect(result.recovered).toBe(0);
+    expect(result.failed).toBe(0);
+    expect(result.skipped).toBe(1);
+    expect(gateway.callGateway).not.toHaveBeenCalled();
+    expect(
+      subagentRegistrySteerRuntime.finalizeInterruptedSubagentRun,
+    ).toHaveBeenCalledOnce();
+    const finalizeParams = requireRecord(
+      firstCallParam(
+        vi.mocked(subagentRegistrySteerRuntime.finalizeInterruptedSubagentRun)
+          .mock.calls,
+        "stale run finalization",
+      ),
+      "stale run finalization params",
+    );
+    expect(finalizeParams.runId).toBe("run-1");
+    expect(finalizeParams.childSessionKey).toBe(
+      "agent:main:subagent:test-session-1",
+    );
+    expect(finalizeParams.error).toContain(
+      "Subagent run was orphaned past the run-liveness window",
+    );
+  });
+
+  it("recovers fresh restart-aborted runs that are within the liveness window", async () => {
+    const freshStartedAt = Date.now() - 30 * 60 * 1_000;
+    vi.mocked(gateway.callGateway).mockResolvedValue({ runId: "resumed-fresh" } as never);
+    vi.mocked(sessions.loadSessionStore).mockReturnValue({
+      "agent:main:subagent:test-session-1": {
+        sessionId: "session-abc",
+        updatedAt: Date.now(),
+        abortedLastRun: true,
+      },
+    });
+
+    const activeRuns = createActiveRuns(
+      createTestRunRecord({
+        // 30 minutes ago — well within the 2-hour window
+        startedAt: freshStartedAt,
+        sessionStartedAt: freshStartedAt,
+        createdAt: freshStartedAt - 60_000,
+      }),
+    );
+
+    const result = await recoverOrphanedSubagentSessions({
+      getActiveRuns: () => activeRuns,
+    });
+
+    expect(result.failed).toBe(0);
+    expect(result.skipped).toBe(0);
+    expect(result.recovered).toBe(1);
+    expect(gateway.callGateway).toHaveBeenCalledOnce();
+    expect(
+      subagentRegistrySteerRuntime.finalizeInterruptedSubagentRun,
+    ).not.toHaveBeenCalled();
+  });
+
+  it("recovers old restart-aborted runs that carry an explicit long timeout extending the window", async () => {
+    const extendedStartedAt = Date.now() - 4 * 60 * 60 * 1_000;
+    vi.mocked(gateway.callGateway).mockResolvedValue({ runId: "resumed-extended" } as never);
+    vi.mocked(sessions.loadSessionStore).mockReturnValue({
+      "agent:main:subagent:test-session-1": {
+        sessionId: "session-abc",
+        updatedAt: Date.now(),
+        abortedLastRun: true,
+      },
+    });
+
+    const activeRuns = createActiveRuns(
+      createTestRunRecord({
+        // 4 hours ago — exceeds the default 2h window,
+        // but the explicit 6-hour runTimeoutSeconds extends the cutoff to ~6h 1m
+        startedAt: extendedStartedAt,
+        sessionStartedAt: extendedStartedAt,
+        createdAt: extendedStartedAt - 60_000,
+        runTimeoutSeconds: 6 * 60 * 60,
+      }),
+    );
+
+    const result = await recoverOrphanedSubagentSessions({
+      getActiveRuns: () => activeRuns,
+    });
+
+    expect(result.failed).toBe(0);
+    expect(result.skipped).toBe(0);
+    expect(result.recovered).toBe(1);
+    expect(result.failed).toBe(0);
+    expect(result.skipped).toBe(0);
+    expect(gateway.callGateway).toHaveBeenCalledOnce();
+    expect(
+      subagentRegistrySteerRuntime.finalizeInterruptedSubagentRun,
+    ).not.toHaveBeenCalled();
+  });
 });
diff --git a/src/agents/subagent-orphan-recovery.ts b/src/agents/subagent-orphan-recovery.ts
@@ -24,6 +24,7 @@ import { readSessionMessagesAsync } from "../gateway/session-utils.fs.js";
 import { formatErrorMessage } from "../infra/errors.js";
 import { createSubsystemLogger } from "../logging/subsystem.js";
 import { resolveInternalSessionEffectsTranscriptPath } from "./internal-session-effects.js";
+import { isLiveUnendedSubagentRun } from "./subagent-run-liveness.js";
 import {
   evaluateSubagentRecoveryGate,
   markSubagentRecoveryAttempt,
@@ -253,6 +254,32 @@ export async function recoverOrphanedSubagentSessions(params: {
           continue;
         }
 
+        // If the run is stale per the existing subagent-run liveness policy,
+        // finalize it instead of attempting automatic recovery. This prevents
+        // resurrecting long-abandoned subagent runs after a gateway restart.
+        // We finalize inline (not via failedRuns) so the parent is notified
+        // immediately rather than waiting for scheduleOrphanRecovery retries.
+        if (!isLiveUnendedSubagentRun(runRecord, now)) {
+          log.warn(
+            `skipping orphan recovery for ${childSessionKey}: subagent run is stale (startedAt=${runRecord.startedAt})`,
+          );
+          try {
+            await finalizeInterruptedSubagentRun({
+              runId,
+              childSessionKey,
+              error:
+                "Subagent run was orphaned past the run-liveness window and " +
+                "could not be automatically recovered. Please retry.",
+            });
+          } catch (finalizeErr) {
+            log.warn(
+              `failed to finalize stale orphaned subagent run ${runId}: ${String(finalizeErr)}`,
+            );
+          }
+          result.skipped++;
+          continue;
+        }
+
         const recoveryGate = evaluateSubagentRecoveryGate(entry, now);
         if (!recoveryGate.allowed) {
           if (recoveryGate.shouldMarkWedged) {
