feat(frontend): match the mobile app's sessions sheet and session header

.github/pull_request_template.md

@@ -9,7 +9,7 @@
 
 ## Checklist
 
-- [ ] Code follows project style (no comments, named imports)
+- [ ] Code follows project style (doc comments only, named imports)
 - [ ] TypeScript types are properly defined
 - [ ] Tests added/updated (80% coverage target)
 - [ ] `pnpm lint` passes locally

AGENTS.md

@@ -17,7 +17,7 @@
 
 ## Code Style
 
-- No comments, self-documenting code only
+- Doc comments only in new and changed code: JSDoc/TSDoc attached to the declaration they document, in the language's native doc convention. No inline, explanatory, or section comments; code must be self-documenting
 - No console logs (use Bun's logger or proper error handling)
 - Strict TypeScript everywhere, proper typing required
 - Named imports only: `import { Hono } from 'hono'`, `import { useState } from 'react'`

CONTRIBUTING.md

@@ -49,7 +49,7 @@ Each item is tagged with a theme to help you find work in your area of interest:
 
 ### Code Style
 
-- Self-documenting code (no comments needed)
+- New and changed code uses doc comments only (JSDoc/TSDoc on the declaration they document); no inline or explanatory comments
 - Strict TypeScript with proper typing
 - Named imports only
 - DRY principles - check for existing patterns before adding new ones

backend/src/services/opencode-event-routing.ts

@@ -52,6 +52,33 @@ export function planSessionStatusReplay(
   return { idle, busy }
 }
 
+/**
+ * Records the activity state an event implies for its session, so that directory-scoped work can be
+ * limited to the sessions that are actually running.
+ *
+ * @param busySessions Sessions currently running on the server, updated in place.
+ * @param event Event observed on the server stream.
+ */
+export function applySessionActivity(busySessions: Set<string>, event: V2Event): void {
+  switch (event.type) {
+    case 'session.status': {
+      const { sessionID, status } = event.data
+      if (status.type === 'idle') busySessions.delete(sessionID)
+      else busySessions.add(sessionID)
+      return
+    }
+    case 'session.execution.started':
+      busySessions.add(event.data.sessionID)
+      return
+    case 'session.idle':
+    case 'session.execution.succeeded':
+    case 'session.execution.failed':
+    case 'session.execution.interrupted':
+    case 'session.deleted':
+      busySessions.delete(event.data.sessionID)
+  }
+}
+
 export function createReplayEventBuilder(idPrefix: string): ReplayEventBuilder {
   let count = 0
   return (type, directory, data) => {

backend/src/services/remote-server-events.ts

@@ -14,6 +14,7 @@ import type {
   OpenCodeServerRegistry,
 } from './opencode-server-registry'
 import {
+  applySessionActivity,
   collectPendingReplayEvents,
   createAuthorizedEventSourceInit,
   createReplayEventBuilder,
@@ -63,6 +64,7 @@ interface RemoteServerStream {
   versionRequested: boolean
   versionProbeToken: number
   sessionDirectories: Map<string, string>
+  busySessions: Set<string>
   subagentSessions: Set<string>
 }
 
@@ -152,6 +154,9 @@ export class RemoteServerEventHub {
     const key = buildServerDirectoryKey(serverId, directory)
     if (!this.aggregator.hasClientDirectory(clientId, key)) return
 
+    const stream = this.streams.get(serverId)
+    if (!stream || !this.hasActiveSession(stream, directory)) return
+
     let api: OpenCodeApi
     try {
       api = this.registry.getClient(serverId).api
@@ -172,6 +177,13 @@ export class RemoteServerEventHub {
     this.emitReplayEventsToClient(clientId, serverId, directory, events.forms)
   }
 
+  private hasActiveSession(stream: RemoteServerStream, directory: string): boolean {
+    for (const sessionID of stream.busySessions) {
+      if (stream.sessionDirectories.get(sessionID) === directory) return true
+    }
+    return false
+  }
+
   private emitReplayEventsToClient(
     clientId: string,
     serverId: string,
@@ -281,6 +293,7 @@ export class RemoteServerEventHub {
     try {
       const { event, resolvedDirectory, payloadJson } = routed
       const sessionID = sessionIDFromEvent(event)
+      if (sessionID) applySessionActivity(stream.busySessions, event)
       if (sessionID && event.type === 'session.deleted') {
         stream.subagentSessions.delete(sessionID)
       } else if (event.type === 'session.created' && event.data.parentID) {
@@ -352,19 +365,24 @@ export class RemoteServerEventHub {
 
     if (!this.isStreamCurrent(serverId, stream, source)) return
 
+    await this.resolveActiveSessionDirectories(api, serverId, stream, Object.keys(active ?? {}))
+    if (!this.isStreamCurrent(serverId, stream, source)) return
+
     const plan = planSessionStatusReplay(active, stream.sessionDirectories)
     let replayed = 0
 
     for (const { sessionID, directory } of plan.idle) {
       const event = this.buildReplayEvent('session.status', directory, { sessionID, status: { type: 'idle' } })
       this.aggregator.deliverRemoteEnvelope(serverId, directory, JSON.stringify(event))
+      stream.busySessions.delete(sessionID)
       replayed++
     }
 
     for (const sessionID of plan.busy) {
       const directory = stream.sessionDirectories.get(sessionID) ?? null
       const event = this.buildReplayEvent('session.status', directory ?? '', { sessionID, status: { type: 'busy' } })
       this.aggregator.deliverRemoteEnvelope(serverId, directory, JSON.stringify(event))
+      stream.busySessions.add(sessionID)
       replayed++
     }
 
@@ -373,6 +391,26 @@ export class RemoteServerEventHub {
     }
   }
 
+  private async resolveActiveSessionDirectories(
+    api: OpenCodeApi,
+    serverId: string,
+    stream: RemoteServerStream,
+    sessionIDs: string[],
+  ): Promise<void> {
+    const unresolved = sessionIDs.filter((sessionID) => !stream.sessionDirectories.has(sessionID))
+    if (unresolved.length === 0) return
+
+    await Promise.allSettled(unresolved.map(async (sessionID) => {
+      try {
+        const session = await api.session.get({ sessionID })
+        const directory = session.location.directory
+        if (directory) stream.sessionDirectories.set(sessionID, directory)
+      } catch (error) {
+        logger.warn(`remote status replay: failed to resolve the directory of ${sessionID} on ${serverId}: ${String(error)}`)
+      }
+    }))
+  }
+
   private async refreshVersion(serverId: string): Promise<void> {
     const stream = this.streams.get(serverId)
     if (!stream || stream.versionRequested) return
@@ -413,6 +451,7 @@ export class RemoteServerEventHub {
       versionRequested: false,
       versionProbeToken: 0,
       sessionDirectories: new Map(),
+      busySessions: new Set(),
       subagentSessions: new Set(),
     }
     this.streams.set(serverId, stream)

backend/src/services/repo.ts

@@ -37,6 +37,9 @@ export class RepoInputError extends Error {
   }
 }
 
+const HTTP_AUTH_STATUS_PATTERN = /\b(?:http|status|error):?\s+401\b/
+const HTTP_NOT_FOUND_STATUS_PATTERN = /\b(?:http|status|error):?\s+404\b/
+
 function notFoundOrDeniedMessage(repoUrl: string): string {
   return `Repository not found or access denied: ${repoUrl}. Check the URL and add credentials in Settings > Git Credentials if it is private.`
 }
@@ -52,7 +55,26 @@ function enhanceCloneError(repoUrl: string, originalMessage: string): RepoInputE
     return new RepoInputError(`Repository not reachable: ${repoUrl}. Check the URL and your network connection.`)
   }
 
-  if (message.includes('repository not found') || message.includes('not found') || message.includes('does not exist') || message.includes('404')) {
+  if (
+    message.includes('authentication failed') ||
+    message.includes('could not authenticate') ||
+    message.includes('invalid credentials') ||
+    message.includes('invalid username or password') ||
+    message.includes('could not read username') ||
+    message.includes('could not read password') ||
+    HTTP_AUTH_STATUS_PATTERN.test(message)
+  ) {
+    return isGitHubHttpsUrl(repoUrl)
+      ? new RepoInputError(notFoundOrDeniedMessage(repoUrl))
+      : new RepoInputError(`Authentication failed for ${repoUrl}. Check your credentials in Settings > Git Credentials.`)
+  }
+
+  if (
+    message.includes('repository not found') ||
+    message.includes('not found') ||
+    message.includes('does not exist') ||
+    HTTP_NOT_FOUND_STATUS_PATTERN.test(message)
+  ) {
     return new RepoInputError(notFoundOrDeniedMessage(repoUrl))
   }
 
@@ -62,12 +84,6 @@ function enhanceCloneError(repoUrl: string, originalMessage: string): RepoInputE
       : new RepoInputError(notFoundOrDeniedMessage(repoUrl))
   }
 
-  if (message.includes('authentication failed') || message.includes('could not authenticate') || message.includes('invalid credentials') || message.includes('could not read username')) {
-    return isGitHubHttpsUrl(repoUrl)
-      ? new RepoInputError(notFoundOrDeniedMessage(repoUrl))
-      : new RepoInputError(`Authentication failed for ${repoUrl}. Check your credentials in Settings > Git Credentials.`)
-  }
-
   if (message.includes('not a git repository') || message.includes('fatal:')) {
     return new RepoInputError(notFoundOrDeniedMessage(repoUrl))
   }

backend/test/services/opencode-single-server.test.ts

@@ -17,6 +17,15 @@ const spawnMock = vi.hoisted(() => vi.fn(() => ({
 
 const spawnSyncMock = vi.hoisted(() => vi.fn())
 
+const processKillMock = vi.hoisted(() => vi.fn((_pid: number, signal?: number | NodeJS.Signals) => {
+  if (signal === 0) {
+    const error = new Error('kill ESRCH') as NodeJS.ErrnoException
+    error.code = 'ESRCH'
+    throw error
+  }
+  return true
+}))
+
 const readFileSyncMock = vi.hoisted(() => vi.fn())
 
 vi.mock('bun:sqlite', () => ({
@@ -186,6 +195,16 @@ const routeVersionProbeThroughExecSyncStub = () => {
 
 beforeEach(routeVersionProbeThroughExecSyncStub)
 
+const originalProcessKill = process.kill
+
+beforeEach(() => {
+  process.kill = processKillMock as unknown as typeof process.kill
+})
+
+afterEach(() => {
+  process.kill = originalProcessKill
+})
+
 // Reset singleton before any tests run to clear any polluted state from previous test files
 beforeAll(async () => {
   const { OpenCodeServerManager } = await import('../../src/services/opencode-single-server')
@@ -2823,6 +2842,7 @@ describe('OpenCodeServerManager - server auth', () => {
       await manager.start()
       await manager.stop()
 
+      expect(processKillMock).toHaveBeenCalledWith(1234, 'SIGTERM')
       const rmMock = fs.rm as unknown as ReturnType<typeof vi.fn>
       expect(rmMock).toHaveBeenCalledWith('/test/workspace/.opencode/state/opencode-server-child.json', { force: true })
     } finally {
@@ -2869,6 +2889,7 @@ describe('OpenCodeServerManager - server auth', () => {
       await secondManager.start()
 
       expect(spawnMock).toHaveBeenCalledTimes(2)
+      expect(processKillMock).toHaveBeenCalledWith(1234, 'SIGKILL')
     } finally {
       readFileMock.mockReset()
       Object.defineProperty(ENV.SERVER, 'NODE_ENV', { value: originalNodeEnv, configurable: true, writable: true })

backend/test/services/remote-server-events.test.ts

@@ -104,6 +104,7 @@ interface ApiFixture {
   permissions?: Record<string, unknown[]>
   forms?: Record<string, unknown[]>
   active?: Record<string, { type: 'running' }>
+  sessionDirectories?: Record<string, string>
 }
 
 function makeApi(fixture: ApiFixture = {}): OpenCodeApi {
@@ -126,6 +127,9 @@ function makeApi(fixture: ApiFixture = {}): OpenCodeApi {
     },
     session: {
       active: vi.fn(async () => fixture.active ?? {}),
+      get: vi.fn(async (input: { sessionID: string }) => ({
+        location: { directory: fixture.sessionDirectories?.[input.sessionID] ?? '' },
+      })),
     },
   } as unknown as OpenCodeApi
 }
@@ -779,8 +783,13 @@ describe('RemoteServerEventHub pending action replay', () => {
     sseAggregator.shutdown()
   })
 
+  function trackSessionStatus(sessionID: string, directory: string, status: string): void {
+    sources.sources[0]!.message(remoteEvent('session.status', { sessionID, status: { type: status } }, directory))
+  }
+
   it('replays pending remote actions to the subscribing client only', async () => {
     hub.start()
+    trackSessionStatus('ses-1', '/repo', 'busy')
     const client = createCapturingClient()
     const other = createCapturingClient()
     sseAggregator.addClient('replay-a', client.callback, client.writeFrame, ['srv_a|/repo'])
@@ -802,11 +811,57 @@ describe('RemoteServerEventHub pending action replay', () => {
     expect(other.frames).toHaveLength(0)
   })
 
+  it('skips the replay for a linked directory with no active session', async () => {
+    hub.start()
+    const client = createCapturingClient()
+    sseAggregator.addClient('idle', client.callback, client.writeFrame, ['srv_a|/repo'])
+
+    await flushPromises()
+
+    expect(fake.api.permission.request.list).not.toHaveBeenCalled()
+    expect(fake.api.form.list).not.toHaveBeenCalled()
+    expect(client.frames).toHaveLength(0)
+  })
+
+  it('stops replaying for a linked directory once its session goes idle', async () => {
+    hub.start()
+    trackSessionStatus('ses-1', '/repo', 'busy')
+    trackSessionStatus('ses-1', '/repo', 'idle')
+    const client = createCapturingClient()
+    sseAggregator.addClient('settled', client.callback, client.writeFrame, ['srv_a|/repo'])
+
+    await flushPromises()
+
+    expect(fake.api.permission.request.list).not.toHaveBeenCalled()
+    expect(client.frames).toHaveLength(0)
+  })
+
+  it('resolves the directory of an active session before gating the replay', async () => {
+    fake = createRegistry([SERVER_A], {
+      active: { 'ses-1': { type: 'running' } },
+      sessionDirectories: { 'ses-1': '/repo' },
+      permissions: { '/repo': [{ id: 'perm-1', sessionID: 'ses-1', action: 'shell', resources: ['ls'] }] },
+    })
+    hub = new RemoteServerEventHub(fake.registry, sseAggregator, { eventSourceFactory: sources.factory })
+    hub.start()
+    sources.sources[0]!.open()
+    await flushPromises()
+
+    const client = createCapturingClient()
+    sseAggregator.addClient('resolved', client.callback, client.writeFrame, ['srv_a|/repo'])
+    await flushPromises()
+
+    expect(fake.api.session.get).toHaveBeenCalledWith({ sessionID: 'ses-1' })
+    expect(fake.api.permission.request.list).toHaveBeenCalledWith({ location: { directory: '/repo' } })
+    expect(client.frames.map(parseFrame).map(frame => frame.payload.type)).toEqual(['permission.asked'])
+  })
+
   it('does not use the local pending action fetcher for remote keys', async () => {
     const localApi = makeApi({ permissions: { '/repo': [{ id: 'local-perm' }] } })
     sseAggregator.setPendingActionsFetcher({ api: localApi })
 
     hub.start()
+    trackSessionStatus('ses-1', '/repo', 'busy')
     const client = createCapturingClient()
     sseAggregator.addClient('mixed', client.callback, client.writeFrame, ['/repo', 'srv_a|/repo'])
 
@@ -820,6 +875,7 @@ describe('RemoteServerEventHub pending action replay', () => {
 
   it('replays remote actions when a client subscribes later', async () => {
     hub.start()
+    trackSessionStatus('ses-1', '/repo', 'busy')
     const client = createCapturingClient()
     sseAggregator.addClient('late', client.callback, client.writeFrame, [])
 
@@ -838,6 +894,7 @@ describe('RemoteServerEventHub pending action replay', () => {
     vi.mocked(fake.api.form.list).mockResolvedValue({ location: { directory: '/repo' }, data: [] })
 
     hub.start()
+    trackSessionStatus('ses-1', '/repo', 'busy')
     const client = createCapturingClient()
     sseAggregator.addClient('unsubscribed', client.callback, client.writeFrame, ['srv_a|/repo'])
     sseAggregator.removeDirectories('unsubscribed', ['srv_a|/repo'])