Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

73.4 KB
Raw Blame
import type { ChatCatalog } from '@shared/chat-catalog'
import type { NormalizedAgentEvent } from '../../shared/agents/normalize'
import type { AgentStatusSnapshotEntry } from '../../shared/agent-status-snapshot'
import { subscribeAgentReplay } from '../../shared/agent-replay-subscription'
import type { DesktopWallpaper, WallpaperStill } from '../../shared/wallpaper'
import type { AlertSoundSaveResult } from '../../shared/alert-sound'
import type { RecentConversationsRequest, RecentConversationsResult } from '../../shared/recent-conversations'
import type {
  RunConfigApi,
  RunDevicesResult,
  RunEntriesResult,
  RunStartResult,
  RunStatus
} from '../../shared/run-config'
// WebSocket bridge that reconstructs `window.nodeTerminal` in the browser (Server Edition).
//
// Under Electron the preload already defines `window.nodeTerminal`; this module only runs when
// it is absent (see main.tsx's bootstrap switch). It opens ONE WebSocket to `/ws`, speaks the
// Task-1 RPC protocol (`parseRpcMessage` / `decodePtyData`), and rebuilds the three real
// namespaces (`pty`, `workspace`, `settings`) over that socket. Every other namespace comes from
// `buildStubApi()` (Task 7) so the renderer boots without a full Electron preload.

import {
  parseRpcMessage,
  encodeArgs,
  decodePtyData,
  E_DISCONNECTED,
  type RpcMessage
} from '../../shared/rpc'
import { IPC } from '../../shared/ipc'
import type {
  ChatDraftPutResult,
  ChatDraftTakeResult,
  ChatInterruptResult,
  ChatPromptResult,
  EmptyPromptResult
} from '../../shared/text-delivery'
import type { ChatScreenRead } from '../../shared/agents/claude-screen'
import type { GitHubControlApi, GitHubIssuesApi } from '../../shared/github-issues'
import {
  UNKNOWN_CLAUDE_CLI_CAPS,
  UNKNOWN_GROK_CLI_CAPS,
  UNKNOWN_CURSOR_CLI_CAPS,
  type CursorApi,
  type CursorCliCaps,
  type BoardLogApi,
  type LogApi,
  type LogRecord,
  type BoardLogReadResult,
  type ChatTranscriptResult,
  type TranscriptPresence,
  type ClaudeApi,
  type ClaudeCliCaps,
  type GrokApi,
  type GrokCliCaps,
  type HostedPending,
  type HostedSelf,
  type HostedSessionApi,
  type ClaudeSkillShareResult,
  type ClaudeSessionCopyResult,
  type CodexApi,
  type CodexIdentityCaps,
  UNKNOWN_CODEX_IDENTITY_CAPS,
  type CodexCliCaps,
  UNKNOWN_CODEX_CLI_CAPS,
  type ContextApi,
  type DownloadTicket,
  type FilesApi,
  type FsApi,
  type GitApi,
  type MemInfo,
  type NodeTerminalApi,
  type PaneKeysResult,
  type PresenceApi,
  type PtyApi,
  type PtyCreateOptions,
  type SettingsApi,
  type ClaudeUsage,
  type ProviderUsage,
  type RemoteAccountUsage,
  type RemoteUsageQuery,
  type SessionMemoryQuery,
  type SessionMemoryReport,
  type Settings,
  type SpeechApi,
  type SpeechModelInfo,
  type TmuxStatus,
  type TranscriptLine,
  type Workspace,
  type WorkspaceApi,
  type WorkspaceSaveOptions
} from '../../shared/types'
import type { PeerIdentity } from '../../shared/presence'
import type { PaneOwner } from '../../shared/agents/pane-owner-predicate'
import type { LaunchIntentExecutionResult } from '../../shared/types'
import type { WhiteboardFile, WhiteboardSaveResult } from '../../shared/whiteboard'
import { fitsOneWsFrame } from '../../shared/ws-frame'
import { buildStubApi, unsupported } from './stubs'
import { sanitizeStationNotices } from '@shared/station-notice'
import { sanitizeOutcomeRecords } from '@shared/station-outcome'
import { sanitizeHandoverRecords } from '@shared/station-handover'
import { mountPickerRoot, openDirectoryPicker } from './dialog-picker'
import { encodePcmForWire } from './speech-encode'
import { type FrameTransport, WebSocketFrameTransport } from './frame-transport'

type Listener = (...args: unknown[]) => void

/**
 * A `FrameTransport`, a pending-request map keyed by an incrementing id, and a channel-listener
 * fan-out map. Exported for the unit tests (`ws-bridge.test.ts` / `frame-transport.test.ts`). Kept
 * free of any DOM/overlay concerns so the tests stay clean — reconnect UI lives in `installWsBridge`.
 *
 * `RpcClient` speaks the rpc.ts protocol but is carrier-agnostic: it depends only on a
 * `FrameTransport` (the WebSocket to the Server Edition server, or the relay tunnel to a remote
 * desktop). For back-compat a plain URL string is accepted and wrapped in a `WebSocketFrameTransport`
 * (so the WebSocket path — and its tests — are byte-identical to before the transport was extracted).
 */
export class RpcClient {
  private transport: FrameTransport
  private nextId = 1
  private pending = new Map<number, { resolve: (v: unknown) => void; reject: (e: Error) => void }>()
  private channels = new Map<string, Set<Listener>>()
  // Events that arrived before any subscriber existed for their channel. The server can push an
  // event in the same macrotask as `open`, so a subscriber registered one microtask later (via
  // `await ready()`) would otherwise miss it. Buffered here (capped) and flushed on subscribe.
  private early: Array<{ channel: string; args: unknown[] }> = []
  private closeCbs = new Set<() => void>()

  constructor(transport: FrameTransport | string) {
    this.transport =
      typeof transport === 'string' ? new WebSocketFrameTransport(transport) : transport
    this.transport.onMessage((data) => this.onMessage(data))
    this.transport.onClose(() => {
      // Fail the in-flight requests BEFORE the overlay hooks: a response can only arrive over the
      // carrier that carried the request, so once it is gone they are unanswerable.
      this.failPending()
      this.closeCbs.forEach((cb) => cb())
    })
  }

  /**
   * Reject every in-flight request, because the socket that could have answered them is gone.
   *
   * A promise that never settles is the worst of the three outcomes. The caller's cleanup —
   * `setBusy(false)`, a `finally`, an error banner — is all downstream of the `await`, so it simply
   * never runs: a dialog sits on "Creating…" with its own Cancel button disabled by `busy`, showing
   * no error and offering no way out but Escape; a Merge or Remove looks like a silent no-op. Every
   * caller that handles a rejection at all handles this correctly the moment we actually reject, so
   * failing closed here protects features that have not been written yet, not just this one.
   */
  private failPending(): void {
    if (this.pending.size === 0) return
    const waiting = [...this.pending.values()]
    this.pending.clear() // clear first: a reject handler that fires another request must not see stale ids
    const err = Object.assign(new Error('The connection to the server was lost.'), {
      code: E_DISCONNECTED
    })
    for (const p of waiting) p.reject(err)
  }

  /** Resolves once the carrier is open; rejects if it fails to open. */
  ready(): Promise<void> {
    return this.transport.ready()
  }

  /** Register a connection-loss hook (used by the reconnect overlay). */
  onClose(cb: () => void): void {
    this.closeCbs.add(cb)
  }

  private onMessage(data: string | Uint8Array): void {
    if (typeof data === 'string') {
      const m = parseRpcMessage(data)
      if (!m) return
      this.handleJson(m)
      return
    }
    // Binary pty frame. The transport has already normalized the carrier's native binary shape
    // (ArrayBuffer in the browser, Buffer under the `ws` package in tests) to a Uint8Array.
    const decoded = decodePtyData(data)
    if (!decoded) return
    this.fanOut(IPC.ptyData(decoded.sessionId), [decoded.data])
  }

  private handleJson(m: RpcMessage): void {
    if (m.t === 'res') {
      const entry = this.pending.get(m.id)
      if (!entry) return
      this.pending.delete(m.id)
      if (m.ok) entry.resolve(m.result)
      else entry.reject(Object.assign(new Error(m.error.message), { code: m.error.code }))
    } else if (m.t === 'ev') {
      this.fanOut(m.channel, m.args)
    }
  }

  private fanOut(channel: string, args: unknown[]): void {
    const set = this.channels.get(channel)
    if (!set || set.size === 0) {
      // No subscriber yet — buffer for replay on the first subscribe (capped, drop oldest).
      this.early.push({ channel, args })
      if (this.early.length > 4096) this.early.shift()
      return
    }
    for (const fn of set) fn(...args)
  }

  /** Send a request and resolve with its result (or reject with the coded error). */
  request(method: string, ...args: unknown[]): Promise<unknown> {
    const id = this.nextId++
    return new Promise<unknown>((resolve, reject) => {
      this.pending.set(id, { resolve, reject })
      // encodeArgs: an OMITTED optional argument must reach the handler as `undefined` (so its
      // default fires) while a MEANINGFUL `null` (pty.resize park, presence clears) stays `null`.
      this.transport.send(JSON.stringify({ t: 'req', id, method, ...encodeArgs(args) }))
    })
  }

  /** Send a fire-and-forget cast (no response expected). */
  cast(method: string, ...args: unknown[]): void {
    this.transport.send(JSON.stringify({ t: 'cast', method, ...encodeArgs(args) }))
  }

