feat(native-chat): release a structured session when its chat closes

config/scripts/structured-lease-renewal-benchmark.ts

@@ -0,0 +1,108 @@
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { performance } from 'node:perf_hooks'
+import { AgentSessionRecordStore } from '../../src/main/runtime/agent-session-record-store'
+import { readProcessStartTimesMs } from '../../src/main/runtime/agent-session-process-identity-probe'
+import { StructuredAgentSessionLeaseRenewer } from '../../src/main/native-chat/agent-session-wire/structured-agent-session-lease-renewer'
+
+const RECORD_COUNT = 50
+const NOW = 1_800_000_000_000
+
+async function seedStore(store: AgentSessionRecordStore, directory: string): Promise<void> {
+  for (let index = 0; index < RECORD_COUNT; index += 1) {
+    const sessionId = `benchmark-session-${index}`
+    const spawnToken = `benchmark-spawn-${index}`
+    const reserved = await store.reserveOwner({
+      sessionId,
+      location: {
+        executionHostId: 'local',
+        wslDistro: null,
+        workspaceId: 'benchmark-workspace',
+        workspaceKind: 'folder'
+      },
+      provider: 'codex',
+      accountHome: { variable: 'CODEX_HOME', path: directory },
+      runtimeKind: 'native',
+      expectedFence: null,
+      spawnToken,
+      claimKeyId: 'benchmark-key',
+      handoffOperationId: null,
+      probe: { outcome: 'reservation-unused' },
+      operation: {
+        callerKey: 'benchmark',
+        operationId: `${NOW}-${index.toString(16).padStart(32, '0')}`,
+        fingerprint: `create-${index}`
+      },
+      now: NOW
+    })
+    const fence = reserved.record.lease.runtimeFence
+    await store.commitProcessIdentity({
+      sessionId,
+      fence,
+      process: {
+        hostId: 'local',
+        pid: process.pid,
+        processStartTimeMs: null,
+        spawnToken
+      },
+      now: NOW
+    })
+    await store.proveOwner({
+      sessionId,
+      fence,
+      link: {
+        linkId: `benchmark-link-${index}`,
+        handle: { provider: 'codex', threadId: `benchmark-thread-${index}` },
+        origin: 'created',
+        mintedAtFence: fence,
+        observedAt: NOW
+      },
+      now: NOW
+    })
+  }
+}
+
+async function main(): Promise<void> {
+  const directory = await mkdtemp(join(tmpdir(), 'orca-lease-renewal-benchmark-'))
+  try {
+    const store = await AgentSessionRecordStore.open({ directory, hostId: 'local' })
+    await seedStore(store, directory)
+    const renewer = new StructuredAgentSessionLeaseRenewer({
+      store,
+      probe: async () => ({ outcome: 'identity-matched', matchedOn: ['spawn-token'] }),
+      now: () => NOW + 10_000
+    })
+    const startedAt = performance.now()
+    await renewer.renewNow()
+    const elapsedMs = performance.now() - startedAt
+    const renewed = store
+      .listRecords()
+      .filter((record) => record.lease.lastRenewedAt === NOW + 10_000).length
+    const processProbeStartedAt = performance.now()
+    const processStartTimes = await readProcessStartTimesMs(
+      Array.from({ length: RECORD_COUNT }, () => process.pid),
+      'darwin'
+    )
+    console.log(
+      JSON.stringify({
+        records: RECORD_COUNT,
+        renewed,
+        elapsedMs,
+        processTableElapsedMs: performance.now() - processProbeStartedAt,
+        processTableMatches:
+          processStartTimes.get(process.pid) === null ||
+          processStartTimes.get(process.pid) === undefined
+            ? 0
+            : RECORD_COUNT
+      })
+    )
+  } finally {
+    await rm(directory, { recursive: true, force: true })
+  }
+}
+
+void main().catch((error: unknown) => {
+  console.error(error)
+  process.exitCode = 1
+})

mobile/src/session/mobile-structured-session-hold.test.ts

