fix: preserve subagent delivery after lock stalls

Galin Iliev · Galin Iliev · commit f9c6fc7de291 · 2026-05-25T15:15:18.000Z
diff --git a/src/agents/session-write-lock.test.ts b/src/agents/session-write-lock.test.ts
@@ -215,10 +215,21 @@ describe("acquireSessionWriteLock", () => {
 
   it("does not reenter locks by default in the same process", async () => {
     await withTempSessionLockFile(async ({ sessionFile }) => {
+      pinCurrentProcessStartTimeForTest();
       const lock = await acquireSessionWriteLock({ sessionFile, timeoutMs: 500 });
-      await expect(
-        acquireSessionWriteLock({ sessionFile, timeoutMs: 5, staleMs: 60_000 }),
-      ).rejects.toThrow(/session file locked/);
+      let error: unknown;
+      try {
+        await acquireSessionWriteLock({ sessionFile, timeoutMs: 5, staleMs: 60_000 });
+      } catch (err) {
+        error = err;
+      }
+      expect(error).toBeInstanceOf(Error);
+      expect(String((error as { owner?: unknown }).owner)).toContain(`pid=${process.pid}`);
+      expect(String((error as { owner?: unknown }).owner)).toContain("alive=true");
+      expect(String((error as { owner?: unknown }).owner)).toContain(
+        `starttime=${FAKE_STARTTIME}`,
+      );
+      expect(error).toHaveProperty("message", expect.stringContaining("currentStarttime=12345"));
       await lock.release();
     });
   });
diff --git a/src/agents/session-write-lock.ts b/src/agents/session-write-lock.ts
@@ -637,6 +637,35 @@ function inspectLockPayloadForSession(params: {
   return inspected;
 }
 
+function formatSessionLockTimeoutOwner(params: {
+  payload: LockFilePayload | null;
+  inspected: LockInspectionDetails;
+}): string {
+  const parts = [
+    params.inspected.pid === null ? "pid=unknown" : `pid=${params.inspected.pid}`,
+    `alive=${params.inspected.pidAlive}`,
+  ];
+  if (typeof params.payload?.starttime === "number") {
+    parts.push(`starttime=${params.payload.starttime}`);
+    if (params.inspected.pid !== null && params.inspected.pidAlive) {
+      const currentStarttime = resolveProcessStartTimeForLock(params.inspected.pid);
+      parts.push(`currentStarttime=${currentStarttime ?? "unknown"}`);
+    }
+  } else {
+    parts.push("starttime=missing");
+  }
+  if (params.inspected.createdAt) {
+    parts.push(`createdAt=${params.inspected.createdAt}`);
+  }
+  if (params.inspected.ageMs !== null) {
+    parts.push(`ageMs=${params.inspected.ageMs}`);
+  }
+  if (params.inspected.staleReasons.length > 0) {
+    parts.push(`staleReasons=${params.inspected.staleReasons.join(",")}`);
+  }
+  return parts.join(" ");
+}
+
 export async function cleanStaleLockFiles(params: {
   sessionsDir: string;
   config?: SessionWriteLockAcquireTimeoutConfig;
@@ -783,7 +812,16 @@ export async function acquireSessionWriteLock(params: {
       }
       const timeoutLockPath = (err as { lockPath?: string }).lockPath ?? lockPath;
       const payload = await readLockPayload(timeoutLockPath);
-      const owner = typeof payload?.pid === "number" ? `pid=${payload.pid}` : "unknown";
+      const inspected = inspectLockPayloadForSession({
+        payload,
+        staleMs,
+        nowMs: Date.now(),
+        heldByThisProcess: sessionLockHeldByThisProcess(normalizedSessionFile),
+        reclaimLockWithoutStarttime: true,
+        readOwnerProcessArgs: readProcessArgsSync,
+        respectMaxHold: true,
+      });
+      const owner = formatSessionLockTimeoutOwner({ payload, inspected });
       throw new SessionWriteLockTimeoutError({ timeoutMs, owner, lockPath: timeoutLockPath });
     }
   }
diff --git a/src/agents/subagent-registry.test.ts b/src/agents/subagent-registry.test.ts
@@ -1864,7 +1864,11 @@ describe("subagent registry seam flow", () => {
         suspendedAt: undefined,
         suspendedReason: undefined,
         discardedAt: now,
-        discardReason: "expired",
+        discardReason: "expired-after-durable-fallback",
+      },
+      completion: {
+        fallbackResultText: "large final payload",
+        fallbackCapturedAt: now,
       },
       cleanupHandled: true,
       cleanupCompletedAt: now,
diff --git a/src/agents/subagent-registry.ts b/src/agents/subagent-registry.ts
@@ -704,9 +704,12 @@ async function discardSuspendedPendingFinalDelivery(
 ): Promise<void> {
   const delivery = ensureDeliveryState(entry);
   const payload = delivery.payload;
+  const durableFallbackText = payload?.frozenResultText ?? payload?.fallbackFrozenResultText;
+  const persistedDurableFallback =
+    reason === "expired" && typeof durableFallbackText === "string" && durableFallbackText.length > 0;
   delivery.status = "discarded";
   delivery.discardedAt = now;
-  delivery.discardReason = reason;
+  delivery.discardReason = persistedDurableFallback ? "expired-after-durable-fallback" : reason;
   delivery.discardedPayloadSummary = {
     requesterSessionKey: payload?.requesterSessionKey ?? entry.requesterSessionKey,
     childSessionKey: payload?.childSessionKey ?? entry.childSessionKey,
@@ -724,15 +727,20 @@ async function discardSuspendedPendingFinalDelivery(
   delivery.suspendedReason = undefined;
   entry.wakeOnDescendantSettle = undefined;
   const completion = ensureCompletionState(entry);
-  completion.fallbackResultText = undefined;
-  completion.fallbackCapturedAt = undefined;
+  if (persistedDurableFallback) {
+    completion.fallbackResultText = durableFallbackText;
+    completion.fallbackCapturedAt = now;
+  } else {
+    completion.fallbackResultText = undefined;
+    completion.fallbackCapturedAt = undefined;
+  }
   entry.cleanupHandled = true;
   delivery.announcedAt = undefined;
   resumedRuns.delete(runId);
   clearPendingLifecycleError(runId);
   clearPendingLifecycleTimeout(runId);
   log.warn("subagent suspended delivery discarded", {
-    reason,
+    reason: delivery.discardReason,
     runId: entry.runId,
     childSessionKey: entry.childSessionKey,
     requesterSessionKey: entry.requesterSessionKey,
diff --git a/src/agents/subagent-registry.types.ts b/src/agents/subagent-registry.types.ts
@@ -59,7 +59,7 @@ export type SubagentCompletionDeliveryState = {
   suspendedAt?: number;
   suspendedReason?: "retry-limit" | "expiry";
   discardedAt?: number;
-  discardReason?: "expired" | "pressure-pruned";
+  discardReason?: "expired" | "expired-after-durable-fallback" | "pressure-pruned";
   discardedPayloadSummary?: {
     requesterSessionKey?: string;
     childSessionKey?: string;