  /** Subscribe to a channel; returns an unsubscribe function. */
  subscribe(channel: string, fn: Listener): () => void {
    let set = this.channels.get(channel)
    if (!set) {
      set = new Set()
      this.channels.set(channel, set)
    }
    set.add(fn)
    // Flush any events that arrived for this channel before it had a subscriber.
    if (this.early.length > 0) {
      const pending = this.early.filter((e) => e.channel === channel)
      if (pending.length > 0) {
        this.early = this.early.filter((e) => e.channel !== channel)
        for (const e of pending) fn(...e.args)
      }
    }
    return () => {
      set!.delete(fn)
      if (set!.size === 0) this.channels.delete(channel)
    }
  }
}

const AI_NAMING_UNAVAILABLE = {
  ok: false as const,
  message: 'AI naming is not available in the server edition yet'
}

/** Build the real `pty` / `workspace` / `projectSettings` / `settings` namespaces (plus the
 *  top-level `userDataDir`) over an RpcClient, mirroring the preload's
 *  invoke(→request)/send(→cast) split exactly. */
export function buildRealApi(
  client: RpcClient
): Pick<
  NodeTerminalApi,
  | 'pty'
  | 'workspace'
  | 'projectSettings'
  | 'projectSetup'
  | 'worktree'
  | 'settings'
  | 'integrations'
  | 'agent'
  | 'userDataDir'
> {
  const pty: PtyApi = {
    create: (options: PtyCreateOptions) =>
      client.request(IPC.ptyCreate, options) as ReturnType<PtyApi['create']>,
    write: (sessionId, data) => client.cast(IPC.ptyWrite, sessionId, data),
    resize: (sessionId, cols, rows, viewerId) =>
      client.cast(IPC.ptyResize, sessionId, cols, rows, viewerId),
    setFlow: (sessionId, resume, viewerId) => client.cast(IPC.ptyFlow, sessionId, resume, viewerId),
    kill: (sessionId, viewerId) => client.cast(IPC.ptyKill, sessionId, viewerId),
    // The trailing flag rides as a plain boolean; the core handler re-checks `=== true`.
    destroy: (persistKey, opts) =>
      client.cast(IPC.ptyDestroy, persistKey, opts?.everySocket === true),
    recycle: (persistKey) => client.cast(IPC.ptyRecycle, persistKey),
    // No server handler — degrade gracefully (never reject the boot path).
    generateName: () => Promise.resolve(AI_NAMING_UNAVAILABLE),
    generateGroupName: () => Promise.resolve(AI_NAMING_UNAVAILABLE),
    capture: (persistKey, full) =>
      client.request(IPC.ptyCapture, persistKey, full).catch(() => '') as Promise<string>,
    // Documented degrade, not a stub with a hole in it: SSH PROJECTS are desktop-only (the whole
    // `sshProject` surface is `U(...)`-stubbed here), so no browser session ever holds a remote
    // ControlMaster to attach early over. `false` = "never attach early" = the pre-feature wait,
    // which is exactly right for a shell that cannot produce the question.
    remoteSessionConfirmed: () => Promise.resolve(false),
    // REAL, unlike `remoteSessionConfirmed` above: the server runs on the machine whose tmux it is
    // reading, so the local leg of this probe is exactly right there. Fail-open to `null` = "could
    // not tell", the same answer every other failure path gives.
    sessionAge: (persistKey) =>
      client.request(IPC.ptySessionAge, persistKey).catch(() => null) as Promise<number | null>,
    readScrollback: (persistKey) =>
      client.request(IPC.ptyReadScrollback, persistKey) as Promise<string>,
    sendText: (persistKey, text, opts) =>
      client.request(IPC.ptySendText, persistKey, text, opts?.enter) as Promise<boolean>,
    sendChatPrompt: (persistKey, text, agentId) =>
      client.request(IPC.ptySendChatPrompt, persistKey, text, agentId) as Promise<ChatPromptResult>,
    sendToEmptyPrompt: (persistKey, text, agentId) =>
      client.request(IPC.ptySendToEmptyPrompt, persistKey, text, agentId) as Promise<EmptyPromptResult>,
    // Real: core registers it. A failed read is "could not tell", never a dialog.
    readChatScreen: (persistKey, agentId) =>
      client
        .request(IPC.ptyReadChatScreen, persistKey, agentId)
        .catch(() => ({ screen: { kind: 'unknown' }, suggestion: null })) as Promise<ChatScreenRead>,
    // Real: core registers it. A failed request (a relay host refusing a non-editor) is `failed`.
    interruptChat: (persistKey, agentId, sentText) =>
      client
        .request(IPC.ptyInterruptChat, persistKey, agentId, sentText)
        .catch(() => ({ sent: false, reason: 'failed' })) as Promise<ChatInterruptResult>,
    // Real: core registers both. A failed request is `failed`, which changes nothing on either side.
    putChatDraft: (persistKey, agentId, text) =>
      client
        .request(IPC.ptyPutChatDraft, persistKey, agentId, text)
        .catch(() => ({ put: false, reason: 'failed' })) as Promise<ChatDraftPutResult>,
    takeChatDraft: (persistKey, agentId) =>
      client
        .request(IPC.ptyTakeChatDraft, persistKey, agentId)
        .catch(() => ({ taken: false, reason: 'failed' })) as Promise<ChatDraftTakeResult>,
    // A failed read is unknown, never evidence that persistence is available.
    tmuxStatus: () =>
      client
        .request(IPC.ptyTmuxStatus)
        .catch(() => ({ available: false, installCommand: null, installLabel: null, platform: null, persistence: null })) as Promise<TmuxStatus>,
    // Unknown on failure (null), never a rejection: the restart poller reads null as "not a
    // shell yet" and gives up on its own deadline.
    paneCommand: (persistKey, opts) =>
      client.request(IPC.ptyPaneCommand, persistKey, opts).catch(() => null) as Promise<string | null>,
    // Real: core registers it. Unknown (null) on failure — a relay host refuses it to a non-editor
    // (EDITOR_ONLY), which reads as "no live cwd" and file links keep the node's launch cwd.
    paneCwd: (persistKey) =>
      client.request(IPC.ptyPaneCwd, persistKey).catch(() => null) as Promise<string | null>,
    // Real: core registers it (host-only; a relay host refuses it). Never rejects.
    sendPaneKeys: (nodeId, data) =>
      client.request(IPC.ptySendPaneKeys, nodeId, data).catch(() => ({ ok: false, reason: 'failed' })) as Promise<PaneKeysResult>,
    // Documented degrade (#925): the Server Edition starts nodes through its HeadlessNodeFactory,
    // never through the browser renderer, so there is nothing for this to call.
    launchHeadless: () => unsupported('pty.launchHeadless'),
    // A REAL implementation, not a stub: core registers the handler, so the server this browser is
    // served from answers it. The hibernation exit fails CLOSED on a null, so a stub here would
    // have silently switched Eco off for the whole Server Edition rather than degrade it.
    paneOwner: (persistKey, opts) =>
      client.request(IPC.ptyPaneOwner, persistKey, opts).catch(() => null) as Promise<PaneOwner | null>,
    terminateForeground: (persistKey, expectedAgentId) =>
      client.request(IPC.ptyTerminateForeground, persistKey, expectedAgentId).catch(() => false) as Promise<boolean | 'unsupported'>,
    // REAL: core registers it, so a server running on Windows answers with its own session host.
    // On the Linux server every call answers `unsupported-shell` and the caller types its legacy
    // line. A transport failure is `delivery-failed`, NOT a fallback: the reply may be what was
    // lost, and typing the legacy line after a launch that did land would start the agent twice.
    executeLaunch: (persistKey, request) =>
      (client.request(IPC.ptyExecuteLaunch, persistKey, request) as Promise<LaunchIntentExecutionResult>).catch(
        (): LaunchIntentExecutionResult => ({
          ok: false,
          reason: 'delivery-failed',
          message: 'The agent launch could not be delivered to the terminal.'
        })
      ),
    // No server handler — the session-name poll degrades to no adopted name. A PRE-EXISTING gap,
    // and not any one agent's: `IPC.ptyReadSessionName` has never been registered server-side, so
    // claude's, grok's and gemini's read legs are equally stubbed here (the write leg works on both
    // surfaces — it goes through pty.sendText). The routing itself is already in core
    // (`core/agent-session-name.ts`) and the server already threads gemini's path association into
    // its session-name SWEEP, which is what keeps the phone's names correct; only this per-node poll
    // is missing. Fixing it means registering the channel from both shells, exactly as
    // `core/transcript-ipc.ts` did for the ⌘M transcript channels.
    readSessionName: () => Promise.resolve(''),
    onData: (sessionId, listener) =>
      client.subscribe(IPC.ptyData(sessionId), listener as Listener),
    onExit: (sessionId, listener) =>
      client.subscribe(IPC.ptyExit(sessionId), listener as Listener),
    // Co-attach channels: ordinary JSON `ev` frames (only pty:data is binary), so the frame
    // decoder is unchanged — they just fan out through the generic channel subscription.
    onSize: (sessionId, listener) => client.subscribe(IPC.ptySize(sessionId), listener as Listener),
    onClosed: (sessionId, listener) =>
      client.subscribe(IPC.ptyClosed(sessionId), listener as Listener),
    onRecycled: (sessionId, listener) =>
      client.subscribe(IPC.ptyRecycled(sessionId), listener as Listener),
    onResync: (sessionId, listener) =>
      client.subscribe(IPC.ptyResync(sessionId), listener as Listener)
  }

  const workspace: WorkspaceApi = {
    load: () => client.request(IPC.workspaceLoad) as Promise<Workspace>,
    save: (ws: Workspace, opts?: WorkspaceSaveOptions) => client.request(IPC.workspaceSave, ws, opts) as Promise<void>,
    // REAL: core's WorkspaceStore registers it, and it is the whole point on this surface — two
    // browser tabs on one project must not both type a launch (#1173).
    claimLaunch: (nodeId: string, command: string, manual: boolean) =>
      client.request(IPC.workspaceClaimLaunch, nodeId, command, manual) as Promise<'claimed' | 'elsewhere'>,
    // REAL: WorkspaceStore (core) registers IPC.workspaceProbeFolder, so the server serves it.
    // Stubbing it to `null` meant "Open folder…" on a repo that already carries a committed
    // .nodeterm/project.json concluded there was no project there, created an EMPTY one, and the
    // next writeDisk() overwrote the team's shared canvas. Data loss, not a degrade.
    probeFolder: (folder: string) =>
      client.request(IPC.workspaceProbeFolder, folder) as ReturnType<WorkspaceApi['probeFolder']>,
    // REAL for the same reason: core registers IPC.workspaceProjectFileState, and a stub would
    // have to answer 'unreadable' — which is the side that never recovers a deleted project file.
    projectFileState: (folder: string) =>
      client.request(IPC.workspaceProjectFileState, folder) as ReturnType<
        WorkspaceApi['projectFileState']
      >,
    // REAL: core registers both (issue #1145), and the Server Edition stores projects the same way.
    releaseFolderFiles: (projectId: string, removeTracked: boolean) =>
      client.request(IPC.workspaceReleaseFolderFiles, projectId, removeTracked) as ReturnType<
        WorkspaceApi['releaseFolderFiles']
      >,
    prepareFolderStorage: (projectId: string) =>
      client.request(IPC.workspacePrepareFolderStorage, projectId) as ReturnType<
        WorkspaceApi['prepareFolderStorage']
      >,
    projectStorage: (projectId: string) =>
      client.request(IPC.workspaceProjectStorage, projectId) as ReturnType<
        WorkspaceApi['projectStorage']
      >,
    // REAL: core broadcasts IPC.workspaceMigrated after a v2→v3 migration (workspace-store.ts).
    onMigrated: (cb) => client.subscribe(IPC.workspaceMigrated, cb as Listener),
    // REAL: core broadcasts IPC.workspaceCorruptRecovered from the load path (workspace-store.ts).
    onCorruptRecovered: (cb) => client.subscribe(IPC.workspaceCorruptRecovered, cb as Listener),
    // Server Edition runs the shared WorkspaceWatcher and broadcasts outside file edits here.
    // Remote-node adoption (the phone appending a session it started) rides it too: that IS
    // "another device", which is what this channel means.
    onExternalChange: (cb) => client.subscribe(IPC.workspaceExternalChange, cb as Listener),
    // REAL: Server Edition canvas control broadcasts its own persisted bridge/rope changes here —
    // wider than the node-only canvas:mut vocabulary, but ours, so they must not travel the
    // outside-edit channel and end up behind the conflict bar (see server/canvas-control.ts).
    onServerChange: (cb) => client.subscribe(IPC.workspaceServerChange, cb as Listener),
    // Documented degrade: the quit / restart-to-update flush is a desktop main-process request.
    // The server never quits on a tab's behalf, and the debounced autosave covers a browser.
    onFlushRequest: () => () => {}
  }

  // REAL: WorkspaceStore (core) registers the project-settings:* channels too — same
  // registerIpc() call as workspace above — so the server serves this on both shells.
  const projectSettings: NodeTerminalApi['projectSettings'] = {
    read: (projectId) =>
      client.request(IPC.projectSettingsRead, projectId) as ReturnType<
        NodeTerminalApi['projectSettings']['read']
      >,
    writeShared: (projectId, doc) =>
      client.request(IPC.projectSettingsWriteShared, projectId, doc) as Promise<boolean>,
    updateLocal: (projectId, local) =>
      client.request(IPC.projectSettingsUpdateLocal, projectId, local) as Promise<boolean>,
    launchInfo: (projectId) =>
      client.request(IPC.projectSettingsLaunchInfo, projectId) as ReturnType<
        NodeTerminalApi['projectSettings']['launchInfo']
      >,
    // REAL: `ProjectSetupService.ensureFamilyTrusted` broadcasts IPC.projectTrustChanged on every
    // approval, for each project id that asked.
    onTrustChanged: (cb) => client.subscribe(IPC.projectTrustChanged, cb as Listener)
  }

  // REAL: registerProjectSetupHandlers (core) is wired on the same construction-order point as
  // src/main/index.ts. Wire carries exactly `(projectId, kind, worktreePath?)` — no rootPath/
  // projectName/ssh; the server derives those itself from its own workspace index, same as main.
  const projectSetup: NodeTerminalApi['projectSetup'] = {
    run: (projectId, kind, worktreePath) =>
      client.request(IPC.projectSetupRun, projectId, kind, worktreePath) as ReturnType<
        NodeTerminalApi['projectSetup']['run']
      >,
    cancel: (runKey) => client.request(IPC.projectSetupCancel, runKey) as Promise<boolean>,
    consent: async (requestId, answer) => {
      client.cast(IPC.projectSetupConsentSubmit, requestId, answer)
    },
    // Fails CLOSED on a rejection rather than throwing at the caller: over the relay this method is
    // host-only, so a guest's call comes back E_FORBIDDEN — and "not trusted" is exactly the right
    // answer for a client that may not raise the host's dialog.
    requestTrust: (projectId, family) =>
      client.request(IPC.projectSetupRequestTrust, projectId, family).then(
        (v) => v === true,
        () => false
      ),
    onConsentRequest: (cb) => client.subscribe(IPC.projectSetupConsentRequest, cb as Listener),
    onConsentDismiss: (cb) => client.subscribe(IPC.projectSetupConsentDismiss, cb as Listener),
    onEvent: (projectId, cb) => {
      const unsub = client.subscribe(IPC.projectSetupEvent(projectId), cb as Listener)
      client.cast(IPC.projectSetupSubscribe, projectId)
      return () => {
        unsub()
        client.cast(IPC.projectSetupUnsubscribe, projectId)
      }
    }
  }

  // REAL: registerWorktreeSharedPathsHandlers (core), same construction point as main/server. Wire
  // carries exactly `(projectId, worktreePath)`; the server reads the sharedPaths list itself.
  const worktree: NodeTerminalApi['worktree'] = {
    materializeShared: (projectId, worktreePath) =>
      client.request(IPC.worktreeMaterializeShared, projectId, worktreePath) as ReturnType<
        NodeTerminalApi['worktree']['materializeShared']
      >
  }

  const settings: SettingsApi = {
    load: () => client.request(IPC.settingsLoad) as Promise<Settings>,
    save: (s: Settings) => client.request(IPC.settingsSave, s) as Promise<void>
  }

  // REAL: both shells boot the consent lifecycle (core/agent-integrations.ts) and register it.
  const integrations: NodeTerminalApi['integrations'] = {
    status: () => client.request(IPC.integrationsStatus) as ReturnType<NodeTerminalApi['integrations']['status']>
  }

  const agent: NodeTerminalApi['agent'] = {
    // Deliberately NOT a request: the server registers no env-snapshot handler (a full host-env
    // dump answerable by any authenticated WS client is the PR #195 leak class at the RPC layer).
    // An empty snapshot makes `${env:VAR}` expansion surface every referenced var as missing, and
    // the launch paths refuse rather than type a mangled line.
    envSnapshot: () => Promise.resolve({}),
    discoverModels: (gateway) =>
      client.request(IPC.agentDiscoverModels, gateway) as ReturnType<
        NodeTerminalApi['agent']['discoverModels']
      >,
    gatewayCredentialStatus: () =>
      client.request(IPC.agentGatewayCredentialStatus) as ReturnType<
        NodeTerminalApi['agent']['gatewayCredentialStatus']
      >,
    saveGatewayCredential: (apiKey) =>
      client.request(IPC.agentGatewayCredentialSave, apiKey) as ReturnType<
        NodeTerminalApi['agent']['saveGatewayCredential']
      >,
    clearGatewayCredential: () =>
      client.request(IPC.agentGatewayCredentialClear) as ReturnType<
        NodeTerminalApi['agent']['clearGatewayCredential']
      >
  }

  // The server's data dir, over the SAME channel the desktop preload uses. It is the writable base
  // the worktree dialog derives its default path from — a stub returning '' would suggest
  // `/worktrees/…` at the filesystem root (the server usually runs as root, and git would create it).
  const userDataDir = (): Promise<string> => client.request(IPC.appUserDataDir) as Promise<string>

  return { pty, workspace, projectSettings, projectSetup, worktree, settings, integrations, agent, userDataDir }
}