@@ -0,0 +1,63 @@
+import { createElement } from 'react'
+import { act, create, type ReactTestRenderer } from 'react-test-renderer'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { RpcClient } from '../transport/rpc-client'
+import { useMobileStructuredSessionHold } from './mobile-structured-session-hold'
+
+function renderHold(props: { client: RpcClient | null; sessionId: string | null }): {
+  renderer: ReactTestRenderer
+} {
+  function Probe(): null {
+    useMobileStructuredSessionHold(props)
+    return null
+  }
+  let renderer!: ReactTestRenderer
+  act(() => {
+    renderer = create(createElement(Probe))
+  })
+  return { renderer }
+}
+
+function client(sendRequest: ReturnType<typeof vi.fn>): RpcClient {
+  return { sendRequest } as unknown as RpcClient
+}
+
+let rendered: ReactTestRenderer | null = null
+
+afterEach(() => {
+  act(() => rendered?.unmount())
+  rendered = null
+})
+
+describe('a paired session view', () => {
+  it('holds the session while it is open and releases it when it closes', async () => {
+    const sendRequest = vi.fn(async () => ({ ok: true, result: {} }))
+    const { renderer } = renderHold({ client: client(sendRequest), sessionId: 'session-alpha' })
+
+    const hold = sendRequest.mock.calls.find(([method]) => method === 'agentSession.hold')
+    expect(hold?.[1]).toMatchObject({ sessionId: 'session-alpha' })
+
+    await act(async () => renderer.unmount())
+
+    const release = sendRequest.mock.calls.find(([method]) => method === 'agentSession.release')
+    expect(release?.[1]).toEqual(hold?.[1])
+  })
+
+  it('asks for nothing before there is a session to hold', () => {
+    const sendRequest = vi.fn(async () => ({ ok: true, result: {} }))
+    rendered = renderHold({ client: client(sendRequest), sessionId: null }).renderer
+
+    expect(sendRequest).not.toHaveBeenCalled()
+  })
+
+  // An older host answers method_not_found; a chat that cannot be held is still a chat that reads.
+  it('survives a host that does not know the method', () => {
+    const sendRequest = vi.fn(async () => {
+      throw new Error('method_not_found')
+    })
+
+    expect(() => {
+      rendered = renderHold({ client: client(sendRequest), sessionId: 'session-alpha' }).renderer
+    }).not.toThrow()
+  })
+})

mobile/src/session/mobile-structured-session-hold.ts

@@ -0,0 +1,37 @@
+// The paired session view telling the host it is looking at this chat.
+//
+// Same contract as the desktop chat's hold, over the mobile transport. It matters more here: a
+// phone is the surface most likely to disappear without saying anything, so the host's own
+// connection-close backstop is what usually ends up releasing this — the explicit release only
+// covers the polite case of navigating away with the socket still up.
+//
+// A host that predates the method answers `method_not_found`; the session still reads.
+
+import { useEffect } from 'react'
+import type { RpcClient } from '../transport/rpc-client'
+
+let holderOrdinal = 0
+
+export function useMobileStructuredSessionHold(args: {
+  client: RpcClient | null
+  sessionId: string | null
+}): void {
+  const { client, sessionId } = args
+  useEffect(() => {
+    if (!client || !sessionId) {
+      return
+    }
+    holderOrdinal += 1
+    const holderId = `mobile-session:${holderOrdinal}`
+    // Chained, not raced: unmounting during the hold's round trip would otherwise release a hold
+    // that has not been taken yet.
+    const held = client
+      .sendRequest('agentSession.hold', { sessionId, holderId })
+      .catch(() => undefined)
+    return () => {
+      void held.then(() =>
+        client.sendRequest('agentSession.release', { sessionId, holderId }).catch(() => undefined)
+      )
+    }
+  }, [client, sessionId])
+}

mobile/src/session/use-mobile-structured-agent-session.ts

@@ -14,6 +14,7 @@ import {
   type StructuredAgentSessionState
 } from '../../../src/shared/structured-agent-session-reducer'
 import type { RpcClient } from '../transport/rpc-client'
