fix: reset web-chat worktree status from owned claude -p run (#273)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: centdix

backend/src/__tests__/claude-conversation-stream-service.test.ts

@@ -292,4 +292,63 @@ describe("ClaudeConversationStreamService", () => {
       activeTurnId: null,
     });
   });
+
+  it("invokes onRunSettled exactly once when a run completes", () => {
+    const claude = new FakeClaudeCliGateway();
+    const service = new ClaudeConversationStreamService({ claude });
+    let settled = 0;
+
+    expect(service.startRun({
+      conversationId: "session-1",
+      turnId: "claude-turn:turn-1",
+      cwd: "/tmp/worktree",
+      prompt: "Ship it",
+      sessionId: "session-1",
+      onRunSettled: () => {
+        settled += 1;
+      },
+    })).toEqual({ ok: true });
+    expect(settled).toBe(0);
+
+    claude.callbacks?.onComplete?.("session-1");
+    expect(settled).toBe(1);
+
+    // A late/duplicate completion signal must not re-fire the callback.
+    claude.callbacks?.onComplete?.("session-1");
+    expect(settled).toBe(1);
+  });
+
+  it("invokes onRunSettled when a run errors or is interrupted", () => {
+    const erroring = new FakeClaudeCliGateway();
+    const errorService = new ClaudeConversationStreamService({ claude: erroring });
+    let erroredSettled = 0;
+    errorService.startRun({
+      conversationId: "session-1",
+      turnId: "claude-turn:turn-1",
+      cwd: "/tmp/worktree",
+      prompt: "Ship it",
+      sessionId: "session-1",
+      onRunSettled: () => {
+        erroredSettled += 1;
+      },
+    });
+    erroring.callbacks?.onError?.("boom");
+    expect(erroredSettled).toBe(1);
+
+    const interrupting = new FakeClaudeCliGateway();
+    const interruptService = new ClaudeConversationStreamService({ claude: interrupting });
+    let interruptedSettled = 0;
+    interruptService.startRun({
+      conversationId: "session-2",
+      turnId: "claude-turn:turn-2",
+      cwd: "/tmp/worktree",
+      prompt: "Ship it",
+      resumeSessionId: "session-2",
+      onRunSettled: () => {
+        interruptedSettled += 1;
+      },
+    });
+    interruptService.interrupt("session-2");
+    expect(interruptedSettled).toBe(1);
+  });
 });

backend/src/__tests__/claude-streaming-lifecycle.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from "bun:test";
+import type {
+  ClaudeCliGateway,
+  ClaudeCliRunCallbacks,
+  ClaudeCliRunHandle,
+} from "../adapters/claude-cli";
+import { ClaudeConversationStreamService } from "../services/claude-conversation-stream-service";
+import { ProjectRuntime } from "../services/project-runtime";
+
+class FakeClaudeCliGateway implements Pick<ClaudeCliGateway, "sendMessage"> {
+  callbacks: ClaudeCliRunCallbacks | null = null;
+
+  sendMessage(
+    params: Parameters<ClaudeCliGateway["sendMessage"]>[0],
+    callbacks: ClaudeCliRunCallbacks,
+  ): ClaudeCliRunHandle {
+    this.callbacks = callbacks;
+    return {
+      completion: Promise.resolve(),
+      interrupt: () => {},
+      sessionId: Promise.resolve(params.sessionId ?? params.resumeSessionId ?? "session-1"),
+    };
+  }
+}
+
+// Mirrors the server's busy gate (isBusyAgentStatus): a worktree is "busy" for
+// web chat only while its agent lifecycle is starting/running.
+const isBusy = (lifecycle: string): boolean => lifecycle === "starting" || lifecycle === "running";
+
+describe("Claude web-chat streaming lifecycle", () => {
+  it("marks the worktree finished when a streamed claude -p turn ends so the next web message is allowed", () => {
+    const runtime = new ProjectRuntime();
+    runtime.upsertWorktree({ worktreeId: "wt-1", branch: "feat", path: "/tmp/wt" });
+    const claude = new FakeClaudeCliGateway();
+    const stream = new ClaudeConversationStreamService({ claude });
+
+    // The same wiring the server uses in sendClaudeStreamingMessage: drive the
+    // worktree lifecycle from the owned claude -p run instead of the lossy hook.
+    const setLifecycle = (lifecycle: "running" | "stopped"): void => {
+      runtime.applyEvent({ type: "agent_status_changed", worktreeId: "wt-1", branch: "feat", lifecycle });
+    };
+    const status = (): string => runtime.getWorktree("wt-1")!.agent.lifecycle;
+
+    // Web message #1: server starts the owned claude -p run and marks it running.
+    expect(stream.startRun({
+      conversationId: "session-1",
+      turnId: "claude-turn:turn-1",
+      cwd: "/tmp/wt",
+      prompt: "first",
+      sessionId: "session-1",
+      onRunSettled: () => setLifecycle("stopped"),
+    })).toEqual({ ok: true });
+    setLifecycle("running");
+
+    // While streaming, the worktree reads as busy — a 2nd web message is gated.
+    expect(isBusy(status())).toBe(true);
+
+    // The claude -p turn ends (stream result line) — the owned end-turn signal.
+    claude.callbacks?.onComplete?.("session-1");
+
+    // Lands on the finished state (maps to "done" in the UI, same as a terminal
+    // turn finishing) so the next web message passes the busy gate.
+    expect(status()).toBe("stopped");
+    expect(isBusy(status())).toBe(false);
+  });
+});