export function buildGitHubApi(
  client: RpcClient
): Pick<NodeTerminalApi, 'githubIssues' | 'githubControl'> {
  const githubIssues: GitHubIssuesApi = {
    subscribe: (projectId) =>
      client.request(IPC.githubIssuesSubscribe, { projectId }) as ReturnType<
        GitHubIssuesApi['subscribe']
      >,
    unsubscribe: async (projectId) => {
      client.cast(IPC.githubIssuesUnsubscribe, projectId)
    },
    query: (request) =>
      client.request(IPC.githubIssuesQuery, request) as ReturnType<GitHubIssuesApi['query']>,
    refresh: (projectId, full) =>
      client.request(IPC.githubIssuesRefresh, projectId, full) as Promise<void>,
    moveIssue: (request) =>
      client.request(IPC.githubIssuesMove, request) as ReturnType<GitHubIssuesApi['moveIssue']>,
    createMissingLabels: (projectId) =>
      client.request(IPC.githubIssuesCreateLabels, projectId) as ReturnType<
        GitHubIssuesApi['createMissingLabels']
      >,
    clearCache: (projectId) =>
      client.request(IPC.githubIssuesClearCache, projectId) as Promise<void>,
    pullStatus: (projectId) =>
      client.request(IPC.githubIssuesPullStatus, projectId) as ReturnType<GitHubIssuesApi['pullStatus']>,
    chasePulls: (projectId) =>
      client.request(IPC.githubIssuesChasePulls, projectId) as Promise<boolean>,
    pullChecks: (projectId, pullNumber) =>
      client.request(IPC.githubIssuesPullChecks, projectId, pullNumber) as ReturnType<
        GitHubIssuesApi['pullChecks']
      >,
    claimPullAutoMove: (request) =>
      client.request(IPC.githubIssuesClaimPullAutoMove, request) as Promise<boolean>,
    notePullWaits: (request) =>
      client.request(IPC.githubIssuesNotePullWaits, request) as Promise<number>,
    projectAvatar: (projectId) =>
      client.request(IPC.githubProjectAvatar, projectId) as ReturnType<
        GitHubIssuesApi['projectAvatar']
      >,
    onChanged: (projectId, listener) =>
      client.subscribe(IPC.githubIssuesChanged(projectId), listener as Listener)
  }

  const githubControl: GitHubControlApi = {
    status: (projectId) =>
      client.request(IPC.githubControlStatus, projectId) as ReturnType<GitHubControlApi['status']>,
    approve: (input) =>
      client.request(IPC.githubControlApprove, input) as ReturnType<GitHubControlApi['approve']>,
    revoke: (input) =>
      client.request(IPC.githubControlRevoke, input) as ReturnType<GitHubControlApi['revoke']>,
    selectProvider: (input) =>
      client.request(IPC.githubControlSelectProvider, input) as ReturnType<
        GitHubControlApi['selectProvider']
      >,
    saveToken: (token) =>
      client.request(IPC.githubControlSaveToken, token) as ReturnType<GitHubControlApi['saveToken']>,
    clearToken: () =>
      client.request(IPC.githubControlClearToken) as ReturnType<GitHubControlApi['clearToken']>
  }

  return { githubIssues, githubControl }
}

