fix(threads): a watch also holds a thread that never ran

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Author: t3dotgg

packages/client-runtime/src/state/entities.test.ts

@@ -155,6 +155,28 @@ describe("V2 client presentation", () => {
     ]);
   });
 
+  it("parks a thread that never ran at idle while a pull request watch holds it", () => {
+    const watch = { taskId: "pull-request-watch:github.com/acme/app#1", kind: "monitor" as const };
+    const watched = presentThreadShell(environmentId, {
+      ...v2ThreadShell,
+      latestRunId: null,
+      activeProviderThreadId: null,
+      activeRunId: null,
+      status: "idle",
+      pendingBackgroundTasks: [watch],
+    });
+    expect(watched.runtime).toMatchObject({ status: "idle", activeRunId: null });
+    expect(
+      presentThreadShell(environmentId, {
+        ...v2ThreadShell,
+        latestRunId: null,
+        activeProviderThreadId: null,
+        status: "idle",
+        pendingBackgroundTasks: [],
+      }).runtime,
+    ).toBeNull();
+  });
+
   it.each([
     { kinds: ["command"], expected: "completed" },
     { kinds: ["command", "subagent"], expected: "idle" },

packages/client-runtime/src/state/models.ts

@@ -174,10 +174,13 @@ function terminalRunStatus(status: OrchestrationV2RunStatus): boolean {
 // latestRun keeps the latest run's status for history presentation.
 // A failed latest run outranks the roster, so the failure stays visible.
 function shellRuntime(thread: OrchestrationV2ThreadShell): ThreadRuntimeSummary | null {
-  if (thread.latestRunId === null && thread.activeProviderThreadId === null) return null;
   const parkAtIdle =
     backgroundWorkHoldsCompletion(thread.pendingBackgroundTasks ?? []) &&
     thread.status !== "failed";
+  // A pull request watch can hold a thread that never ran.
+  if (thread.latestRunId === null && thread.activeProviderThreadId === null && !parkAtIdle) {
+    return null;
+  }
   const status = parkAtIdle ? "idle" : (thread.activityRunStatus ?? thread.status);
   return {
     status,

packages/client-runtime/src/state/threadExecution.ts

@@ -234,9 +234,6 @@ export function deriveThreadRuntime(
   const liveActivityRun = latestMatchingRun(projection, (run) =>
     ACTIVITY_RUN_STATUSES.has(run.status),
   );
-  if (latestRun === null && projection.thread.activeProviderThreadId === null) return null;
-  const activeRunId =
-    latestMatchingRun(projection, (run) => INTERRUPTIBLE_RUN_STATUSES.has(run.status))?.id ?? null;
   // Same rule as the shell runtime: only background work that holds the
   // completion parks the thread at idle; a dev server left running does not.
   const backgroundWorkHoldsRun = backgroundWorkHoldsCompletion(
@@ -249,6 +246,16 @@ export function deriveThreadRuntime(
       pullRequests: projection.thread.pullRequests,
     }),
   );
+  // A pull request watch can hold a thread that never ran.
+  if (
+    latestRun === null &&
+    projection.thread.activeProviderThreadId === null &&
+    !backgroundWorkHoldsRun
+  ) {
+    return null;
+  }
+  const activeRunId =
+    latestMatchingRun(projection, (run) => INTERRUPTIBLE_RUN_STATUSES.has(run.status))?.id ?? null;
   return {
     status: usageLimitedRun
       ? "failed"

packages/shared/src/orchestrationV2PendingBackgroundWork.test.ts

@@ -564,6 +564,17 @@ describe("derivePendingBackgroundWork kinds", () => {
       expect(backgroundWorkHoldsCompletion(tasks)).toBe(true);
     });
 
+    it("keeps a thread that never ran waiting on its watch", () => {
+      expect(
+        derivePendingBackgroundWork({
+          latestRun: null,
+          providerThreads: [],
+          turnItems: [],
+          pullRequests,
+        }).map((task) => task.taskId),
+      ).toEqual(["pull-request-watch:github.com/acme/app#1"]);
+    });
+
     it("lists no watch while a run is active", () => {
       expect(
         derivePendingBackgroundWork({

packages/shared/src/orchestrationV2PendingBackgroundWork.ts

@@ -89,6 +89,11 @@ function backgroundWorkKindHoldsCompletion(kind: PendingBackgroundWorkTask["kind
 
 type PendingBackgroundWorkRun = Pick<OrchestrationV2Run, "id" | "ordinal" | "status">;
 
+type PendingBackgroundWorkPullRequest = Pick<
+  ThreadPullRequestLink,
+  "host" | "repository" | "number" | "url" | "source" | "watch"
+>;
+
 type PendingBackgroundWorkProviderThread = Pick<
   OrchestrationV2ProviderThread,
   "id" | "pendingBackgroundTasks"
@@ -227,11 +232,7 @@ export function derivePendingBackgroundWork(input: {
    * pass projection runs so policy cannot drift.
    */
   readonly runs?: ReadonlyArray<PendingBackgroundWorkRun>;
-  readonly pullRequests?:
-    | ReadonlyArray<
-        Pick<ThreadPullRequestLink, "host" | "repository" | "number" | "url" | "source" | "watch">
-      >
-    | undefined;
+  readonly pullRequests?: ReadonlyArray<PendingBackgroundWorkPullRequest> | undefined;
 }): ReadonlyArray<PendingBackgroundWorkTask> {
   const hasActiveRun =
     input.hasActiveRun ??
@@ -242,6 +243,10 @@ export function derivePendingBackgroundWork(input: {
   if (hasActiveRun) {
     return [];
   }
+  // A thread that never ran waits on nothing else, but a watch started on it still wakes it.
+  if (input.latestRun == null) {
+    return pullRequestWatchTasks(input.pullRequests);
+  }
   if (!isLatestRunSettledForBackgroundWait(input.latestRun)) {
     return [];
   }
@@ -276,15 +281,23 @@ export function derivePendingBackgroundWork(input: {
     byTaskId.set(taskId, pendingTaskFromTurnItem(taskId, item));
   }
 
-  for (const link of input.pullRequests ?? []) {
-    if (link.watch === undefined || link.source === "stack-dismissed") continue;
-    const taskId = `pull-request-watch:${threadPullRequestKeyOf(link)}`;
-    byTaskId.set(taskId, {
-      taskId,
-      description: `Watching pull request #${link.number}`,
-      kind: "monitor",
-    });
-  }
+  for (const task of pullRequestWatchTasks(input.pullRequests)) byTaskId.set(task.taskId, task);
 
   return Array.from(byTaskId.values());
 }
+
+function pullRequestWatchTasks(
+  pullRequests: ReadonlyArray<PendingBackgroundWorkPullRequest> | undefined,
+): Array<PendingBackgroundWorkTask> {
+  return (pullRequests ?? []).flatMap((link) =>
+    link.watch === undefined || link.source === "stack-dismissed"
+      ? []
+      : [
+          {
+            taskId: `pull-request-watch:${threadPullRequestKeyOf(link)}`,
+            description: `Watching pull request #${link.number}`,
+            kind: "monitor" as const,
+          },
+        ],
+  );
+}