fix(ui): refresh worktrees from OpenCode ready events (NeuralNomadsAI#583)

## Problem

Worktrees created through OpenCode can leave CodeNomad's cached worktree
inventory and workspace mapping stale. The previous approach in NeuralNomadsAI#516
polled on `session.idle` and attempted to infer which session created a
newly observed worktree, which introduced race conditions and unsafe
attribution.

## Fix

- route OpenCode's `worktree.ready` event through the existing UI SSE
manager;
- reload the live Git worktree inventory when that event arrives;
- synchronize OpenCode workspace mappings only after the refreshed
inventory is available;
- avoid idle polling and avoid auto-switching a session because the
event identifies the new worktree directory but does not identify an
originating session.

The server bridge already forwards arbitrary OpenCode events and
preserves the global event `directory`, so no server change is required.

Supersedes NeuralNomadsAI#516 and implements the SSE approach suggested by @shantur
NeuralNomadsAI#516 (comment).

## Validation

- `bun test --conditions browser packages/ui/src` (`126` passing)
- `npm run typecheck --workspace @codenomad/ui`
- `git diff --check`

Author: pascalandr

packages/ui/src/lib/sse-manager.ts

@@ -73,6 +73,15 @@ interface ServerInstanceDisposedEvent {
   }
 }
 
+export interface WorktreeReadyEvent {
+  type: "worktree.ready"
+  directory?: string
+  properties: {
+    name: string
+    branch?: string
+  }
+}
+
 type EventSessionCreated = Omit<EventSessionUpdated, "type"> & { type: "session.created" }
 export interface EventSessionDeleted {
   type: "session.deleted"
@@ -110,6 +119,7 @@ type SSEEvent =
   | BackgroundProcessUpdatedEvent
   | BackgroundProcessRemovedEvent
   | ServerInstanceDisposedEvent
+  | WorktreeReadyEvent
   | { type: string; properties?: Record<string, unknown> }
 
 const [connectionStatus, setConnectionStatus] = createSignal<Map<string, ConnectionStatus>>(new Map())
@@ -238,6 +248,16 @@ class SSEManager {
       case "server.instance.disposed":
         this.onInstanceDisposed?.(instanceId, event as ServerInstanceDisposedEvent)
         break
+      case "worktree.ready":
+        try {
+          const result = this.onWorktreeReady?.(instanceId, event as WorktreeReadyEvent)
+          void result?.catch((error) => {
+            log.warn("Failed to handle worktree ready event", { instanceId, error })
+          })
+        } catch (error) {
+          log.warn("Failed to handle worktree ready event", { instanceId, error })
+        }
+        break
       default:
         log.warn("Unknown SSE event type", { type: event.type })
     }
@@ -271,6 +291,7 @@ class SSEManager {
   onBackgroundProcessUpdated?: (instanceId: string, event: BackgroundProcessUpdatedEvent) => void
   onBackgroundProcessRemoved?: (instanceId: string, event: BackgroundProcessRemovedEvent) => void
   onInstanceDisposed?: (instanceId: string, event: ServerInstanceDisposedEvent) => void
+  onWorktreeReady?: (instanceId: string, event: WorktreeReadyEvent) => void | Promise<void>
   onConnectionLost?: (instanceId: string, reason: string) => void | Promise<void>
 
   getStatus(instanceId: string): ConnectionStatus | null {

packages/ui/src/stores/opencode-workspaces.ts

@@ -80,15 +80,17 @@ async function syncOpenCodeWorkspaces(instanceId: string): Promise<void> {
       }
     })
     .finally(() => {
-      workspaceSyncs.delete(instanceId)
+      if (workspaceSyncs.get(instanceId) === task) {
+        workspaceSyncs.delete(instanceId)
+      }
     })
 
   workspaceSyncs.set(instanceId, task)
   return task
 }
 
 async function reloadOpenCodeWorkspaces(instanceId: string): Promise<void> {
-  workspaceSyncs.delete(instanceId)
+  await workspaceSyncs.get(instanceId)
   await syncOpenCodeWorkspaces(instanceId)
 }
 