/**
 * Build the real `fs` / `git` / `files` / `context` namespaces over an RpcClient, mirroring the
 * preload's invoke(→request) / send(→cast) / on*(→subscribe) split member-for-member. Every
 * `fs.*`, `git.*`, `files.quickOpen` and `git.generateMessage` member is an `invoke` in the
 * preload → `client.request`; `context.ensure` is a `send` → `client.cast`; the event-shaped
 * `git.onCloneProgress` / `context.onUpdate` are `.on` → `client.subscribe`. `git.generateMessage`
 * routes over `IPC.commitGenerate` (not a git:* channel) exactly as the preload does. Each namespace
 * is declared against its `NodeTerminalApi` slice so `satisfies` makes the compiler the completeness
 * gate: a missing or misnamed member fails typecheck.
 */
export function buildFilesApi(
  client: RpcClient
): Pick<NodeTerminalApi, 'fs' | 'git' | 'files' | 'context' | 'boardLog' | 'logs'> {
  const fs: FsApi = {
    list: (dirPath) => client.request(IPC.fsList, dirPath) as ReturnType<FsApi['list']>,
    read: (filePath) => client.request(IPC.fsRead, filePath) as Promise<string>,
    readBinary: (filePath) => client.request(IPC.fsReadBinary, filePath) as Promise<string>,
    write: (filePath, content) => client.request(IPC.fsWrite, filePath, content) as Promise<boolean>,
    mkdir: (dirPath) => client.request(IPC.fsMkdir, dirPath) as Promise<boolean>,
    exists: (p) => client.request(IPC.fsExists, p) as Promise<boolean>
  }

  const git: GitApi = {
    status: (cwd) => client.request(IPC.gitStatus, cwd) as ReturnType<GitApi['status']>,
    init: (cwd) => client.request(IPC.gitInit, cwd) as ReturnType<GitApi['init']>,
    clone: (parentDir, url) =>
      client.request(IPC.gitClone, parentDir, url) as ReturnType<GitApi['clone']>,
    cloneAbort: () => client.request(IPC.gitCloneAbort) as Promise<void>,
    cloneDefaultParent: () => client.request(IPC.gitCloneDefaultParent) as Promise<string>,
    onCloneProgress: (listener) => client.subscribe(IPC.gitCloneProgress, listener as Listener),
    commit: (cwd, message) =>
      client.request(IPC.gitCommit, cwd, message) as ReturnType<GitApi['commit']>,
    push: (cwd) => client.request(IPC.gitPush, cwd) as ReturnType<GitApi['push']>,
    pull: (cwd) => client.request(IPC.gitPull, cwd) as ReturnType<GitApi['pull']>,
    sync: (cwd) => client.request(IPC.gitSync, cwd) as ReturnType<GitApi['sync']>,
    publish: (cwd, name, isPrivate) =>
      client.request(IPC.gitPublish, cwd, name, isPrivate) as ReturnType<GitApi['publish']>,
    stage: (cwd, paths) => client.request(IPC.gitStage, cwd, paths) as ReturnType<GitApi['stage']>,
    unstage: (cwd, paths) =>
      client.request(IPC.gitUnstage, cwd, paths) as ReturnType<GitApi['unstage']>,
    stageAll: (cwd) => client.request(IPC.gitStageAll, cwd) as ReturnType<GitApi['stageAll']>,
    unstageAll: (cwd) => client.request(IPC.gitUnstageAll, cwd) as ReturnType<GitApi['unstageAll']>,
    diff: (cwd, path, staged, untracked) =>
      client.request(IPC.gitDiff, cwd, path, staged, untracked) as Promise<string>,
    discard: (cwd, path, untracked) =>
      client.request(IPC.gitDiscard, cwd, path, untracked) as ReturnType<GitApi['discard']>,
    switchBranch: (cwd, name) =>
      client.request(IPC.gitSwitchBranch, cwd, name) as ReturnType<GitApi['switchBranch']>,
    createBranch: (cwd, name) =>
      client.request(IPC.gitCreateBranch, cwd, name) as ReturnType<GitApi['createBranch']>,
    showFile: (cwd, ref, path) =>
      client.request(IPC.gitShowFile, cwd, ref, path) as Promise<string>,
    generateMessage: (cwd) =>
      client.request(IPC.commitGenerate, cwd) as ReturnType<GitApi['generateMessage']>,
    history: (cwd, options) =>
      client.request(IPC.gitHistory, cwd, options) as ReturnType<GitApi['history']>,
    commitFiles: (cwd, oid) =>
      client.request(IPC.gitCommitFiles, cwd, oid) as ReturnType<GitApi['commitFiles']>,
    remoteCommitUrl: (cwd, sha) =>
      client.request(IPC.gitRemoteCommitUrl, cwd, sha) as Promise<string | null>,
    merge: (cwd, ref) => client.request(IPC.gitMerge, cwd, ref) as ReturnType<GitApi['merge']>,
    rebase: (cwd, onto) => client.request(IPC.gitRebase, cwd, onto) as ReturnType<GitApi['rebase']>,
    deleteBranch: (cwd, name, force) =>
      client.request(IPC.gitDeleteBranch, cwd, name, force) as ReturnType<GitApi['deleteBranch']>,
    renameBranch: (cwd, newName) =>
      client.request(IPC.gitRenameBranch, cwd, newName) as ReturnType<GitApi['renameBranch']>,
    fetch: (cwd) => client.request(IPC.gitFetch, cwd) as ReturnType<GitApi['fetch']>,
    forcePush: (cwd) => client.request(IPC.gitForcePush, cwd) as ReturnType<GitApi['forcePush']>,
    stashPush: (cwd) => client.request(IPC.gitStashPush, cwd) as ReturnType<GitApi['stashPush']>,
    stashPop: (cwd) => client.request(IPC.gitStashPop, cwd) as ReturnType<GitApi['stashPop']>,
    revert: (cwd, oid) => client.request(IPC.gitRevert, cwd, oid) as ReturnType<GitApi['revert']>,
    branchAt: (cwd, name, oid) =>
      client.request(IPC.gitBranchAt, cwd, name, oid) as ReturnType<GitApi['branchAt']>,
    checkoutCommit: (cwd, oid) =>
      client.request(IPC.gitCheckoutCommit, cwd, oid) as ReturnType<GitApi['checkoutCommit']>,
    repoRoot: (cwd) => client.request(IPC.gitRepoRoot, cwd) as Promise<string | null>,
    worktreeList: (repoPath) =>
      client.request(IPC.gitWorktreeList, repoPath) as ReturnType<GitApi['worktreeList']>,
    worktreeAdd: (repoPath, wtPath, branch, baseRef, isNew) =>
      client.request(
        IPC.gitWorktreeAdd,
        repoPath,
        wtPath,
        branch,
        baseRef,
        isNew
      ) as ReturnType<GitApi['worktreeAdd']>,
    worktreeMerge: (repoPath, branch, baseRef, push) =>
      client.request(
        IPC.gitWorktreeMerge,
        repoPath,
        branch,
        baseRef,
        push
      ) as ReturnType<GitApi['worktreeMerge']>,
    worktreeRemove: (repoPath, wtPath, deleteBranch, pruneOnly) =>
      client.request(
        IPC.gitWorktreeRemove,
        repoPath,
        wtPath,
        deleteBranch,
        pruneOnly
      ) as ReturnType<GitApi['worktreeRemove']>,
    setActiveRemote: (projectId) =>
      client.request(IPC.gitSetActiveRemote, projectId) as Promise<void>
  }

  const files: FilesApi = {
    quickOpen: (cwd) => client.request(IPC.filesQuickOpen, cwd) as Promise<string[]>,
    // A REAL implementation, not a stub: this is the browser's only way to get a file off the
    // server, and it deliberately does not stream through this socket — it mints a ticket the
    // browser redeems with a plain GET (src/server/download.ts).
    downloadTicket: (p) => client.request(IPC.filesDownloadTicket, p) as Promise<DownloadTicket | null>,
    // Also real, and the direction that matters here: the browser holds the bytes, the terminal
    // runs on the server, so a pasted image only becomes nameable once the server has written it.
    saveUpload: (name, dataBase64) =>
      client.request(IPC.filesSaveUpload, name, dataBase64) as Promise<string | null>,
    // Real too, and for the same reason: the browser holds the bytes and the project folder is on
    // the server, so only the server can put a canvas image where the canvas will find it again.
    saveCanvasImage: (projectId, name, dataBase64) =>
      client.request(IPC.filesSaveCanvasImage, projectId, name, dataBase64) as Promise<
        string | null
      >,
    // Real: the whiteboard's side file sits beside the server's project.json.
    // The server closes the WHOLE socket (code 1009) on a client frame over WS_MAX_PAYLOAD, so a
    // board too big for one frame is refused here, before sending — the node shows "Not saved"
    // instead of the browser tab losing its connection to every terminal.
    saveWhiteboard: (projectId, nodeId, scene, thumbnailBase64, expectedRev) =>
      fitsOneWsFrame([projectId, nodeId, scene, thumbnailBase64, expectedRev])
        ? (client.request(IPC.filesSaveWhiteboard, projectId, nodeId, scene, thumbnailBase64, expectedRev) as Promise<
            WhiteboardSaveResult | string | null
          >)
        : Promise.resolve(null),
    readWhiteboard: (projectId, nodeId, sourceId, withScene) =>
      client.request(IPC.filesReadWhiteboard, projectId, nodeId, sourceId, withScene) as Promise<WhiteboardFile | null>,
    // Real: the browser holds the picked sound's bytes and the data dir is the server's, so the
    // server stores it and serves it back by kind (issue #289). The browser's own path never leaves
    // the browser — a host-local path would not exist on the server anyway.
    saveAlertSound: (kind, name, dataBase64) =>
      client.request(IPC.filesSaveAlertSound, kind, name, dataBase64) as Promise<AlertSoundSaveResult>,
    readAlertSound: (kind) => client.request(IPC.filesReadAlertSound, kind) as Promise<string | null>,
    clearAlertSound: (kind) => client.request(IPC.filesClearAlertSound, kind) as Promise<boolean>
  }

  const context: ContextApi = {
    onUpdate: (listener) => client.subscribe(IPC.contextUpdate, listener as Listener),
    onRemoteControl: (listener) => client.subscribe(IPC.agentRemoteControl, listener as Listener),
    ensure: (sessionId, cwd, accountId, nodeId, agentId) =>
      client.cast(IPC.contextEnsure, sessionId, cwd, accountId, nodeId, agentId)
  }

  // Board-log: REAL over the bridge for local projects (the server routes local; SSH projects on the
  // server answer `unsupported`). `onChanged` is `.on` → subscribe, plus the ref-counted cast pair the
  // preload sends so the server starts/stops watching this project's log.
  const boardLog: BoardLogApi = {
    append: (projectId, entry) =>
      client.request(IPC.boardLogAppend, projectId, entry) as Promise<boolean>,
    read: (projectId, opts) =>
      client.request(IPC.boardLogRead, projectId, opts) as Promise<BoardLogReadResult>,
    onChanged: (projectId, cb) => {
      const unsub = client.subscribe(IPC.boardLogChanged(projectId), cb as Listener)
      client.cast(IPC.boardLogSubscribe, projectId)
      return () => {
        unsub()
        client.cast(IPC.boardLogUnsubscribe, projectId)
      }
    }
  }

  // Same core on the server, so the log ring is real over the bridge — the panel debugs the
  // Server Edition process, which is exactly where a packaged-app console is least visible.
  const logs: LogApi = {
    snapshot: () => client.request(IPC.logSnapshot) as Promise<LogRecord[]>,
    clear: () => client.cast(IPC.logClear),
    onBatch: (cb) => {
      const unsub = client.subscribe(IPC.logBatch, cb as Listener)
      client.cast(IPC.logSubscribe)
      return () => {
        unsub()
        client.cast(IPC.logUnsubscribe)
      }
    }
  }

  return { fs, git, files, context, boardLog, logs }
}