+import { useMobileStructuredSessionHold } from './mobile-structured-session-hold'
 import {
   createMobileStructuredReconnectState,
   noteStructuredBackground,
@@ -58,6 +59,8 @@ export function useMobileStructuredAgentSession(args: {
   loadOlder: () => Promise<boolean>
 } {
   const { client, sessionId } = args
+  // Declared before the read: the hold is what gives a restored session its provider child back.
+  useMobileStructuredSessionHold({ client, sessionId })
   const [state, dispatch] = useReducer(reduceStructuredAgentSession, EMPTY_STRUCTURED_AGENT_SESSION)
   const stateRef = useRef(state)
   const [loadingOlder, setLoadingOlder] = useState(false)

mobile/src/transport/mobile-e2ee-v2-physical-channel.test.ts

@@ -143,7 +143,7 @@ describe('mobile E2EE v2 physical channel', () => {
     expect(JSON.parse(new TextDecoder().decode(capabilities!))).toEqual({
       type: 'e2ee_client_capabilities',
       v: 1,
-      clientCapabilities: ['agent-session.structured.v1']
+      clientCapabilities: ['agent-session.structured.v1', 'agent-session.structured.hold.v1']
     })
     expect(ctx.onAuthenticated).toHaveBeenCalledOnce()
     expect(ctx.onError).not.toHaveBeenCalled()

mobile/src/transport/mobile-e2ee-v2-physical-channel.ts

@@ -2,7 +2,10 @@ import {
   createWsOutboundBackpressureQueue,
   type WsOutboundBackpressureQueue
 } from '../../../src/shared/ws-outbound-backpressure-queue'
-import { STRUCTURED_AGENT_SESSION_RUNTIME_CAPABILITY } from '../../../src/shared/protocol-version'
+import {
+  STRUCTURED_AGENT_SESSION_HOLD_RUNTIME_CAPABILITY,
+  STRUCTURED_AGENT_SESSION_RUNTIME_CAPABILITY
+} from '../../../src/shared/protocol-version'
 import type { MobileE2EEV2ClientSession } from './mobile-e2ee-v2-client-session'
 
 type ChannelState = 'awaiting-ready' | 'awaiting-authenticated' | 'ready'
@@ -117,7 +120,10 @@ export class MobileE2EEV2PhysicalChannel {
         plaintext: JSON.stringify({
           type: 'e2ee_client_capabilities',
           v: 1,
-          clientCapabilities: [STRUCTURED_AGENT_SESSION_RUNTIME_CAPABILITY]
+          clientCapabilities: [
+            STRUCTURED_AGENT_SESSION_RUNTIME_CAPABILITY,
+            STRUCTURED_AGENT_SESSION_HOLD_RUNTIME_CAPABILITY
+          ]
         })
       })
       this.args.onAuthenticated()

mobile/src/transport/rpc-client-contract.ts

@@ -36,6 +36,10 @@ export type RpcClient = {
   getState: () => ConnectionState
   getReconnectAttempt: () => number
   getLastConnectedAt: () => number | null
+  // Wall-clock stamp of the last inbound frame on the current session, or null when the
+  // transport can't vouch for one. Optional so older/foreign RpcClient shapes stay valid;
+  // callers must treat absent/null as "unknown" and fall back to a safe bound.
+  getLastInboundAt?: () => number | null
   onStateChange: (listener: (state: ConnectionState) => void) => () => void
   notifyForeground: (reason?: ForegroundNudgeReason) => void
   restartAfterStructuredBackground?: () => void

mobile/src/transport/rpc-client-structured-session.test.ts

@@ -99,7 +99,7 @@ describe('structured session RPC transport', () => {
     expect(auth).toEqual({
       type: 'e2ee_auth',
       deviceToken: 'token',
-      clientCapabilities: ['agent-session.structured.v1']
+      clientCapabilities: ['agent-session.structured.v1', 'agent-session.structured.hold.v1']
     })
     client.close()
   })

mobile/src/transport/rpc-client.ts

@@ -46,7 +46,10 @@ import {
 } from './rpc-session-liveness-watchdog'
 import { isStaleForegroundDial } from './rpc-stale-dial'
 import { websocketPayloadToUint8 } from './websocket-payload-bytes'
-import { STRUCTURED_AGENT_SESSION_RUNTIME_CAPABILITY } from '../../../src/shared/protocol-version'
+import {
+  STRUCTURED_AGENT_SESSION_HOLD_RUNTIME_CAPABILITY,
+  STRUCTURED_AGENT_SESSION_RUNTIME_CAPABILITY
+} from '../../../src/shared/protocol-version'
 import type { RpcClient, SendRequestOptions, SubscribeOptions } from './rpc-client-contract'
 
 export type { RpcClient, SendRequestOptions } from './rpc-client-contract'
@@ -374,7 +377,10 @@ export function connect(
             sendEncrypted({
               type: 'e2ee_auth',
               deviceToken,
-              clientCapabilities: [STRUCTURED_AGENT_SESSION_RUNTIME_CAPABILITY]
+              clientCapabilities: [
+                STRUCTURED_AGENT_SESSION_RUNTIME_CAPABILITY,
+                STRUCTURED_AGENT_SESSION_HOLD_RUNTIME_CAPABILITY
+              ]
             })
             return
           }

src/cli/handlers/orchestration-worker-cli.test.ts

@@ -164,6 +164,52 @@ describe('orchestration worker-start CLI contract', () => {
     expect(process.exitCode).toBe(1)
   })
 
+  it('prints the Structured Chat recovery action for a refused worker start', async () => {
+    callMock.mockResolvedValue({
+      result: {
+        taskId: 'task_1',
+        dispatchId: 'ctx_1',
+        state: 'failed',
+        failedStage: 'dispatch_input',
+        lastError:
+          'The target terminal is in Structured Chat. Switch it to Terminal, then retry `orca orchestration worker-start`.',
+        effects: [],
+        residualResources: []
+      }
+    })
+
+    await ORCHESTRATION_HANDLERS['orchestration worker-start']({
+      flags: new Map<string, string | boolean>([
+        ['task', 'task_1'],
+        ['terminal', 'term_worker'],
+        ['from', 'term_coord']
+      ]),
+      client: { call: callMock },
+      cwd: '/tmp/repo',
+      json: false
+    } as never)
+
+    const formatter = vi.mocked(printResult).mock.calls[0]?.[2] as
+      | ((result: {
+          taskId: string
+          dispatchId: string
+          state: string
+          failedStage?: string
+          lastError?: string
+        }) => string)
+      | undefined
+    expect(
+      formatter?.({
+        taskId: 'task_1',
+        dispatchId: 'ctx_1',
+        state: 'failed',
+        failedStage: 'dispatch_input',
+        lastError:
+          'The target terminal is in Structured Chat. Switch it to Terminal, then retry `orca orchestration worker-start`.'
+      })
+    ).toMatch(/Structured Chat.*Switch it to Terminal.*orca orchestration worker-start/s)
+  })
+
   it('prints a reveal warning for a live background worker', async () => {
     callMock.mockResolvedValue({
       result: {