packages/ui/src/stores/sessions.ts

@@ -65,6 +65,7 @@ import {
 } from "./session-state"
 
 import { getDefaultModel } from "./session-models"
+import { handleWorktreeReady } from "./worktrees"
 import {
   createSession,
   deleteSession,
@@ -119,6 +120,7 @@ sseManager.onPermissionUpdated = handlePermissionUpdated
 sseManager.onPermissionReplied = handlePermissionReplied
 sseManager.onQuestionAsked = handleQuestionAsked
 sseManager.onQuestionAnswered = handleQuestionAnswered
+sseManager.onWorktreeReady = handleWorktreeReady
 
 export {
   abortSession,

packages/ui/src/stores/worktree-ready.test.ts

@@ -0,0 +1,145 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+
+import { serverApi } from "../lib/api-client.ts"
+import { ensureWorktreesLoaded, getWorktrees, handleWorktreeReady, reloadWorktrees } from "./worktrees.ts"
+
+describe("handleWorktreeReady", () => {
+  it("refreshes worktrees before synchronizing OpenCode workspaces", async () => {
+    const calls: string[] = []
+
+    await handleWorktreeReady(
+      "instance-1",
+      {
+        type: "worktree.ready",
+        directory: "/tmp/opencode/worktree/feature",
+        properties: { name: "feature", branch: "opencode/feature" },
+      },
+      async (instanceId) => {
+        calls.push(`worktrees:${instanceId}`)
+      },
+      async (instanceId) => {
+        calls.push(`workspaces:${instanceId}`)
+      },
+    )
+
+    assert.deepEqual(calls, ["worktrees:instance-1", "workspaces:instance-1"])
+  })
+
+  it("serializes overlapping ready events for the same instance", async () => {
+    const calls: string[] = []
+    let releaseFirst!: () => void
+    const firstPending = new Promise<void>((resolve) => {
+      releaseFirst = resolve
+    })
+    let refreshCount = 0
+
+    const refreshWorktrees = async () => {
+      refreshCount += 1
+      calls.push(`worktrees:${refreshCount}`)
+      if (refreshCount === 1) await firstPending
+    }
+    const refreshWorkspaces = async () => {
+      calls.push(`workspaces:${refreshCount}`)
+    }
+    const event = {
+      type: "worktree.ready" as const,
+      directory: "/tmp/opencode/worktree/feature",
+      properties: { name: "feature" },
+    }
+
+    const first = handleWorktreeReady("instance-concurrent", event, refreshWorktrees, refreshWorkspaces)
+    await Promise.resolve()
+    const second = handleWorktreeReady("instance-concurrent", event, refreshWorktrees, refreshWorkspaces)
+    await Promise.resolve()
+
+    assert.deepEqual(calls, ["worktrees:1"])
+
+    releaseFirst()
+    await Promise.all([first, second])
+
+    assert.deepEqual(calls, ["worktrees:1", "workspaces:1", "worktrees:2", "workspaces:2"])
+  })
+
+  it("continues processing after an earlier refresh rejects", async () => {
+    const event = {
+      type: "worktree.ready" as const,
+      properties: { name: "feature" },
+    }
+
+    await assert.rejects(
+      handleWorktreeReady(
+        "instance-recovery",
+        event,
+        async () => {
+          throw new Error("refresh failed")
+        },
+        async () => undefined,
+      ),
+      /refresh failed/,
+    )
+
+    const calls: string[] = []
+    await handleWorktreeReady(
+      "instance-recovery",
+      event,
+      async () => {
+        calls.push("worktrees")
+      },
+      async () => {
+        calls.push("workspaces")
+      },
+    )
+
+    assert.deepEqual(calls, ["worktrees", "workspaces"])
+  })
+
+  it("orders initial hydration before a trailing reload", async () => {
+    const instanceId = "instance-initial-reload"
+    const originalFetchWorktrees = serverApi.fetchWorktrees
+    let resolveInitial!: (value: Awaited<ReturnType<typeof serverApi.fetchWorktrees>>) => void
+    let resolveReload!: (value: Awaited<ReturnType<typeof serverApi.fetchWorktrees>>) => void
+    const initialResponse = new Promise<Awaited<ReturnType<typeof serverApi.fetchWorktrees>>>((resolve) => {
+      resolveInitial = resolve
+    })
+    const reloadResponse = new Promise<Awaited<ReturnType<typeof serverApi.fetchWorktrees>>>((resolve) => {
+      resolveReload = resolve
+    })
+    let requestCount = 0
+
+    serverApi.fetchWorktrees = async () => {
+      requestCount += 1
+      return requestCount === 1 ? initialResponse : reloadResponse
+    }
+
+    try {
+      const initial = ensureWorktreesLoaded(instanceId)
+      const reload = reloadWorktrees(instanceId)
+      await Promise.resolve()
+
+      assert.equal(requestCount, 1)
+
+      resolveInitial({
+        isGitRepo: true,
+        worktrees: [{ slug: "root", directory: "/repo", kind: "root" }],
+      })
+      await initial
+      await Promise.resolve()
+
+      assert.equal(requestCount, 2)
+
+      resolveReload({
+        isGitRepo: true,
+        worktrees: [
+          { slug: "root", directory: "/repo", kind: "root" },
+          { slug: "feature", directory: "/repo-feature", kind: "worktree" },
+        ],
+      })
+      await reload
+
+      assert.deepEqual(getWorktrees(instanceId).map((worktree) => worktree.slug), ["root", "feature"])
+    } finally {
+      serverApi.fetchWorktrees = originalFetchWorktrees
+    }
+  })
+})

packages/ui/src/stores/worktrees.ts

@@ -5,17 +5,21 @@ import { getSessionRoot, sessions } from "./session-state"
 import { getLogger } from "../lib/logger"
 import { getCodeNomadSessionMetadata, setSessionWorktreeSlugWithClient } from "./session-metadata"
 import { getRootClient } from "./opencode-client"
+import type { WorktreeReadyEvent } from "../lib/sse-manager"
 
 const log = getLogger("api")
 
 const [worktreesByInstance, setWorktreesByInstance] = createSignal<Map<string, WorktreeDescriptor[]>>(new Map())
 const [worktreeMapByInstance, setWorktreeMapByInstance] = createSignal<Map<string, WorktreeMap>>(new Map())
 const [gitRepoStatusByInstance, setGitRepoStatusByInstance] = createSignal<Map<string, boolean | null>>(new Map())
 
-const worktreeLoads = new Map<string, Promise<void>>()
+const worktreeRequests = new Map<string, Promise<void>>()
+const worktreeReadyRefreshes = new Map<string, Promise<void>>()
 const mapLoads = new Map<string, Promise<void>>()
 const mapMigrations = new Map<string, Promise<void>>()
 
+type WorktreeReadyRefresh = (instanceId: string) => Promise<void>
+
 function normalizeMap(input?: WorktreeMap | null): WorktreeMap {
   if (!input || typeof input !== "object") {
     return { version: 1, defaultWorktreeSlug: "root", parentSessionWorktreeSlug: {} }
@@ -27,15 +31,11 @@ function normalizeMap(input?: WorktreeMap | null): WorktreeMap {
   }
 }
 
-async function ensureWorktreesLoaded(instanceId: string): Promise<void> {
-  if (!instanceId) return
-  if (worktreesByInstance().has(instanceId) && gitRepoStatusByInstance().has(instanceId)) return
-  const existing = worktreeLoads.get(instanceId)
-  if (existing) return existing
-
-  const task = serverApi
-    .fetchWorktrees(instanceId)
-    .then((response) => {
+async function queueWorktreeRequest(instanceId: string, initial: boolean): Promise<void> {
+  const previous = worktreeRequests.get(instanceId)
+  const task = (previous?.catch(() => undefined) ?? Promise.resolve()).then(async () => {
+    try {
+      const response = await serverApi.fetchWorktrees(instanceId)
       setWorktreesByInstance((prev) => {
         const next = new Map(prev)
         next.set(instanceId, response.worktrees ?? [])
@@ -52,9 +52,10 @@ async function ensureWorktreesLoaded(instanceId: string): Promise<void> {
       if (worktreeMapByInstance().has(instanceId)) {
         void pruneWorktreeMap(instanceId).catch(() => undefined)
       }
-    })
-    .catch((error) => {
-      log.warn("Failed to load worktrees", { instanceId, error })
+    } catch (error) {
+      log.warn(initial ? "Failed to load worktrees" : "Failed to reload worktrees", { instanceId, error })
+      if (!initial) return
+
       setWorktreesByInstance((prev) => {
         const next = new Map(prev)
         next.set(instanceId, [])
@@ -68,39 +69,64 @@ async function ensureWorktreesLoaded(instanceId: string): Promise<void> {
         next.set(instanceId, null)
         return next
       })
-    })
-    .finally(() => {
-      worktreeLoads.delete(instanceId)
-    })
+    }
+  })
 
-  worktreeLoads.set(instanceId, task)
-  return task
+  worktreeRequests.set(instanceId, task)
+  await task.finally(() => {
+    if (worktreeRequests.get(instanceId) === task) {
+      worktreeRequests.delete(instanceId)
+    }
+  })
+}
+
+async function ensureWorktreesLoaded(instanceId: string): Promise<void> {
+  if (!instanceId) return
+  if (worktreesByInstance().has(instanceId) && gitRepoStatusByInstance().has(instanceId)) return
+
+  const existing = worktreeRequests.get(instanceId)
+  if (existing) {
+    await existing
+    if (worktreesByInstance().has(instanceId) && gitRepoStatusByInstance().has(instanceId)) return
+  }
+
+  await queueWorktreeRequest(instanceId, true)
 }
 
 async function reloadWorktrees(instanceId: string): Promise<void> {
   if (!instanceId) return
-  await serverApi
-    .fetchWorktrees(instanceId)
-    .then((response) => {
-      setWorktreesByInstance((prev) => {
-        const next = new Map(prev)
-        next.set(instanceId, response.worktrees ?? [])
-        return next
-      })
+  await queueWorktreeRequest(instanceId, false)
+}
 
-      setGitRepoStatusByInstance((prev) => {
-        const next = new Map(prev)
-        next.set(instanceId, typeof response.isGitRepo === "boolean" ? response.isGitRepo : null)
-        return next
-      })
+async function handleWorktreeReady(
+  instanceId: string,
+  event: WorktreeReadyEvent,
+  refreshWorktrees: WorktreeReadyRefresh = reloadWorktrees,
+  refreshWorkspaces: WorktreeReadyRefresh = async (id) => {
+    const { reloadOpenCodeWorkspaces } = await import("./opencode-workspaces")
+    await reloadOpenCodeWorkspaces(id)
+  },
+): Promise<void> {
+  if (!instanceId) return
 
-      if (worktreeMapByInstance().has(instanceId)) {
-        void pruneWorktreeMap(instanceId).catch(() => undefined)
-      }
-    })
-    .catch((error) => {
-      log.warn("Failed to reload worktrees", { instanceId, error })
-    })
+  log.info("OpenCode worktree ready", {
+    instanceId,
+    directory: event.directory,
+    name: event.properties?.name,
+  })
+
+  const previous = worktreeReadyRefreshes.get(instanceId)
+  const task = (previous?.catch(() => undefined) ?? Promise.resolve()).then(async () => {
+    await refreshWorktrees(instanceId)
+    await refreshWorkspaces(instanceId)
+  })
+
+  worktreeReadyRefreshes.set(instanceId, task)
+  await task.finally(() => {
+    if (worktreeReadyRefreshes.get(instanceId) === task) {
+      worktreeReadyRefreshes.delete(instanceId)
+    }
+  })
 }
 
 function getGitRepoStatus(instanceId: string): boolean | null {
@@ -401,6 +427,7 @@ export {
   gitRepoStatusByInstance,
   ensureWorktreesLoaded,
   reloadWorktrees,
+  handleWorktreeReady,
   reloadWorktreeMap,
   ensureWorktreeMapLoaded,
   getGitRepoStatus,