/**
 * The Server Edition's station-failure notices — REAL, because the server's canvas-control runtime
 * opens stations headlessly and its monitor is the one that decides (src/core/agents/
 * station-notice.ts). Kept OUT of `buildAgentApi` on purpose: that builder is spread into relay
 * tabs too, and a relay tab's stations are the host's to report, never this browser's.
 */
export function buildStationNoticeApi(
  client: RpcClient
): Pick<NodeTerminalApi, 'stationNotice' | 'boardDispatch'> {
  return {
    // Same host-only class as the DROPPED report beside it: this tab's own dispatcher state, read by
    // the server's `issues` control verb (core/board-dispatch-report.ts). Never spread into a relay tab.
    boardDispatch: {
      report: (entries) => {
        void client.request(IPC.boardDispatchReport, entries).catch(() => undefined)
      }
    },
    stationNotice: {
      list: () =>
        (client.request(IPC.stationNoticeList) as Promise<unknown>).then(sanitizeStationNotices, () => []),
      onChanged: (cb) =>
        client.subscribe(IPC.stationNoticeChanged, ((views: unknown) =>
          cb(sanitizeStationNotices(views))) as Listener),
      reportDropped: (nodeId, dropped) => {
        void client.request(IPC.stationNoticeDropped, nodeId, dropped).catch(() => undefined)
      }
    }
  }
}

/**
 * The Server Edition's station task outcomes — REAL, for the same reason as station notices: the
 * server's canvas-control runtime records `report-outcome` and honours `--after-success` headlessly,
 * and a browser tab's QUEUED badge and `list` must say what the server knows. Kept out of
 * `buildAgentApi`, which relay tabs share. The hand-over list (src/core/station-handover.ts) is real
 * for the same reason: the server's headless factory honours plain `--after` with it, and `list`
 * names it.
 */
export function buildStationHandoverApi(client: RpcClient): Pick<NodeTerminalApi, 'stationHandover'> {
  return {
    stationHandover: {
      list: () =>
        (client.request(IPC.stationHandoverList) as Promise<unknown>).then(sanitizeHandoverRecords, () => []),
      onChanged: (cb) =>
        client.subscribe(IPC.stationHandoverChanged, ((records: unknown) =>
          cb(sanitizeHandoverRecords(records))) as Listener)
    }
  }
}

/**
 * The Server Edition's station task outcomes — the real bridge, see `buildStationHandoverApi`'s note.
 */
export function buildStationOutcomeApi(client: RpcClient): Pick<NodeTerminalApi, 'stationOutcome'> {
  return {
    stationOutcome: {
      list: () =>
        (client.request(IPC.stationOutcomeList) as Promise<unknown>).then(sanitizeOutcomeRecords, () => []),
      onChanged: (cb) =>
        client.subscribe(IPC.stationOutcomeChanged, ((records: unknown) =>
          cb(sanitizeOutcomeRecords(records))) as Listener)
    }
  }
}

/**
 * Build the top-level agent-event subscriptions (`onAgentStatus` / `onSubagentActivity`) over an
 * RpcClient. These mirror the preload's `.on(channel, …)` → `client.subscribe(channel, …)` split:
 * each takes a listener and returns an unsubscribe. Declared against its `NodeTerminalApi` slice so
 * `satisfies` keeps the compiler as the completeness gate.
 */
export function buildAgentApi(
  client: RpcClient
): Pick<
  NodeTerminalApi,
  | 'onAgentStatus'
  | 'agentStatusSnapshot'
  | 'onSubagentActivity'
  | 'onUnreadClear'
  | 'answerPermission'
  | 'ackDone'
  | 'reportHibernated'
  | 'seedAgentIdentity'
  | 'onAgentWake'
  | 'onRemoteViewers'
  | 'onAgentRefreshNode'
  | 'onAgentRenameNode'
> {
  return {
    onAgentStatus: (listener) => subscribeAgentReplay(
      (cb) => client.subscribe(IPC.agentStatus, cb as Listener),
      () => client.request(IPC.agentSubagentSnapshot) as Promise<NormalizedAgentEvent[]>, listener
    ),
    // REAL request: the core's mirror answers it, so a browser tab (and, through relay-api's spread,
    // a relay tab, whose host narrows it for a non-editor) starts from the states the host holds.
    agentStatusSnapshot: () => client.request(IPC.agentStatusSnapshot) as Promise<AgentStatusSnapshotEntry[]>,
    // REAL forward: the Server Edition writes its own agent-status mirror, and the phone reads it
    // over its SSH browse path — a browser canvas hibernating a node must reach that file too.
    reportHibernated: (nodeId, on) => {
      void client.request(IPC.agentHibernated, { nodeId, on }).catch(() => undefined)
    },
    // REAL forward, same reason: the server's mirror is what a phone browsing that host reads.
    seedAgentIdentity: (entries) => {
      void client.request(IPC.agentSeedIdentity, entries).catch(() => undefined)
    },
    // Deliberate no-op subscriptions, not stubs-by-accident: both signals originate in the phone
    // RELAY host, which lives only in the desktop main process — the Server Edition serves no
    // relay, so there is nothing to subscribe to and nothing silently degrades.
    onAgentWake: () => () => undefined,
    onRemoteViewers: () => () => undefined,
    onAgentRefreshNode: () => () => undefined,
    onAgentRenameNode: () => () => undefined,
    // Host swept a phone read-ack → drop this browser canvas's unread flag (external clear, no re-ack).
    onUnreadClear: (listener) => client.subscribe(IPC.agentUnreadClear, listener as Listener),
    onSubagentActivity: (listener) =>
      client.subscribe(IPC.agentSubagentActivity, listener as Listener),
    // Deterministic hook-reply approvals: a real request over the bridge — the Server Edition runs
    // ON the host, so a local project's answer file is written right there (SSH-from-server is v1
    // unsupported and the handler returns false). See docs/hook-reply-approvals.md.
    answerPermission: (payload) =>
      client.request(IPC.agentAnswerPermission, payload) as Promise<boolean>,
    // Read-a-finished-session ack: a real fire-and-forget request over the bridge — the browser
    // canvas runs ON the host, so the server's mirror acks the done event + re-sends the 'end'
    // live-update to the paired phone, same as desktop. See agent-status-mirror `ackDone`.
    ackDone: (nodeId) => {
      void client.request(IPC.agentAckDone, nodeId)
    }
  }
}

