@hellcoder/companion 0.113.2 → 0.113.3

package/server/proc-diagnostics.test.ts

@@ -7,6 +7,7 @@ import {
   hasLiveDescendants,
   countDescendants,
   findOrphanedMcpProcesses,
+  stdoutFdOpen,
 } from "./proc-diagnostics.js";
 
 /**
@@ -287,3 +288,46 @@ describe("findOrphanedMcpProcesses", () => {
     expect(typeof found?.comm).toBe("string");
   });
 });
+
+describe("stdoutFdOpen", () => {
+  const spawned: ReturnType<typeof spawn>[] = [];
+
+  afterEach(() => {
+    for (const p of spawned.splice(0)) {
+      try { p.kill("SIGKILL"); } catch { /* already gone */ }
+    }
+  });
+
+  // This probe decides how a mid-stream stdout EOF is attributed: a pipe only
+  // EOFs at the read end when every write end has closed, so "our reader saw
+  // EOF but fd 1 is still open" proves a reader-side (server) stream failure
+  // rather than a CLI wedge. Production sampling showed every wedge-kill
+  // victim healthy — this is the field that finally distinguishes the cases.
+  it.runIf(isLinux)("returns true for a live process holding stdout open", async () => {
+    const child = spawn("sleep", ["30"], { stdio: "ignore" });
+    spawned.push(child);
+    await new Promise((r) => setTimeout(r, 100));
+    expect(stdoutFdOpen(child.pid)).toBe(true);
+  });
+
+  it.runIf(isLinux)("returns false when the process closed its own stdout", async () => {
+    // exec 1>&- closes fd 1 in the shell itself, then keeps the process alive.
+    const child = spawn("/bin/bash", ["-c", "exec 1>&-; sleep 30"], { stdio: "ignore" });
+    spawned.push(child);
+    await new Promise((r) => setTimeout(r, 300));
+    expect(stdoutFdOpen(child.pid)).toBe(false);
+  });
+
+  it.runIf(isLinux)("returns false for an exited process", async () => {
+    const child = spawn("true", [], { stdio: "ignore" });
+    spawned.push(child);
+    await new Promise((r) => setTimeout(r, 300));
+    expect(stdoutFdOpen(child.pid)).toBe(false);
+  });
+
+  it("returns null for a missing pid and never throws", () => {
+    expect(stdoutFdOpen(undefined)).toBeNull();
+    expect(stdoutFdOpen(null)).toBeNull();
+    expect(stdoutFdOpen(0)).toBeNull();
+  });
+});

package/server/proc-diagnostics.ts

@@ -8,7 +8,7 @@
 // Everything here is best-effort and must never throw: this runs on a recovery
 // path, and a diagnostic that breaks recovery is worse than no diagnostic.
 
-import { readFileSync, readdirSync } from "node:fs";
+import { readFileSync, readdirSync, readlinkSync } from "node:fs";
 
 /** A point-in-time snapshot of kernel state for a process. */
 export interface ProcSnapshot {
@@ -281,3 +281,30 @@ export function captureProcState(pid: number | undefined): ProcSnapshot {
   if (!readAnything) snapshot.error = "process_gone_or_unreadable";
   return snapshot;
 }
+
+/**
+ * Does the process still hold its stdout (fd 1) open?
+ *
+ * The discriminating probe for a mid-stream stdout EOF. A pipe only EOFs at
+ * the read end once every write end is closed — so if OUR reader reported EOF
+ * while the CLI's fd 1 is still open, the "EOF" was synthetic on the reader
+ * (Bun stream) side, not the CLI closing its output. That distinction decides
+ * whether a "wedged" kill is recovering from a real CLI failure or destroying
+ * a healthy process because of our own stream handling. Production sampling
+ * showed every wedge-kill victim was healthy (S/ep_poll), which is what
+ * motivated recording this at kill time.
+ *
+ * Returns true if fd 1 is open, false if it is definitely gone (fd closed or
+ * process exited), and null when it cannot be determined (non-Linux,
+ * permissions).
+ */
+export function stdoutFdOpen(pid: number | undefined | null): boolean | null {
+  if (!pid || process.platform !== "linux") return null;
+  try {
+    readlinkSync(`/proc/${pid}/fd/1`);
+    return true;
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException)?.code;
+    return code === "ENOENT" || code === "ESRCH" ? false : null;
+  }
+}

