fix(gateway): preserve startup-failed agent waits

neilofneils404 · neilofneils404 · commit 83aefea57419 · 2026-05-05T17:48:13.000-04:00
diff --git a/src/gateway/server-methods/agent-job.ts b/src/gateway/server-methods/agent-job.ts
@@ -26,6 +26,7 @@ let agentRunListenerStarted = false;
 type AgentRunSnapshot = {
   runId: string;
   status: "ok" | "error" | "timeout";
+  phase?: "end" | "error" | "startup-failed";
   startedAt?: number;
   endedAt?: number;
   error?: string;
@@ -149,6 +150,7 @@ function createSnapshotFromLifecycleEvent(params: {
     runId,
     status:
       phase === "error" || phase === "startup-failed" ? "error" : data?.aborted ? "timeout" : "ok",
+    phase,
     startedAt,
     endedAt,
     error,
@@ -194,6 +196,10 @@ function ensureAgentRunListener() {
       phase,
       data: evt.data,
     });
+    const existing = getCachedAgentRun(evt.runId);
+    if (phase === "end" && existing?.phase === "startup-failed") {
+      return;
+    }
     agentRunStarts.delete(evt.runId);
     if (phase === "error") {
       schedulePendingAgentRunError(snapshot);
@@ -348,7 +354,7 @@ export async function waitForAgentJob(params: {
         clearPendingTimeoutTimer();
         return;
       }
-      if (phase !== "end" && phase !== "error") {
+      if (phase !== "end" && phase !== "error" && phase !== "startup-failed") {
         return;
       }
       const latest = ignoreCachedSnapshot ? undefined : getCachedAgentRun(runId);
@@ -365,6 +371,11 @@ export async function waitForAgentJob(params: {
         scheduleErrorFinish(snapshot);
         return;
       }
+      if (phase === "startup-failed") {
+        recordAgentRunSnapshot(snapshot);
+        finish(snapshot);
+        return;
+      }
       if (snapshot.status === "timeout") {
         scheduleTimeoutFinish(snapshot);
         return;
diff --git a/src/gateway/server-methods/server-methods.test.ts b/src/gateway/server-methods/server-methods.test.ts
@@ -95,6 +95,35 @@ describe("waitForAgentJob", () => {
     expect(snapshot?.endedAt).toBe(400);
   });
 
+  it("preserves startup-failed when a trailing lifecycle end follows", async () => {
+    const runId = `run-startup-failed-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    const waitPromise = waitForAgentJob({ runId, timeoutMs: 1_000 });
+
+    emitAgentEvent({
+      runId,
+      stream: "lifecycle",
+      data: { phase: "start", startedAt: 425 },
+    });
+    emitAgentEvent({
+      runId,
+      stream: "lifecycle",
+      data: { phase: "startup-failed", startedAt: 425, endedAt: 450, reason: "boot failed" },
+    });
+    emitAgentEvent({
+      runId,
+      stream: "lifecycle",
+      data: { phase: "end", startedAt: 425, endedAt: 500 },
+    });
+
+    const snapshot = await waitPromise;
+    expect(snapshot).not.toBeNull();
+    expect(snapshot?.status).toBe("error");
+    expect(snapshot?.phase).toBe("startup-failed");
+    expect(snapshot?.startedAt).toBe(425);
+    expect(snapshot?.endedAt).toBe(450);
+    expect(snapshot?.error).toBe("boot failed");
+  });
+
   it("ignores transient aborted end events when the same run later succeeds", async () => {
     const runId = `run-timeout-retry-${Date.now()}-${Math.random().toString(36).slice(2)}`;
     const waitPromise = waitForAgentJob({ runId, timeoutMs: 1_000 });