/**
 * Build the `canvas` namespace over an RpcClient: a cast out (`canvas:mut`) and a subscription in on
 * the same channel. The server stamps each mutation with the total order (`seq`) and reflects it to
 * every client, us included — our own frame coming back is the ACK that carries our place in that
 * order (the renderer recognizes it by `src`; see src/shared/canvas-order.ts). This is a REAL
 * implementation, not a stub:
 * the Server Edition (two browsers on one workspace) is the surface that needs canvas sync most.
 */
export function buildCanvasApi(client: RpcClient): Pick<NodeTerminalApi, 'canvas'> {
  return {
    canvas: {
      mutate: (projectId, mutation) => client.cast(IPC.canvasMut, projectId, mutation),
      onMutation: (listener) => client.subscribe(IPC.canvasMut, listener as Listener)
    }
  }
}

/**
 * Build the `canvasAuthority` namespace over an RpcClient: a REAL implementation for the Server
 * Edition browser, whose core may run the canvas authority (docs/hosted-team-relay.md). A server
 * that does not answer (an older one, a failure) governs nothing, so the tab keeps the solo gate
 * rather than rejecting. Deliberately NOT part of `buildCanvasApi`, which the relay tab shares: a
 * relay tab answers from its own connection (relay-api.ts) and never asks the host over the wire.
 */
export function buildCanvasAuthorityApi(client: RpcClient): Pick<NodeTerminalApi, 'canvasAuthority'> {
  const ids = (v: unknown): string[] =>
    Array.isArray(v) ? v.filter((x): x is string => typeof x === 'string') : []
  return {
    canvasAuthority: {
      // A Server Edition core governs the projects its hosted team shares, and says which only when
      // asked: until it answers, a client publishes for every project (collab-sync `followGoverned`).
      assumeAllUntilAnswered: true,
      governed: () => client.request(IPC.canvasAuthority).then(ids, () => []),
      onChanged: (listener) => client.subscribe(IPC.canvasAuthorityChanged, ((v: unknown) => listener(ids(v))) as Listener)
    }
  }
}

/**
 * Build the `presence` namespace over an RpcClient, mirroring the preload's invoke(→request) /
 * send(→cast) / on(→subscribe) split member-for-member: `hello` is the only request (its response
 * is how a client learns its OWN clientId), cursor/focus/chat/project are casts, and the two event
 * channels are subscriptions. Declared against its `NodeTerminalApi` slice so `satisfies` keeps
 * the compiler as the completeness gate.
 */
export function buildPresenceApi(client: RpcClient): Pick<NodeTerminalApi, 'presence'> {
  const presence: PresenceApi = {
    hello: (identity: PeerIdentity) =>
      client.request(IPC.presenceHello, identity) as ReturnType<PresenceApi['hello']>,
    cursor: (cursor) => client.cast(IPC.presenceCursor, cursor),
    focus: (nodeId) => client.cast(IPC.presenceFocus, nodeId),
    chat: (text) => client.cast(IPC.presenceChat, text),
    dino: (payload) => client.cast(IPC.presenceDino, payload),
    project: (projectId) => client.cast(IPC.presenceProject, projectId),
    onSync: (listener) => client.subscribe(IPC.presenceSync, listener as Listener),
    onPeer: (listener) => client.subscribe(IPC.presencePeer, listener as Listener)
  }
  return { presence }
}

/**
 * Build the hosted-team verbs of ONE relay session (`NodeTerminalApi.hosted`). Only a relay tab
 * joined by a `nodeterm://join` code spreads this (relay-api.ts, `{ hosted: true }`): a Server
 * Edition browser never joins a relay host, and a Team Access relay tab (desktop to desktop) talks
 * to a host that answers none of these, so both leave `hosted` absent. The host core answers every
 * request itself (src/core/relay/hosted-service.ts) and judges the caller's role: `self` is open to
 * any member, the rest are owner-only. `peer-pending` / `pending-closed` reach connected OWNERS only;
 * `shared-changed` (the team's whole shared set) reaches every connected member, viewers included.
 */
export function buildHostedApi(client: RpcClient): Required<Pick<NodeTerminalApi, 'hosted'>> {
  const hosted: HostedSessionApi = {
    self: () => client.request(IPC.relayHostedSelf) as Promise<HostedSelf>,
    pending: () => client.request(IPC.relayHostedPending) as Promise<HostedPending[]>,
    inviteCode: () => client.request(IPC.relayHostedInviteCode) as Promise<string | null>,
    approve: (pendingId, role) => client.request(IPC.relayHostedApprove, pendingId, role) as Promise<boolean>,
    deny: (pendingId) => client.request(IPC.relayHostedDeny, pendingId) as Promise<boolean>,
    onPeerPending: (listener) => client.subscribe(IPC.relayHostedPeerPending, listener as Listener),
    onPendingClosed: (listener) => client.subscribe(IPC.relayHostedPendingClosed, listener as Listener),
    onSharedChanged: (listener) => client.subscribe(IPC.relayHostedSharedChanged, listener as Listener)
  }
  return { hosted }
}

/**
 * Build the `speech` namespace over an RpcClient — a REAL implementation (the server registers
 * `registerSpeechIpc` too; see `src/core/speech/register-ipc.ts`), not a stub. The one wire
 * difference from Electron IPC: `decodePcmPayload` (src/core/speech/pcm.ts) accepts EITHER a raw
 * Float32 ArrayBuffer (what the preload sends over structured-clone IPC) OR a base64 string of
 * little-endian Int16 samples (half the bytes over JSON) — this is the string branch, encoded by
 * the pure `encodePcmForWire` helper. `micConsent` resolves `true` locally: the browser's own
 * `getUserMedia` prompt IS the consent gate, so there is nothing for the server to answer (the
 * server-side handler for this channel is stubbed the same way — see src/server/index.ts).
 */
export function buildSpeechApi(client: RpcClient): Pick<NodeTerminalApi, 'speech'> {
  const speech: SpeechApi = {
    transcribe: (pcm, language) =>
      client.request(IPC.speechTranscribe, { pcm: encodePcmForWire(pcm), language }) as Promise<{
        text: string
      }>,
    models: () => client.request(IPC.speechModels) as Promise<SpeechModelInfo[]>,
    downloadModel: (id) => client.request(IPC.speechModelDownload, { id }) as Promise<void>,
    deleteModel: (id) => client.request(IPC.speechModelDelete, { id }) as Promise<void>,
    onProgress: (cb) => client.subscribe(IPC.speechProgress, cb as Listener),
    micConsent: () => Promise.resolve(true)
    // `openMicSettings` is deliberately ABSENT: a browser's mic permission is its own site
    // setting, and the dictation overlay hides its "Open microphone settings" button without it.
  }
  return { speech }
}

/**
 * Build the `usage` namespace over an RpcClient. The server shell runs the same core usage
 * service the desktop does, so this is real end to end — including `onUpdate`, which subscribes
 * to the poll's broadcast rather than the stub's no-op.
 *
 * `fetch` deliberately does NOT catch: `UsageApi.fetch` is typed as `Promise<ClaudeUsage>`, so
 * swallowing a transport failure would mean inventing a snapshot. The one consumer
 * (UsageIndicator) leaves `usage` null until a real one arrives and renders nothing meanwhile,
 * which is the correct outcome for "we don't know".
 */
function buildUsageApi(client: RpcClient): Pick<NodeTerminalApi, 'usage'> {
  return {
    usage: {
      fetch: (accountId?: string) =>
        client.request(IPC.usageFetch, accountId) as Promise<ClaudeUsage>,
      refresh: (accountId?: string) =>
        client.request(IPC.usageRefresh, accountId) as Promise<ClaudeUsage>,
      providers: (force?: boolean) =>
        client.request(IPC.usageProviders, force) as Promise<ProviderUsage[]>,
      // Real, but structurally empty on the server: `usage:remote` is registered by the same core
      // service, and the server shell injects no SSH deps (it has no SSH projects), so it answers
      // `[]` rather than rejecting.
      remote: (query?: RemoteUsageQuery) =>
        client.request(IPC.usageRemote, query) as Promise<RemoteAccountUsage[]>,
      setProviderCookie: (provider: string, cookie: string) =>
        client.request(IPC.usageSetProviderCookie, provider, cookie) as Promise<boolean>,
      cookieProviders: () =>
        client.request(IPC.usageCookieProviders) as Promise<Record<string, boolean>>,
      onUpdate: (listener) => client.subscribe(IPC.usageUpdate, listener as Listener)
    }
  }
}

/**
 * Real, not a stub: the same core service (`startSessionMemoryService`) registers these channels in
 * the server shell, so the browser gets a genuine per-session breakdown of the machine it is served
 * from — the one it is actually looking at.
 *
 * The query is forwarded VERBATIM. `remote` is the renderer's own "this scope is an SSH host"
 * claim and is one of TWO independent sources the service ORs to decide which machine answers;
 * `projectId` is the only thing naming that machine. A layer that drops or rewrites either turns a
 * remote query into a local sweep, and this machine's sessions get published under the host's name.
 *
 * Neither member catches: a transport failure must not be laundered into `{ok:false}` / `null`,
 * which are the service's own words for "the sweep could not run" and "RAM unreadable". The panel
 * shows a failed request as a failed request.
 */