backend/src/server.ts

@@ -706,6 +706,22 @@ async function setAgentTerminalStale(worktree: WorktreeSnapshot, stale: boolean)
   }
 }
 
+/** Drive the worktree agent lifecycle from the backend-owned `claude -p` web
+ *  chat run. The hook-based lifecycle (UserPromptSubmit/Stop) is best-effort and
+ *  can be lost or reordered, leaving the worktree stuck "running" so the busy
+ *  gate blocks the next web message even though nothing is running. The owned
+ *  run's start/settle is authoritative, so we set it directly. */
+function setWorktreeAgentLifecycle(worktree: WorktreeSnapshot, lifecycle: "running" | "stopped"): void {
+  const state = projectRuntime.getWorktreeByBranch(worktree.branch);
+  if (!state) return;
+  projectRuntime.applyEvent({
+    type: "agent_status_changed",
+    worktreeId: state.worktreeId,
+    branch: state.branch,
+    lifecycle,
+  });
+}
+
 async function resolveClaudeStreamingLaunchContext(
   worktree: WorktreeSnapshot,
 ): Promise<{
@@ -778,11 +794,13 @@ async function sendClaudeStreamingMessage(input: {
     permissionMode: launchContext.data.permissionMode,
     ...(hasExistingSession ? { resumeSessionId: sessionId } : { sessionId }),
     ...(!hasExistingSession && launchContext.data.systemPrompt ? { systemPrompt: launchContext.data.systemPrompt } : {}),
+    onRunSettled: () => setWorktreeAgentLifecycle(input.worktree, "stopped"),
   });
   if (!started.ok) {
     return errorResponse(started.error, 409);
   }
 
+  setWorktreeAgentLifecycle(input.worktree, "running");
   await setAgentTerminalStale(input.worktree, true);
   return jsonResponse({
     conversationId: sessionId,

backend/src/services/claude-conversation-stream-service.ts

@@ -20,6 +20,10 @@ export interface ClaudeConversationStreamRunInput {
   resumeSessionId?: string | null;
   sessionId?: string | null;
   systemPrompt?: string | null;
+  /** Fired exactly once when the owned `claude -p` run settles (completes,
+   *  errors, or is interrupted). The server uses this reliable end-of-turn
+   *  signal to reset the worktree lifecycle, instead of the lossy Stop hook. */
+  onRunSettled?: () => void;
 }
 
 interface ActiveClaudeRun {
@@ -29,6 +33,7 @@ interface ActiveClaudeRun {
   liveMessages: Map<string, AgentsUiConversationMessageDraft>;
   completed: boolean;
   pruneTimer: ReturnType<typeof setTimeout> | null;
+  onRunSettled: (() => void) | null;
 }
 
 export interface ClaudeConversationStreamServiceDependencies {
@@ -72,6 +77,7 @@ export class ClaudeConversationStreamService {
       liveMessages: new Map(),
       completed: false,
       pruneTimer: null,
+      onRunSettled: input.onRunSettled ?? null,
     };
     this.runs.set(input.conversationId, run);
 
@@ -250,6 +256,7 @@ export class ClaudeConversationStreamService {
     }
 
     this.notifyStatus(run, false);
+    run.onRunSettled?.();
 
     run.pruneTimer = setTimeout(() => {
       const current = this.runs.get(run.conversationId);