package/server/recorder.test.ts

@@ -350,7 +350,7 @@ describe("RecorderManager", () => {
 // ─── Cleanup / Rotation ─────────────────────────────────────────────────────
 
 describe("cleanup / rotation", () => {
-  it("deletes oldest files when total lines exceed maxLines", () => {
+  it("deletes oldest files when total lines exceed maxLines", async () => {
     // Create 3 files with 10 entries each (= 11 lines each including header, 33 total)
     // Use different mtimes so we control which is "oldest"
     const now = Date.now();
@@ -365,7 +365,7 @@ describe("cleanup / rotation", () => {
       maxLines: 20,
     });
 
-    const deleted = mgr.cleanup();
+    const deleted = await mgr.cleanup();
 
     // Should have deleted at least the oldest file (11 lines), bringing total to 22,
     // still > 20, so the mid file (11 lines) gets deleted too → total 11 lines
@@ -376,7 +376,7 @@ describe("cleanup / rotation", () => {
     expect(remaining[0]).toContain("new_claude");
   });
 
-  it("does not delete files from active recording sessions", () => {
+  it("does not delete files from active recording sessions", async () => {
     // Create an old file that would normally be deleted
     const now = Date.now();
     createFakeRecording(tempDir, "stale_claude_2025-01-01.jsonl", 10, new Date(now - 3000));
@@ -390,7 +390,7 @@ describe("cleanup / rotation", () => {
     mgr.record("active-sess", "in", "msg", "cli", "claude", "/cwd");
 
     // Now cleanup should delete the stale file but NOT the active recording's file
-    const deleted = mgr.cleanup();
+    const deleted = await mgr.cleanup();
 
     // stale file deleted
     expect(existsSync(join(tempDir, "stale_claude_2025-01-01.jsonl"))).toBe(false);
@@ -403,7 +403,7 @@ describe("cleanup / rotation", () => {
     mgr.closeAll();
   });
 
-  it("is a no-op when total lines are under the limit", () => {
+  it("is a no-op when total lines are under the limit", async () => {
     // 2 files × 3 entries = 2 × 4 lines = 8 total, well under 100
     createFakeRecording(tempDir, "a_claude_2025-01-01.jsonl", 3);
     createFakeRecording(tempDir, "b_claude_2025-01-02.jsonl", 3);
@@ -414,36 +414,38 @@ describe("cleanup / rotation", () => {
       maxLines: 100,
     });
 
-    const deleted = mgr.cleanup();
+    const deleted = await mgr.cleanup();
     expect(deleted).toBe(0);
 
     expect(readDirSafe(tempDir).length).toBe(2);
   });
 
-  it("handles empty recordings directory gracefully", () => {
+  it("handles empty recordings directory gracefully", async () => {
     const mgr = new RecorderManager({
       globalEnabled: false,
       recordingsDir: tempDir,
       maxLines: 10,
     });
 
-    const deleted = mgr.cleanup();
+    const deleted = await mgr.cleanup();
     expect(deleted).toBe(0);
   });
 
-  it("runs cleanup at construction when globally enabled", () => {
+  it("runs cleanup at construction when globally enabled", async () => {
     // Pre-fill the directory over the limit
     const now = Date.now();
     createFakeRecording(tempDir, "old_claude_2025-01-01.jsonl", 20, new Date(now - 2000));
     createFakeRecording(tempDir, "new_claude_2025-01-02.jsonl", 5, new Date(now - 1000));
 
     // Total = 21 + 6 = 27 lines, maxLines = 10
-    // Constructor should run cleanup immediately, deleting the old file
+    // Constructor should kick off cleanup immediately; it is async now, so
+    // await the coalesced in-flight pass before asserting.
     const mgr = new RecorderManager({
       globalEnabled: true,
       recordingsDir: tempDir,
       maxLines: 10,
     });
+    await mgr.cleanup();
 
     const remaining = readDirSafe(tempDir);
     expect(remaining.length).toBe(1);

package/server/recorder.ts

@@ -3,7 +3,7 @@ import { randomBytes } from "node:crypto";
 import { join } from "node:path";
 import type { BackendType } from "./session-types.js";
 import { COMPANION_HOME } from "./paths.js";
-import { countFileLines } from "./fs-utils.js";
+import { countFileLines, countFileLinesCached, cachedFileLines, type FileLinesCacheEntry } from "./fs-utils.js";
 
 const DEFAULT_MAX_LINES = 1_000_000;
 const CLEANUP_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
@@ -152,6 +152,13 @@ export class RecorderManager {
   private globalEnabled: boolean;
   private recordingsDir: string;
   private maxLines: number;
+  /** Stat-validated line-count cache: finished recordings are immutable, so
+   *  only actively-written files are ever re-read. Keeps the periodic scan of
+   *  a multi-hundred-MB recordings dir from stalling the event loop (which
+   *  starved live CLI stdio streams). */
+  private lineCountCache = new Map<string, FileLinesCacheEntry>();
+  /** Serializes cleanup passes so a slow scan cannot overlap the next tick. */
+  private cleanupInFlight: Promise<number> | null = null;
   private perSessionEnabled = new Set<string>();
   private perSessionDisabled = new Set<string>();
   private recorders = new Map<string, SessionRecorder>();
@@ -174,8 +181,8 @@ export class RecorderManager {
 
     if (this.globalEnabled) {
       // Run cleanup at startup (async, non-blocking) and periodically
-      this.cleanup();
-      this.cleanupTimer = setInterval(() => this.cleanup(), CLEANUP_INTERVAL_MS);
+      void this.cleanup();
+      this.cleanupTimer = setInterval(() => void this.cleanup(), CLEANUP_INTERVAL_MS);
       if (this.cleanupTimer.unref) this.cleanupTimer.unref();
     }
   }
@@ -279,8 +286,10 @@ export class RecorderManager {
           if (firstUnderscore === -1 || secondUnderscore === -1) {
             return { filename, sessionId: "", backendType: "", startedAt: "", lines: 0 };
           }
-          // Count lines — fast: just count newlines
-          const lines = countFileLines(join(this.recordingsDir, filename));
+          // Count lines — prefer counts warmed by the periodic async scan;
+          // fall back to a direct count for files the scan has not seen yet.
+          const fullPath = join(this.recordingsDir, filename);
+          const lines = cachedFileLines(fullPath, this.lineCountCache) ?? countFileLines(fullPath);
           return {
             filename,
             sessionId: withoutExt.substring(0, firstUnderscore),
@@ -309,7 +318,20 @@ export class RecorderManager {
    * Delete oldest recording files until total lines are under maxLines.
    * Skips files that belong to active (currently recording) sessions.
    */
-  cleanup(): number {
+  /**
+   * Async and cache-backed on purpose: the previous sync implementation
+   * re-read every byte of the recordings directory (385MB observed) on the
+   * event loop every 5 minutes. Overlapping passes are coalesced.
+   */
+  cleanup(): Promise<number> {
+    if (this.cleanupInFlight) return this.cleanupInFlight;
+    this.cleanupInFlight = this.runCleanup().finally(() => {
+      this.cleanupInFlight = null;
+    });
+    return this.cleanupInFlight;
+  }
+
+  private async runCleanup(): Promise<number> {
     try {
       this.ensureDir();
       const files = readdirSync(this.recordingsDir).filter((f) => f.endsWith(".jsonl"));
@@ -326,7 +348,7 @@ export class RecorderManager {
 
       for (const filename of files) {
         const fullPath = join(this.recordingsDir, filename);
-        const lines = countFileLines(fullPath);
+        const lines = await countFileLinesCached(fullPath, this.lineCountCache);
         let mtimeMs = 0;
         try {
           mtimeMs = statSync(fullPath).mtimeMs;
@@ -349,6 +371,7 @@ export class RecorderManager {
         if (activeFiles.has(entry.path)) continue;
         try {
           unlinkSync(entry.path);
+          this.lineCountCache.delete(entry.path);
           totalLines -= entry.lines;
           deleted++;
         } catch {

package/server/session-git-info.ts

@@ -1,4 +1,4 @@
-import { execSync } from "node:child_process";
+import { exec } from "node:child_process";
 import { resolve } from "node:path";
 import type { SessionState } from "./session-types.js";
 import { containerManager } from "./container-manager.js";
@@ -7,23 +7,38 @@ function shellEscapeSingle(value: string): string {
   return value.replace(/'/g, "'\\''");
 }
 
-function runGitCommand(sessionId: string, state: SessionState, command: string): string {
+/**
+ * Run a git (or docker-wrapped git) command asynchronously.
+ *
+ * This used to be execSync. Resolving git info runs up to four commands per
+ * session and fires for EVERY session on browser connect — a browser
+ * reconnect storm over a dozen sessions meant dozens of back-to-back
+ * synchronous subprocess calls (3s timeout each) on the event loop. Those
+ * stalls starved live CLI stdio streams mid-turn, which the wedge detector
+ * then misread as dead transports. Async keeps the loop free; the git info
+ * lands a few ms later, which nothing here is sensitive to.
+ */
+function runGitCommand(sessionId: string, state: SessionState, command: string): Promise<string> {
+  let fullCommand = command;
+  let cwd: string | undefined = state.cwd;
+
   if (state.is_containerized) {
     const container = containerManager.getContainer(sessionId);
-    if (container?.containerId) {
-      const containerCwd = container.containerCwd || "/workspace";
-      const inner = `cd '${shellEscapeSingle(containerCwd)}' && ${command}`;
-      const dockerCmd = `docker exec ${container.containerId} sh -lc ${JSON.stringify(inner)}`;
-      return execSync(dockerCmd, { encoding: "utf-8", timeout: 3000 }).trim();
+    if (!container?.containerId) {
+      return Promise.reject(new Error("container not tracked"));
     }
-    throw new Error("container not tracked");
+    const containerCwd = container.containerCwd || "/workspace";
+    const inner = `cd '${shellEscapeSingle(containerCwd)}' && ${command}`;
+    fullCommand = `docker exec ${container.containerId} sh -lc ${JSON.stringify(inner)}`;
+    cwd = undefined;
   }
 
-  return execSync(command, {
-    cwd: state.cwd,
-    encoding: "utf-8",
-    timeout: 3000,
-  }).trim();
+  return new Promise((resolvePromise, rejectPromise) => {
+    exec(fullCommand, { cwd, encoding: "utf-8", timeout: 3000 }, (error, stdout) => {
+      if (error) rejectPromise(error);
+      else resolvePromise(stdout.trim());
+    });
+  });
 }
 
 function mapContainerPathToHost(sessionId: string, state: SessionState, pathValue: string): string {
@@ -39,7 +54,7 @@ function mapContainerPathToHost(sessionId: string, state: SessionState, pathValu
   return pathValue;
 }
 
-export function resolveSessionGitInfo(sessionId: string, state: SessionState): void {
+export async function resolveSessionGitInfo(sessionId: string, state: SessionState): Promise<void> {
   if (!state.cwd) return;
   const wasContainerized = state.is_containerized;
   const previous = {
@@ -50,10 +65,10 @@ export function resolveSessionGitInfo(sessionId: string, state: SessionState): v
     git_behind: state.git_behind,
   };
   try {
-    state.git_branch = runGitCommand(sessionId, state, "git rev-parse --abbrev-ref HEAD 2>/dev/null");
+    state.git_branch = await runGitCommand(sessionId, state, "git rev-parse --abbrev-ref HEAD 2>/dev/null");
 
     try {
-      const gitDir = runGitCommand(sessionId, state, "git rev-parse --git-dir 2>/dev/null");
+      const gitDir = await runGitCommand(sessionId, state, "git rev-parse --git-dir 2>/dev/null");
       state.is_worktree = gitDir.includes("/worktrees/");
     } catch {
       state.is_worktree = false;
@@ -61,10 +76,10 @@ export function resolveSessionGitInfo(sessionId: string, state: SessionState): v
 
     try {
       if (state.is_worktree) {
-        const commonDir = runGitCommand(sessionId, state, "git rev-parse --git-common-dir 2>/dev/null");
+        const commonDir = await runGitCommand(sessionId, state, "git rev-parse --git-common-dir 2>/dev/null");
         state.repo_root = resolve(state.cwd, commonDir, "..");
       } else {
-        state.repo_root = runGitCommand(sessionId, state, "git rev-parse --show-toplevel 2>/dev/null");
+        state.repo_root = await runGitCommand(sessionId, state, "git rev-parse --show-toplevel 2>/dev/null");
       }
       state.repo_root = mapContainerPathToHost(sessionId, state, state.repo_root);
     } catch {
@@ -72,7 +87,7 @@ export function resolveSessionGitInfo(sessionId: string, state: SessionState): v
     }
 
     try {
-      const counts = runGitCommand(
+      const counts = await runGitCommand(
         sessionId,
         state,
         "git rev-list --left-right --count @{upstream}...HEAD 2>/dev/null",

package/server/ws-bridge.test.ts

@@ -17,7 +17,19 @@ if (typeof globalThis.Bun === "undefined") {
 }
 
 const mockExecSync = vi.hoisted(() => vi.fn());
-vi.mock("node:child_process", () => ({ execSync: mockExecSync }));
+// session-git-info now uses async exec (the sync version stalled the event
+// loop on browser-connect storms); delegate it to the same mockExecSync
+// fixtures so every test keeps configuring git output in one place.
+const mockExec = vi.hoisted(() => (cmd: string, opts: unknown, cb: (err: Error | null, stdout: string) => void) => {
+  process.nextTick(() => {
+    try {
+      cb(null, String(mockExecSync(cmd, opts)));
+    } catch (err) {
+      cb(err as Error, "");
+    }
+  });
+});
+vi.mock("node:child_process", () => ({ execSync: mockExecSync, exec: mockExec }));
 vi.mock("node:crypto", () => ({ randomUUID: () => "test-uuid" }));
 
 // Mock settings-manager to prevent AI validation from interfering with tests.
@@ -680,7 +692,7 @@ describe("CLI handlers", () => {
 
     const state = bridge.getSession("s1")!.state;
     expect(state.cwd).toBe("/Users/stan/Dev/myproject");
-    expect(state.git_branch).toBe("container-branch");
+    await vi.waitFor(() => expect(state.git_branch).toBe("container-branch"));
     expect(state.repo_root).toBe("/Users/stan/Dev/myproject");
     expect(state.git_behind).toBe(1);
     expect(state.git_ahead).toBe(3);
@@ -716,7 +728,7 @@ describe("CLI handlers", () => {
     await bridge.handleCLIMessage(cli, makeInitMsg({ cwd: "/workspace" }));
 
     const state = bridge.getSession("s1")!.state;
-    expect(state.repo_root).toBe("/Users/stan/Dev/myproject/packages/api");
+    await vi.waitFor(() => expect(state.repo_root).toBe("/Users/stan/Dev/myproject/packages/api"));
     expect(getContainerSpy).toHaveBeenCalledWith("s1");
     getContainerSpy.mockRestore();
   });
@@ -733,8 +745,9 @@ describe("CLI handlers", () => {
     bridge.handleCLIOpen(cli, "s1");
     await bridge.handleCLIMessage(cli, makeInitMsg());
 
+    // Git info now resolves asynchronously (off the event loop) — wait for it.
+    await vi.waitFor(() => expect(bridge.getSession("s1")!.state.git_branch).toBe("feat/test-branch"));
     const state = bridge.getSession("s1")!.state;
-    expect(state.git_branch).toBe("feat/test-branch");
     expect(state.repo_root).toBe("/repo");
     expect(state.git_ahead).toBe(5);
     expect(state.git_behind).toBe(2);
@@ -754,7 +767,7 @@ describe("CLI handlers", () => {
     await bridge.handleCLIMessage(cli, makeInitMsg({ cwd: "/home/user/myproject" }));
 
     const state = bridge.getSession("s1")!.state;
-    expect(state.repo_root).toBe("/home/user/myproject");
+    await vi.waitFor(() => expect(state.repo_root).toBe("/home/user/myproject"));
   });
 
   it("handleCLIMessage: system.status updates compacting and permissionMode", async () => {
@@ -1182,7 +1195,7 @@ describe("Browser handlers", () => {
     expect(firstMsg.session.session_id).toBe("s1");
   });
 
-  it("handleBrowserOpen: refreshes git branch before sending session snapshot", () => {
+  it("handleBrowserOpen: refreshes git branch and broadcasts the update once it lands", async () => {
     mockExecSync.mockImplementation((cmd: string) => {
       if (cmd.includes("--abbrev-ref HEAD")) return "feat/dynamic-branch\n";
       if (cmd.includes("--git-dir")) return ".git\n";
@@ -1201,9 +1214,17 @@ describe("Browser handlers", () => {
     const browser = makeBrowserSocket("s1");
     bridge.handleBrowserOpen(browser, "s1");
 
+    // The snapshot goes out immediately — git resolution no longer blocks the
+    // event loop (sync git on browser-connect storms starved CLI stdio and got
+    // healthy CLIs killed as "wedged"). The refreshed branch follows as a
+    // session_update broadcast once the async git calls land.
     const firstMsg = JSON.parse(browser.send.mock.calls[0][0]);
     expect(firstMsg.type).toBe("session_init");
-    expect(firstMsg.session.git_branch).toBe("feat/dynamic-branch");
+    await vi.waitFor(() => {
+      const calls = browser.send.mock.calls.map(([arg]: [string]) => JSON.parse(arg));
+      const update = calls.find((c: { type: string }) => c.type === "session_update");
+      expect(update?.session?.git_branch).toBe("feat/dynamic-branch");
+    });
     expect(gitInfoCb).toHaveBeenCalledWith("s1", "/repo", "feat/dynamic-branch");
   });
 
@@ -1762,9 +1783,12 @@ describe("CLI message routing", () => {
 
     await bridge.handleCLIMessage(cli, msg);
 
-    const calls = browser.send.mock.calls.map(([arg]: [string]) => JSON.parse(arg));
-    const updateMsg = calls.find((c: any) => c.type === "session_update");
-    expect(updateMsg).toBeDefined();
+    let updateMsg: any;
+    await vi.waitFor(() => {
+      const calls = browser.send.mock.calls.map(([arg]: [string]) => JSON.parse(arg));
+      updateMsg = calls.find((c: any) => c.type === "session_update");
+      expect(updateMsg).toBeDefined();
+    });
     expect(updateMsg.session.git_branch).toBe("feat/new-branch");
     expect(updateMsg.session.git_ahead).toBe(1);
     expect(bridge.getSession("s1")!.state.git_branch).toBe("feat/new-branch");

package/server/ws-bridge.ts

@@ -187,8 +187,10 @@ export class WsBridge {
         stateMachine: new SessionStateMachine(p.id, "terminated"),
       };
       session.state.backend_type = session.backendType;
-      // Resolve git info for restored sessions (may have been persisted without it)
-      resolveSessionGitInfo(session.id, session.state);
+      // Resolve git info for restored sessions (may have been persisted
+      // without it). Fire-and-forget: the info lands asynchronously and
+      // nothing in the restore path reads it synchronously.
+      void resolveSessionGitInfo(session.id, session.state);
       this.sessions.set(p.id, session);
       // Restored sessions with completed turns don't need auto-naming re-triggered
       if (session.state.num_turns > 0) {
@@ -207,10 +209,56 @@ export class WsBridge {
     persistSessionFn(session, this.store);
   }
 
+  /** In-flight git refresh bookkeeping per session: a refresh requested while
+   *  one is running is coalesced into a single re-run (options OR-merged),
+   *  because the running pass may be reading a state object that a
+   *  `system.init`/`session_update` handler has since replaced. */
+  private gitRefreshPending = new Map<string, {
+    rerun: boolean;
+    options: { broadcastUpdate?: boolean; notifyPoller?: boolean };
+  }>();
+
+  /**
+   * Fire-and-forget: git resolution now runs async subprocesses, so this
+   * returns immediately and broadcasts/persists when the info lands. A
+   * browser reconnect storm used to trigger a burst of synchronous git calls
+   * (4 per session × every session) that stalled the event loop and starved
+   * live CLI stdio streams; concurrent refreshes for the same session are
+   * coalesced instead of stacking.
+   */
   private refreshGitInfo(
     session: Session,
     options: { broadcastUpdate?: boolean; notifyPoller?: boolean } = {},
   ): void {
+    const pending = this.gitRefreshPending.get(session.id);
+    if (pending) {
+      pending.rerun = true;
+      pending.options = {
+        broadcastUpdate: pending.options.broadcastUpdate || options.broadcastUpdate,
+        notifyPoller: pending.options.notifyPoller || options.notifyPoller,
+      };
+      return;
+    }
+    const entry = { rerun: false, options: { ...options } };
+    this.gitRefreshPending.set(session.id, entry);
+    void (async () => {
+      try {
+        do {
+          entry.rerun = false;
+          // Reads session.state fresh on every pass, so a re-run picks up a
+          // state object swapped in while the previous pass was mid-flight.
+          await this.doRefreshGitInfo(session, entry.options);
+        } while (entry.rerun);
+      } finally {
+        this.gitRefreshPending.delete(session.id);
+      }
+    })();
+  }
+
+  private async doRefreshGitInfo(
+    session: Session,
+    options: { broadcastUpdate?: boolean; notifyPoller?: boolean } = {},
+  ): Promise<void> {
     const before = {
       git_branch: session.state.git_branch,
       is_worktree: session.state.is_worktree,
@@ -220,7 +268,7 @@ export class WsBridge {
       git_behind: session.state.git_behind,
     };
 
-    resolveSessionGitInfo(session.id, session.state);
+    await resolveSessionGitInfo(session.id, session.state);
 
     let changed = false;
     for (const key of WsBridge.GIT_SESSION_KEYS) {
@@ -449,7 +497,10 @@ export class WsBridge {
         // treated as an auth failure and denied keepalive relaunch. authBlocked
         // is re-set the moment another auth-error result arrives.
         session.authBlocked = false;
-        this.refreshGitInfo(session, { notifyPoller: true });
+        // broadcastUpdate: the refresh is async now, so fresh git info can no
+        // longer ride along in the snapshot broadcast below — it follows as a
+        // session_update once the git calls land (only when something changed).
+        this.refreshGitInfo(session, { broadcastUpdate: true, notifyPoller: true });
         this.broadcastToBrowsers(session, { type: "session_init", session: session.state });
         session.stateMachine.transition("ready", "system_init");
         this.persistSession(session);
@@ -467,7 +518,10 @@ export class WsBridge {
           ...(skills?.length ? { skills } : {}),
           backend_type: session.backendType,
         };
-        this.refreshGitInfo(session, { notifyPoller: true });
+        // broadcastUpdate: the refresh is async now, so fresh git info can no
+        // longer ride along in the snapshot broadcast below — it follows as a
+        // session_update once the git calls land (only when something changed).
+        this.refreshGitInfo(session, { broadcastUpdate: true, notifyPoller: true });
         this.persistSession(session);
         if (session.pendingMessages.length > 0 && adapter.isConnected()) {
           this.flushQueuedBrowserMessages(session, adapter, "backend_session_update");
@@ -1002,7 +1056,10 @@ export class WsBridge {
     this.stopIdleKillWatchdog(sessionId);
 
     // Refresh git state on browser connect so branch changes made mid-session are reflected.
-    this.refreshGitInfo(session, { notifyPoller: true });
+    // broadcastUpdate: the refresh is async now, so fresh git info can no
+        // longer ride along in the snapshot broadcast below — it follows as a
+        // session_update once the git calls land (only when something changed).
+        this.refreshGitInfo(session, { broadcastUpdate: true, notifyPoller: true });
 
     // Send current session state as snapshot
     const snapshot: BrowserIncomingMessage = {