/**
 * The `triggers` namespace over an RpcClient — REAL on the Server Edition: the arm store, the
 * scheduler and the delivery all run in the server shell (`startTriggerService` registers these
 * handlers there exactly as desktop main does), so arming a trigger from the browser arms it on
 * the machine that will fire it. The relay deliberately keeps the refusing stub (stubs.ts):
 * another machine's arm store is not the guest's to write.
 */
export function buildTriggersApi(client: RpcClient): Pick<NodeTerminalApi, 'triggers'> {
  return {
    triggers: {
      arm: (projectId, nodeId, spec) =>
        client.request(IPC.triggersArm, { projectId, nodeId, spec }) as Promise<boolean>,
      disarm: (projectId, nodeId) =>
        client.request(IPC.triggersDisarm, { projectId, nodeId }) as Promise<void>,
      status: (projectId, nodeId) =>
        client.request(IPC.triggersStatus, { projectId, nodeId }) as Promise<
          import('@shared/trigger').TriggerNodeStatus
        >,
      runNow: (projectId, nodeId) =>
        client.request(IPC.triggersRunNow, { projectId, nodeId }) as Promise<{
          outcome: 'fired' | 'missed' | 'failed' | 'queued'
          detail?: string
        }>
    }
  }
}

export function buildSessionMemoryApi(client: RpcClient): Pick<NodeTerminalApi, 'sessionMemory'> {
  return {
    sessionMemory: {
      read: (q?: SessionMemoryQuery) =>
        client.request(IPC.sessionMemory, q) as Promise<SessionMemoryReport>,
      host: (q?: SessionMemoryQuery) =>
        client.request(IPC.sessionMemoryHost, q) as Promise<MemInfo | null>
    }
  }
}

/** The server lists ITS OWN host's history — the machine the browser's sessions run on. A failed
 *  request is `{ok:false}`, never an empty list. */
export function buildRecentConversationsApi(client: RpcClient): Pick<NodeTerminalApi, 'recentConversations'> {
  return {
    recentConversations: {
      list: (req?: RecentConversationsRequest) =>
        (client.request(IPC.recentConversationsList, req) as Promise<RecentConversationsResult>).catch(
          () => ({ ok: false as const, reason: 'failed' as const })
        )
    }
  }
}

export function buildWallpaperApi(client: RpcClient): Pick<NodeTerminalApi, 'wallpaper'> {
  return {
    wallpaper: {
      listStills: () => client.request(IPC.wallpaperListStills) as Promise<WallpaperStill[]>,
      load: (w: DesktopWallpaper) => client.request(IPC.wallpaperLoad, w) as Promise<string | null>,
      importImage: (p: string) => client.request(IPC.wallpaperImport, p) as Promise<DesktopWallpaper>,
      listAerials: () => client.request(IPC.wallpaperListAerials) as Promise<WallpaperStill[]>,
      aerialClips: (w: DesktopWallpaper) => client.request(IPC.wallpaperAerialClips, w) as Promise<string[]>
    }
  }
}

/** The run node's host side. Real on the Server Edition (`registerRunConfigIpc` runs in the
 *  server shell): the run happens on the server, so its launch.json, devices and processes are the
 *  server's — which is the machine the node's terminal runs on. */
export function buildRunConfigApi(client: RpcClient): Pick<NodeTerminalApi, 'runConfig'> {
  const r: RunConfigApi = {
    entries: (dir) => client.request(IPC.runEntries, dir) as Promise<RunEntriesResult>,
    devices: (refresh) => client.request(IPC.runDevices, refresh) as Promise<RunDevicesResult>,
    bootDevice: (udid) => client.request(IPC.runBootDevice, udid) as Promise<boolean>,
    discoverProjects: (dir) => client.request(IPC.runDiscover, dir) as Promise<string[]>,
    start: (nodeId, config, opts) => client.request(IPC.runStart, nodeId, config, opts) as Promise<RunStartResult>,
    status: (nodeId) => client.request(IPC.runStatus, nodeId) as Promise<RunStatus>,
    stop: (nodeId, force) => client.request(IPC.runStop, nodeId, force) as Promise<boolean>,
    signal: (nodeId, kind) => client.request(IPC.runSignal, nodeId, kind) as Promise<boolean>,
    watch: (nodeId, dir) => client.request(IPC.runWatch, nodeId, dir) as Promise<void>
  }
  return { runConfig: r }
}

/**
 * Build the `claude` namespace over an RpcClient. `cliCaps` is a REAL handler on the server
 * (`registerClaudeCliIpc` runs in the server shell too), so the browser resolves the very same
 * `--permission-mode auto` version gate as desktop instead of silently no-opping into "auto
 * unsupported" — which would strip the flag from every Claude launch in the Server Edition.
 * A failed request degrades to the fail-open caps (bare command), never a rejection: the launch
 * path awaits this.
 *
 * `readTranscript` stays STUBBED here on purpose. This builder is shared with the relay
 * (`relay-api.ts`), where the transcripts that matter live on the HOST while this namespace's
 * only real member is a capability probe — the Server Edition gets the real reader from
 * `buildTranscriptApi` below instead, which the relay does not use.
 */
/**
 * The `codex` namespace over an RpcClient — a REAL implementation, not a stub, because the answer
 * has to come from the machine the pty runs on. Today the Server Edition's handler deliberately
 * answers `{ shared: false }` (see server/handlers/index.ts); wiring that side later needs nothing
 * here. A failed request degrades to the same conservative answer: the launch path reads it.
 */
export function buildCodexApi(client: RpcClient): CodexApi {
  return {
    identityCaps: () =>
      (client.request(IPC.codexIdentityCaps) as Promise<CodexIdentityCaps>).catch(
        () => UNKNOWN_CODEX_IDENTITY_CAPS
      ),
    // A REAL handler server-side, unlike `identityCaps` right above it — `registerCodexCliIpc`
    // runs in that shell for the reason spelled out there: the Server Edition's Codex sessions run
    // on the server's own `codex`, so the browser needs that binary's real approval vocabulary.
    // Rejection degrades to the unknown caps, i.e. the baseline vocabulary.
    cliCaps: () =>
      (client.request(IPC.codexCliCaps) as Promise<CodexCliCaps>).catch(
        () => UNKNOWN_CODEX_CLI_CAPS
      ),
    onIdentity: (listener) => client.subscribe(IPC.codexIdentity, listener as Listener)
  }
}

export function buildClaudeApi(client: RpcClient, stub: ClaudeApi): ClaudeApi {
  return {
    ...stub,
    cliCaps: () =>
      (client.request(IPC.claudeCliCaps) as Promise<ClaudeCliCaps>).catch(
        () => UNKNOWN_CLAUDE_CLI_CAPS
      )
  }
}

/** grok's probe over WS-RPC. A REAL handler server-side (`registerGrokCliIpc` runs in that shell
 *  too), so the browser gets the same answer the desktop does — not a stub that quietly disables
 *  session-id minting on one surface only. Rejection degrades to the fail-open caps. */
export function buildGrokApi(client: RpcClient): GrokApi {
  return {
    cliCaps: () =>
      (client.request(IPC.grokCliCaps) as Promise<GrokCliCaps>).catch(() => UNKNOWN_GROK_CLI_CAPS),
    takenSessionIds: (cwd: string) =>
      (client.request(IPC.grokTakenSessionIds, cwd) as Promise<string[]>).catch(() => [])
  }
}

/** cursor's model catalogue over WS-RPC: a REAL handler server-side (`registerCursorCliIpc`). */
export function buildCursorApi(client: RpcClient): CursorApi {
  return {
    cliCaps: () =>
      (client.request(IPC.cursorCliCaps) as Promise<CursorCliCaps>).catch(
        () => UNKNOWN_CURSOR_CLI_CAPS
      )
  }
}

/**
 * The two transcript READ channels, now that `registerTranscriptIpc` serves them in the server
 * shell too. Before this the browser had no handler at all: the stub rejected, the ⌘M panel never
 * caught it, and every Server Edition session read as an empty conversation.
 *
 * Server Edition ONLY (see buildClaudeApi's note): the server runs on the machine whose
 * transcripts these are, so no `nodeId` remote leg is needed — the argument still rides along
 * because the channel is shared with desktop.
 */
export function buildTranscriptApi(
  client: RpcClient
): Pick<NodeTerminalApi, 'chat'> & { claudeReadTranscript: ClaudeApi['readTranscript'] } {
  return {
    chat: {
      // `page` rides through untouched: the server validates it (`normalizeChatPage`) — the
      // browser is the untrusted side of this wire, so checking it here would prove nothing.
      readTranscript: (sessionId, cwd, accountId, nodeId, agentId, page) =>
        client.request(
          IPC.chatReadTranscript,
          sessionId,
          cwd,
          accountId,
          nodeId,
          agentId,
          page
        ) as Promise<ChatTranscriptResult>,
      // A REAL implementation, not a stub: the server runs on the machine holding these
      // transcripts, so its answer is as good as the desktop's local leg. A failed request
      // degrades to `unknown` (never `absent`) — cold restore acts on a negative, so the wrong
      // degrade would drop a live conversation's `--resume` because a socket blipped.
      transcriptExists: (sessionId, accountId, nodeId) =>
        (
          client.request(
            IPC.transcriptExists,
            sessionId,
            accountId,
            nodeId
          ) as Promise<TranscriptPresence>
        ).catch(() => 'unknown' as const),
      // REAL: the server registers `registerChatCatalogIpc` and runs on the machine whose command
      // and skill folders these are. The reply is re-checked in the composer (sanitizeChatCatalog).
      catalog: (nodeId, agentId, accountId, cwd) =>
        client.request(IPC.chatCatalog, nodeId, agentId, accountId, cwd) as Promise<ChatCatalog>
    },
    claudeReadTranscript: (sessionId, cwd, accountId, nodeId) =>
      client.request(
        IPC.claudeReadTranscript,
        sessionId,
        cwd,
        accountId,
        nodeId
      ) as Promise<TranscriptLine[]>
  }
}

