fix(server): hold background liveness until a waking task resumes

apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.test.ts

@@ -4680,6 +4680,174 @@ describe("ProviderRuntimeIngestion", () => {
     expect(activity?.payload).toMatchObject({ requestId: "message-compact" });
   });
 
+  /**
+   * The parent turn can settle while a task is still live. The waking
+   * completion keeps background liveness working until the follow-up turn
+   * starts, then the hold drops.
+   */
+  async function keepsBackgroundLivenessUntilFollowUpTurnStarts() {
+    const harness = await createHarness();
+    const now = "2026-01-01T00:00:00.000Z";
+    const threadId = asThreadId("thread-1");
+    const provider = ProviderDriverKind.make("claudeAgent");
+
+    await harness.emitAndDrain([
+      {
+        type: "task.started",
+        eventId: asEventId("evt-resume-task-started"),
+        provider,
+        createdAt: now,
+        threadId,
+        payload: {
+          taskId: "subagent-1",
+          taskType: "local_agent",
+          description: "Review the diff",
+        },
+      },
+    ]);
+    expect((await harness.readThreadShell()).backgroundLiveness).toBe("working");
+
+    await harness.emitAndDrain([
+      {
+        type: "turn.completed",
+        eventId: asEventId("evt-resume-turn-completed"),
+        provider,
+        createdAt: now,
+        threadId,
+        turnId: asTurnId("turn-parent"),
+        payload: { state: "completed" },
+      },
+    ]);
+    expect((await harness.readThreadShell()).session?.status).toBe("ready");
+    expect((await harness.readThreadShell()).backgroundLiveness).toBe("working");
+
+    await harness.emitAndDrain([
+      {
+        type: "task.completed",
+        eventId: asEventId("evt-resume-task-completed"),
+        provider,
+        createdAt: now,
+        threadId,
+        payload: {
+          taskId: "subagent-1",
+          status: "completed",
+          resumesProvider: true,
+        },
+      },
+    ]);
+    const held = await harness.readThreadShell();
+    expect(held.session?.status).toBe("ready");
+    expect(held.backgroundLiveness).toBe("working");
+
+    await harness.emitAndDrain([
+      {
+        type: "turn.started",
+        eventId: asEventId("evt-resume-follow-up"),
+        provider,
+        createdAt: "2026-01-01T00:00:02.000Z",
+        threadId,
+        turnId: asTurnId("turn-follow-up"),
+      },
+    ]);
+    const resumed = await harness.readThreadShell();
+    expect(resumed.session?.status).toBe("running");
+    expect(resumed.backgroundLiveness).toBeNull();
+  }
+
+  /**
+   * A completion that does not resume the provider clears background
+   * liveness. The sidebar is not held on working.
+   */
+  async function clearsBackgroundLivenessWhenCompletionWillNotResumeProvider() {
+    const harness = await createHarness();
+    const now = "2026-01-01T00:00:00.000Z";
+    const threadId = asThreadId("thread-1");
+    const provider = ProviderDriverKind.make("claudeAgent");
+
+    await harness.emitAndDrain([
+      {
+        type: "task.started",
+        eventId: asEventId("evt-settle-task-started"),
+        provider,
+        createdAt: now,
+        threadId,
+        payload: {
+          taskId: "monitor-1",
+          taskType: "local_bash",
+          description: "Watch the checks",
+        },
+      },
+      {
+        type: "task.completed",
+        eventId: asEventId("evt-settle-task-completed"),
+        provider,
+        createdAt: now,
+        threadId,
+        payload: {
+          taskId: "monitor-1",
+          status: "completed",
+        },
+      },
+    ]);
+    expect((await harness.readThreadShell()).backgroundLiveness).toBeNull();
+  }
+
+  /**
+   * A session error drops a provider-resume hold. The shell is not pinned
+   * on working after the provider can no longer resume.
+   */
+  async function dropsProviderResumeHoldWhenSessionErrors() {
+    const harness = await createHarness();
+    const now = "2026-01-01T00:00:00.000Z";
+    const threadId = asThreadId("thread-1");
+    const provider = ProviderDriverKind.make("claudeAgent");
+
+    await harness.emitAndDrain([
+      {
+        type: "task.completed",
+        eventId: asEventId("evt-error-task-completed"),
+        provider,
+        createdAt: now,
+        threadId,
+        payload: {
+          taskId: "subagent-1",
+          status: "completed",
+          resumesProvider: true,
+        },
+      },
+    ]);
+    expect((await harness.readThreadShell()).backgroundLiveness).toBe("working");
+
+    await harness.emitAndDrain([
+      {
+        type: "session.state.changed",
+        eventId: asEventId("evt-resume-session-error"),
+        provider,
+        createdAt: now,
+        threadId,
+        payload: { state: "error", reason: "provider crashed" },
+      },
+    ]);
+    const failed = await harness.readThreadShell();
+    expect(failed.session?.status).toBe("error");
+    expect(failed.backgroundLiveness).toBeNull();
+  }
+
+  it(
+    "keeps background liveness through a provider resume until the follow-up turn starts",
+    keepsBackgroundLivenessUntilFollowUpTurnStarts,
+  );
+
+  it(
+    "clears background liveness when a completion will not resume the provider",
+    clearsBackgroundLivenessWhenCompletionWillNotResumeProvider,
+  );
+
+  it(
+    "drops a provider-resume hold when the session errors",
+    dropsProviderResumeHoldWhenSessionErrors,
+  );
+
   it("projects Codex task lifecycle chunks into thread activities", async () => {
     const harness = await createHarness();
     const now = "2026-01-01T00:00:00.000Z";

apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts

@@ -1039,6 +1039,15 @@ export function runtimeEventToActivities(
   return [];
 }
 
+/**
+ * Subscribe to provider runtime events and fold them into thread commands,
+ * activities, and in-memory background liveness.
+ *
+ * A waking task completion keeps that liveness working until the follow-up
+ * turn starts, so the shell does not read as ready in the gap.
+ *
+ * @returns The ingestion service, with `start` and `drain`.
+ */
 const make = Effect.gen(function* () {
   const threadBackgroundLiveness = yield* ThreadBackgroundLivenessService;
   const threadPlanProgress = yield* ThreadPlanProgressService;
@@ -1778,6 +1787,15 @@ const make = Effect.gen(function* () {
     },
   );
 
+  /**
+   * Fold one provider runtime event into the thread: session lifecycle,
+   * activities, and in-memory background liveness. A waking task completion
+   * keeps that liveness working until the follow-up turn starts, so the
+   * shell does not read as ready in the gap.
+   *
+   * @param event - Provider runtime event for the thread being ingested.
+   * @returns The effect that persists the event and updates liveness.
+   */
   const processRuntimeEvent = (event: ProviderRuntimeEvent) =>
     Effect.gen(function* () {
       if (
@@ -2504,6 +2522,7 @@ const make = Effect.gen(function* () {
             taskType?: string;
             status?: string;
             agentId?: string;
+            resumesProvider?: boolean;
           };
           threadBackgroundLiveness.recordTaskLiveness({
             threadId: thread.id,
@@ -2519,9 +2538,30 @@ const make = Effect.gen(function* () {
                   : event.type === "task.updated"
                     ? "updated"
                     : "completed",
+            awaitsProviderResume:
+              event.type === "task.completed" && payload.resumesProvider === true,
           });
           break;
         }
+        case "turn.started":
+          // The follow-up turn is running. Session status keeps the thread
+          // working until that turn settles, so the resume hold can drop.
+          if (shouldApplyThreadLifecycle) {
+            threadBackgroundLiveness.releaseProviderResume(thread.id);
+          }
+          break;
+        case "turn.aborted":
+          if (shouldApplyThreadLifecycle) {
+            threadBackgroundLiveness.releaseProviderResume(thread.id);
+          }
+          break;
+        case "session.state.changed":
+          // Ready is the gap itself. Release only when the session can no
+          // longer resume, so a failure is not pinned on Working.
+          if (event.payload.state === "error" || event.payload.state === "stopped") {
+            threadBackgroundLiveness.releaseProviderResume(thread.id);
+          }
+          break;
         case "session.exited":
           threadBackgroundLiveness.clearThreadLiveness(thread.id);
           break;

apps/server/src/orchestration/ThreadBackgroundLiveness.test.ts

@@ -1,6 +1,120 @@
 import { describe, expect, it } from "vite-plus/test";
 import * as ThreadBackgroundLiveness from "./ThreadBackgroundLiveness.ts";
 
+/**
+ * A waking completion stays working after the last live task drops, until
+ * `releaseProviderResume`. An earlier completion while a monitor is still
+ * live stays monitoring.
+ */
+function holdsWorkingAfterWakingCompletionUntilProviderResumes() {
+  const liveness = ThreadBackgroundLiveness.make();
+  const threadId = "thread-resume";
+  liveness.recordTaskLiveness({
+    threadId,
+    taskId: "subagent",
+    taskType: "local_agent",
+    status: undefined,
+    kind: "started",
+  });
+  liveness.recordTaskLiveness({
+    threadId,
+    taskId: "monitor",
+    taskType: "local_bash",
+    status: undefined,
+    kind: "started",
+  });
+  liveness.recordTaskLiveness({
+    threadId,
+    taskId: "subagent",
+    taskType: "local_agent",
+    status: "completed",
+    kind: "completed",
+    awaitsProviderResume: true,
+  });
+  expect(liveness.getThreadBackgroundLiveness(threadId)).toBe("monitoring");
+  liveness.recordTaskLiveness({
+    threadId,
+    taskId: "monitor",
+    taskType: "local_bash",
+    status: "completed",
+    kind: "completed",
+    awaitsProviderResume: true,
+  });
+  expect(liveness.getThreadBackgroundLiveness(threadId)).toBe("working");
+  liveness.releaseProviderResume(threadId);
+  expect(liveness.getThreadBackgroundLiveness(threadId)).toBeNull();
+}
+
+/**
+ * A terminal task update without `awaitsProviderResume` clears liveness.
+ * Ordinary completions must not keep the sidebar on working.
+ */
+function doesNotHoldCompletionThatWillNotResumeProvider() {
+  const liveness = ThreadBackgroundLiveness.make();
+  const threadId = "thread-settle";
+  liveness.recordTaskLiveness({
+    threadId,
+    taskId: "monitor",
+    taskType: "local_bash",
+    status: undefined,
+    kind: "started",
+  });
+  liveness.recordTaskLiveness({
+    threadId,
+    taskId: "monitor",
+    taskType: "local_bash",
+    status: "completed",
+    kind: "completed",
+  });
+  expect(liveness.getThreadBackgroundLiveness(threadId)).toBeNull();
+}
+
+/**
+ * Clearing a thread drops both live tasks and a resume hold, so a dead
+ * session does not stay working.
+ */
+function dropsResumeHoldWhenBackgroundWorkIsCleared() {
+  const liveness = ThreadBackgroundLiveness.make();
+  liveness.recordTaskLiveness({
+    threadId: "thread",
+    taskId: "subagent",
+    taskType: "local_agent",
+    status: "completed",
+    kind: "completed",
+    awaitsProviderResume: true,
+  });
+  expect(liveness.getThreadBackgroundLiveness("thread")).toBe("working");
+  liveness.clearThreadLiveness("thread");
+  expect(liveness.getThreadBackgroundLiveness("thread")).toBeNull();
+}
+
+/**
+ * Releasing the resume hold leaves a task that started during the handoff.
+ * The sidebar then follows that task instead of going ready.
+ */
+function releasesOnlyResumeHoldAndLeavesTaskStartedDuringHandoff() {
+  const liveness = ThreadBackgroundLiveness.make();
+  const threadId = "thread-handoff";
+  liveness.recordTaskLiveness({
+    threadId,
+    taskId: "subagent",
+    taskType: "local_agent",
+    status: "completed",
+    kind: "completed",
+    awaitsProviderResume: true,
+  });
+  liveness.recordTaskLiveness({
+    threadId,
+    taskId: "monitor",
+    taskType: "local_bash",
+    status: undefined,
+    kind: "started",
+  });
+  expect(liveness.getThreadBackgroundLiveness(threadId)).toBe("working");
+  liveness.releaseProviderResume(threadId);
+  expect(liveness.getThreadBackgroundLiveness(threadId)).toBe("monitoring");
+}
+
 describe("ThreadBackgroundLiveness", () => {
   it("does not let status-free progress or metadata restart an idle task", () => {
     const liveness = ThreadBackgroundLiveness.make();
@@ -226,4 +340,24 @@ describe("ThreadBackgroundLiveness", () => {
     a.clearThreadLiveness("t");
     expect(a.getThreadBackgroundLiveness("t")).toBeNull();
   });
+
+  it(
+    "holds working after a waking completion until the provider resumes",
+    holdsWorkingAfterWakingCompletionUntilProviderResumes,
+  );
+
+  it(
+    "does not hold a completion that will not resume the provider",
+    doesNotHoldCompletionThatWillNotResumeProvider,
+  );
+
+  it(
+    "drops a resume hold when the thread's background work is cleared",
+    dropsResumeHoldWhenBackgroundWorkIsCleared,
+  );
+
+  it(
+    "releases only the resume hold and leaves a task that started during the handoff",
+    releasesOnlyResumeHoldAndLeavesTaskStartedDuringHandoff,
+  );
 });