fix: broadcast newly-discovered orphan sessions to UI (v0.2.50) (#136)

Fixes #135.

## Problem

New orphan rows were inserted into `agent_sessions` but never broadcast
— the UI's history list stayed empty until some unrelated event happened
to trigger `updateDormantAgentSessions()`.

## Fix

Add an `onSessionsDiscovered` callback fired at the end of `pollOnce`
when `orphans > 0`, wired to `updateDormantAgentSessions()` next to the
existing `onSessionActivated` / `onSessionOrphaned` callbacks.

## Tests

Two new `logPoller.test.ts` cases:
- callback fires for new-orphan discovery
- callback does not fire when every new log matches a window

22/22 logPoller tests pass; lint and typecheck clean.

---------

Co-authored-by: Gary Basin <gary@pineapple.mortgage>

Author: anish749

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gbasin/agentboard",
-  "version": "0.2.49",
+  "version": "0.2.50",
   "type": "module",
   "description": "Web GUI for tmux optimized for AI agent TUIs",
   "author": "gbasin",

src/server/__tests__/logPoller.test.ts

@@ -874,6 +874,143 @@ describe('LogPoller', () => {
     db.close()
   })
 
+  test('fires onOrphanSessionsDiscovered when a new session is discovered as orphan', async () => {
+    const db = initDatabase({ path: ':memory:' })
+    const registry = new SessionRegistry()
+    // Empty registry: no tmux windows to match against, so any new log
+    // becomes an orphan on first discovery.
+    registry.replaceSessions([])
+
+    const orphanProjectPath = path.join(tempRoot, 'orphan-project')
+    const encoded = encodeProjectPath(orphanProjectPath)
+    const logDir = path.join(
+      process.env.CLAUDE_CONFIG_DIR ?? '',
+      'projects',
+      encoded
+    )
+    await fs.mkdir(logDir, { recursive: true })
+
+    const tokens = Array.from({ length: 60 }, (_, i) => `token${i}`).join(' ')
+    const logPath = path.join(logDir, 'orphan-session.jsonl')
+    const userLine = buildUserLogEntry(tokens, {
+      sessionId: 'claude-orphan-session',
+      cwd: orphanProjectPath,
+    })
+    const assistantLine = JSON.stringify({
+      type: 'assistant',
+      message: { content: [{ type: 'text', text: tokens }] },
+    })
+    await fs.writeFile(logPath, `${userLine}\n${assistantLine}\n`)
+
+    const discovered: Array<{ newOrphans: number }> = []
+    const poller = new LogPoller(db, registry, {
+      matchWorkerClient: new InlineMatchWorkerClient(),
+      onOrphanSessionsDiscovered: (stats) => discovered.push(stats),
+    })
+
+    const stats = await poller.pollOnce()
+    expect(stats.newSessions).toBe(1)
+    expect(stats.orphans).toBe(1)
+    expect(stats.matches).toBe(0)
+
+    // The DB row should exist as an orphan.
+    const record = db.getSessionById('claude-orphan-session')
+    expect(record).toBeDefined()
+    expect(record?.currentWindow).toBeNull()
+
+    // Callback must fire exactly once with the orphan count, so the server
+    // can broadcast the new history entries over the WebSocket.
+    expect(discovered).toEqual([{ newOrphans: 1 }])
+
+    db.close()
+  })
+
+  test('fires onOrphanSessionsDiscovered from pollChanged (watch-mode path)', async () => {
+    // Watch mode is the default deployment, and new log files reach the
+    // poller through pollChanged() rather than pollOnce(). The broadcast
+    // must fire on both code paths.
+    const db = initDatabase({ path: ':memory:' })
+    const registry = new SessionRegistry()
+    registry.replaceSessions([])
+
+    const orphanProjectPath = path.join(tempRoot, 'orphan-project-watch')
+    const encoded = encodeProjectPath(orphanProjectPath)
+    const logDir = path.join(
+      process.env.CLAUDE_CONFIG_DIR ?? '',
+      'projects',
+      encoded
+    )
+    await fs.mkdir(logDir, { recursive: true })
+
+    const tokens = Array.from({ length: 60 }, (_, i) => `token${i}`).join(' ')
+    const logPath = path.join(logDir, 'orphan-watch.jsonl')
+    const userLine = buildUserLogEntry(tokens, {
+      sessionId: 'claude-orphan-watch',
+      cwd: orphanProjectPath,
+    })
+    const assistantLine = JSON.stringify({
+      type: 'assistant',
+      message: { content: [{ type: 'text', text: tokens }] },
+    })
+    await fs.writeFile(logPath, `${userLine}\n${assistantLine}\n`)
+
+    const discovered: Array<{ newOrphans: number }> = []
+    const poller = new LogPoller(db, registry, {
+      matchWorkerClient: new InlineMatchWorkerClient(),
+      onOrphanSessionsDiscovered: (stats) => discovered.push(stats),
+    })
+
+    await poller.pollChanged([logPath])
+
+    const record = db.getSessionById('claude-orphan-watch')
+    expect(record).toBeDefined()
+    expect(record?.currentWindow).toBeNull()
+    expect(discovered).toEqual([{ newOrphans: 1 }])
+
+    db.close()
+  })
+
+  test('does not fire onOrphanSessionsDiscovered when no new orphans are created', async () => {
+    const db = initDatabase({ path: ':memory:' })
+    const registry = new SessionRegistry()
+    registry.replaceSessions([baseSession])
+
+    const tokens = Array.from({ length: 60 }, (_, i) => `token${i}`).join(' ')
+    setTmuxOutput(baseSession.tmuxWindow, buildLastExchangeOutput(tokens))
+
+    const projectPath = baseSession.projectPath
+    const encoded = encodeProjectPath(projectPath)
+    const logDir = path.join(
+      process.env.CLAUDE_CONFIG_DIR ?? '',
+      'projects',
+      encoded
+    )
+    await fs.mkdir(logDir, { recursive: true })
+    const logPath = path.join(logDir, 'matched-session.jsonl')
+    const userLine = buildUserLogEntry(tokens, {
+      sessionId: 'claude-matched-session',
+      cwd: projectPath,
+    })
+    const assistantLine = JSON.stringify({
+      type: 'assistant',
+      message: { content: [{ type: 'text', text: tokens }] },
+    })
+    await fs.writeFile(logPath, `${userLine}\n${assistantLine}\n`)
+
+    const discovered: Array<{ newOrphans: number }> = []
+    const poller = new LogPoller(db, registry, {
+      matchWorkerClient: new InlineMatchWorkerClient(),
+      onOrphanSessionsDiscovered: (stats) => discovered.push(stats),
+    })
+
+    const stats = await poller.pollOnce()
+    expect(stats.newSessions).toBe(1)
+    expect(stats.orphans).toBe(0)
+    expect(discovered).toEqual([])
+
+    db.close()
+  })
+
   test('fires onSessionOrphaned callback when superseding via slug', async () => {
     const db = initDatabase({ path: ':memory:' })
     const registry = new SessionRegistry()

src/server/index.ts

@@ -461,6 +461,9 @@ const logPoller = new LogPoller(db, registry, {
       })
     }
   },
+  onOrphanSessionsDiscovered: () => {
+    updateDormantAgentSessions()
+  },
   isLastUserMessageLocked: (tmuxWindow) =>
     (lastUserMessageLocks.get(tmuxWindow) ?? 0) > Date.now(),
   maxLogsPerPoll: config.logPollMax,

src/server/logPoller.ts

@@ -158,6 +158,7 @@ export class LogPoller {
   private registry: SessionRegistry
   private onSessionOrphaned?: (sessionId: string, supersededBy?: string) => void
   private onSessionActivated?: (sessionId: string, window: string) => void
+  private onOrphanSessionsDiscovered?: (stats: { newOrphans: number }) => void
   private isLastUserMessageLocked?: (tmuxWindow: string) => boolean
   private maxLogsPerPoll: number
   private matchProfile: boolean
@@ -180,6 +181,7 @@ export class LogPoller {
     {
       onSessionOrphaned,
       onSessionActivated,
+      onOrphanSessionsDiscovered,
       isLastUserMessageLocked,
       maxLogsPerPoll,
       matchProfile,
@@ -189,6 +191,7 @@ export class LogPoller {
     }: {
       onSessionOrphaned?: (sessionId: string, supersededBy?: string) => void
       onSessionActivated?: (sessionId: string, window: string) => void
+      onOrphanSessionsDiscovered?: (stats: { newOrphans: number }) => void
       isLastUserMessageLocked?: (tmuxWindow: string) => boolean
       maxLogsPerPoll?: number
       matchProfile?: boolean
@@ -201,6 +204,7 @@ export class LogPoller {
     this.registry = registry
     this.onSessionOrphaned = onSessionOrphaned
     this.onSessionActivated = onSessionActivated
+    this.onOrphanSessionsDiscovered = onOrphanSessionsDiscovered
     this.isLastUserMessageLocked = isLastUserMessageLocked
     const limit = maxLogsPerPoll ?? DEFAULT_MAX_LOGS
     this.maxLogsPerPoll = Math.max(1, limit)
@@ -493,6 +497,17 @@ export class LogPoller {
     this.matchWorker = null
   }
 
+  private notifyOrphanSessionsDiscovered(newOrphans: number): void {
+    if (newOrphans <= 0) return
+    try {
+      this.onOrphanSessionsDiscovered?.({ newOrphans })
+    } catch (error) {
+      logger.warn('log_poll_discovered_callback_error', {
+        message: error instanceof Error ? error.message : String(error),
+      })
+    }
+  }
+
   async pollChanged(changedPaths: string[]): Promise<void> {
     if (this.pollInFlight) return
     this.pollInFlight = true
@@ -544,7 +559,8 @@ export class LogPoller {
         },
       })
 
-      this.processMatchResponse(response, windows, sessionRecords)
+      const stats = this.processMatchResponse(response, windows, sessionRecords)
+      this.notifyOrphanSessionsDiscovered(stats.orphans)
     } catch (error) {
       logger.warn('log_poll_changed_error', {
         message: error instanceof Error ? error.message : String(error),
@@ -1057,6 +1073,7 @@ export class LogPoller {
       }
 
       logger.info('log_poll', { ...stats })
+      this.notifyOrphanSessionsDiscovered(stats.orphans)
       return stats
     } finally {
       this.pollInFlight = false