/**
 * Managed CLAUDE accounts over the WS bridge (issue #313). REAL, not a stub: the lifecycle moved
 * into `src/core/claude-accounts-service.ts`, so the server registers the same four channels the
 * desktop does and the browser can create, log into and remove accounts. Deliberately NOT added to
 * `relay-api.ts` — a relay tab drives someone else's machine, and minting an account there would
 * create it on the HOST while this renderer's settings.json records it as one of its own.
 *
 * `waitLogin` is a straight passthrough of a poll that runs up to 5 minutes. That is safe because
 * RpcClient has no request timeout: a pending request rejects only when the socket drops, which is
 * exactly the outcome the caller wants (the login row stays pending and offers Retry).
 *
 * The `codexAccounts` namespace stays STUBBED (E_UNSUPPORTED). Its switch verbs authorize the
 * owning window by Electron WebContents id, which has no meaning over a WS connection — porting it
 * needs a connection-identity design, not a builder.
 */
export function buildClaudeAccountsApi(client: RpcClient): Pick<NodeTerminalApi, 'claudeAccounts'> {
  return {
    claudeAccounts: {
      add: (ctx) =>
        client.request(IPC.claudeAccountsAdd, ctx) as Promise<{
          id: string
          configDir: string
          versionSupported: boolean
        }>,
      waitLogin: (id, ctx) =>
        client.request(IPC.claudeAccountsWaitLogin, id, ctx) as Promise<{ email: string } | null>,
      cancelWaitLogin: (id) =>
        client.request(IPC.claudeAccountsCancelWait, id) as Promise<void>,
      remove: (id, ctx) => client.request(IPC.claudeAccountsRemove, id, ctx) as Promise<void>,
      link: (configDir) =>
        client.request(IPC.claudeAccountsLink, configDir) as Promise<{
          id: string
          configDir: string
          email: string | null
        }>,
      // Real, not a stub: the whole implementation is core, so the machine the browser is served
      // FROM is exactly the machine whose `~/.claude/skills` the option shares (issue #643).
      setSkillSharing: (id, enabled) =>
        client.request(
          IPC.claudeAccountsSetSkillSharing,
          id,
          enabled
        ) as Promise<ClaudeSkillShareResult>,
      // Real: the copy is core, on the machine the browser is served from — the same machine whose
      // account dirs the Server Edition's panes run under.
      // An SSH ctx is forwarded as-is: the server registers no SSH leg, so core refuses it
      // (`failed`) instead of copying on the server's own disk.
      copySession: (sessionId, sourceAccountId, targetAccountId, ctx) =>
        client.request(
          IPC.claudeAccountsCopySession,
          sessionId,
          sourceAccountId,
          targetAccountId,
          ctx
        ) as Promise<ClaudeSessionCopyResult>
    }
  }
}

/** WS URL for the current page: same host, `/ws`, ws→http / wss→https. */
function wsUrl(): string {
  const scheme = location.protocol === 'https:' ? 'wss' : 'ws'
  return `${scheme}://${location.host}/ws`
}

// ── Reconnect overlay (kept out of RpcClient's unit-tested core) ────────────────────────────
const OVERLAY_ID = 'nt-reconnect-overlay'

/** Is the reconnect overlay currently mounted? Exported for the unit test. */
export function isOverlayMounted(): boolean {
  return typeof document !== 'undefined' && document.getElementById(OVERLAY_ID) !== null
}

/** Mount the full-screen "reconnecting" overlay (idempotent). Exported so both the initial-connect
 *  failure path and the later onClose path — and the unit test — mount the identical UI. */
export function showReconnectOverlay(): void {
  if (typeof document === 'undefined' || document.getElementById(OVERLAY_ID)) return
  const el = document.createElement('div')
  el.id = OVERLAY_ID
  el.setAttribute('data-nt-reconnect', '')
  el.style.cssText =
    'position:fixed;inset:0;z-index:2147483647;display:flex;align-items:center;' +
    'justify-content:center;background:rgba(0,0,0,0.72);color:#fff;' +
    'font:15px -apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;text-align:center;padding:24px'
  el.textContent = 'Connection lost — reconnecting…'
  document.body.appendChild(el)
}

/** Retry the WS with backoff (1s→2s→4s→…→10s cap). On the first successful reopen, reload the
 *  page (the reloaded app re-runs `pty.create` per node with the same persistKey → tmux warm
 *  reattach). After 3 consecutive failed retries, bounce to `/login` (assume auth expired). */
function startReconnect(): void {
  showReconnectOverlay()
  let attempt = 0
  let failures = 0

  const tryOnce = (): void => {
    let probe: WebSocket
    try {
      probe = new WebSocket(wsUrl())
    } catch {
      scheduleRetry()
      return
    }
    probe.binaryType = 'arraybuffer'
    const cleanup = (): void => {
      probe.onopen = null
      probe.onerror = null
      probe.onclose = null
    }
    probe.onopen = () => {
      cleanup()
      try {
        probe.close()
      } catch {
        /* ignore */
      }
      location.reload()
    }
    probe.onerror = () => {
      // Let onclose drive the retry/failure counting (fires after error).
    }
    probe.onclose = () => {
      cleanup()
      failures++
      if (failures >= 3) {
        location.href = '/login'
        return
      }
      scheduleRetry()
    }
  }

  const scheduleRetry = (): void => {
    const delay = Math.min(1000 * 2 ** attempt, 10000)
    attempt++
    setTimeout(tryOnce, delay)
  }

  scheduleRetry()
}

/**
 * Connect the WS bridge and install `window.nodeTerminal`. Awaited by main.tsx's bootstrap
 * before the app boots, so the real namespaces are present on first render. Resolves `true` once
 * the socket is open and `window.nodeTerminal` is assigned; resolves `false` on the initial-connect
 * failure path (overlay shown, reconnect loop running) so bootstrap can skip loading the app.
 */
export async function installWsBridge(): Promise<boolean> {
  const client = new RpcClient(new WebSocketFrameTransport(wsUrl()))
  try {
    await client.ready()
  } catch {
    // First connection failed (server down at page load, or the socket errored before opening).
    // Show the SAME reconnect overlay + backoff loop as a later drop instead of rejecting — a
    // rejection here would bubble out of bootstrap() and leave a blank screen. `startReconnect`
    // reloads the page on the first successful reopen, which re-runs installWsBridge cleanly.
    // Return false so bootstrap skips `import('./boot')` — booting the app with an undefined
    // `window.nodeTerminal` throws under the (opaque) overlay.
    startReconnect()
    return false
  }
  client.onClose(() => startReconnect())
  const stubApi = buildStubApi()
  const api: NodeTerminalApi = {
    ...stubApi,
    ...buildRealApi(client),
    ...buildFilesApi(client),
    ...buildAgentApi(client),
    ...buildStationNoticeApi(client),
    ...buildStationOutcomeApi(client),
    ...buildStationHandoverApi(client),
    ...buildCanvasApi(client),
    ...buildCanvasAuthorityApi(client),
    ...buildPresenceApi(client),
    ...buildSpeechApi(client),
    ...buildUsageApi(client),
    ...buildSessionMemoryApi(client),
    ...buildRecentConversationsApi(client),
    ...buildWallpaperApi(client),
    ...buildRunConfigApi(client),
    ...buildTriggersApi(client),
    ...buildGitHubApi(client),
    ...buildClaudeAccountsApi(client),
    codex: buildCodexApi(client),
    // `claude` is assembled from two builders: `cliCaps` from the relay-shared one, and the
    // transcript reader from the Server-Edition-only one (which also supplies `chat`).
    ...(() => {
      const t = buildTranscriptApi(client)
      return {
        chat: t.chat,
        claude: { ...buildClaudeApi(client, stubApi.claude), readTranscript: t.claudeReadTranscript },
        grok: buildGrokApi(client),
        cursor: buildCursorApi(client)
      }
    })(),
    // Web replacement for the Electron native dialog: an in-app server-directory browser over
    // fs.list (the stub's E_UNSUPPORTED reject is dropped in favor of this real picker).
    dialog: (() => {
      mountPickerRoot()
      const startDir = '/' // navigable up/down from root; the picker remembers nothing across calls in v1
      // `write` is what gives folder mode its "New folder" button — the native dialog has one and
      // the browser has no dialog at all, so without it a server folder had to exist already
      // before it could be opened as a project. Same `fs.mkdir`/`fs.exists` the Explorer writes
      // through, and therefore the same reach as everything else this picker already lists.
      // Lambdas, not `api.fs.mkdir` directly: this IIFE runs while `api` is still being built.
      const write = {
        mkdir: (p: string) => api.fs.mkdir(p),
        exists: (p: string) => api.fs.exists(p)
      }
      return {
        selectFolder: () =>
          openDirectoryPicker({ mode: 'folder', startDir, list: api.fs.list, write }),
        selectFile: () => openDirectoryPicker({ mode: 'file', startDir, list: api.fs.list })
      }
    })()
  }
  ;(window as unknown as { nodeTerminal: NodeTerminalApi }).nodeTerminal = api
  return true
}