@xingular/harness 2.0.0 → 2.0.1-unstable

package/src/terminal/socket.ts

@@ -1,256 +0,0 @@
-// The session socket: how a process the harness did not start in-process (the `pi` command in
-// a terminal, with its extension and the `xagent-wiki` / `xagent-mcp` commands) reaches the
-// session it belongs to. Owner-only Unix socket (a named pipe on Windows), newline-delimited JSON,
-// one request per connection. Each terminal session holds a random token bound to its caller, its
-// connected-apps grant, and its controller; the token stops working when the terminal ends.
-import { createHash, randomBytes } from 'node:crypto'
-import { chmodSync, mkdirSync, rmSync, statSync } from 'node:fs'
-import { createServer, type Server, type Socket } from 'node:net'
-import { tmpdir } from 'node:os'
-import { dirname, join } from 'node:path'
-
-import { log } from '../core/bus'
-import { HarnessError, toErrorShape } from '../core/errors'
-import { newId } from '../core/fs'
-import type { BrokerSession } from '../mcp/service'
-import type { CallerContext } from '../memory/caller'
-
-/** What a token stands for. */
-export interface SocketGrant {
-  sessionId: string
-  /** Who memory, Wiki, and recall calls are made as. The run is filled in while a turn is live. */
-  caller: () => CallerContext
-  /** The session's connected-apps grant, when it has one. */
-  broker: BrokerSession | null
-  /** Telemetry from the native process, and what to do when it hangs up mid-request. */
-  terminal?: { accept(event: string, data: Record<string, unknown>): Promise<unknown>; disconnected(): void; control?(call: string, data: Record<string, unknown>): unknown }
-}
-
-export interface SocketHandlers {
-  /** `wiki.*`, `memory.*`, `recall.*`. */
-  memory(caller: CallerContext, call: string, params: Record<string, unknown>): string
-  /** `mcp.list`, `mcp.call`, `mcp.revision`, `tools.list`, `tools.call`. */
-  apps(session: BrokerSession, call: string, params: Record<string, unknown>): Promise<unknown>
-  /**
-   * `plugins.*`. `control` is true only for the session's own extension, which holds a key the
-   * session's shell never sees; anything that changes what loads needs it.
-   */
-  plugins?(grant: SocketGrant, call: string, params: Record<string, unknown>, control: boolean): Promise<unknown>
-  /** `accounts.*`. Every call needs `control`: adding, signing in, or removing an account is a person's choice. */
-  accounts?(grant: SocketGrant, call: string, params: Record<string, unknown>, control: boolean): Promise<unknown>
-}
-
-const MAX_REQUEST_BYTES = 1024 * 1024
-/** macOS refuses a socket path longer than 103 bytes. */
-const MAX_SOCKET_PATH = 100
-
-/**
- * Windows has no socket files for Node's `net`: it listens on a named pipe, which lives in a
- * machine-wide namespace. A random name keeps another local process from guessing it and standing
- * in front of the session; the token still decides what a caller may do.
- */
-export function socketPath(stateDir: string): string {
-  if (process.platform === 'win32') return `\\\\.\\pipe\\xingular-harness-${randomBytes(12).toString('hex')}`
-  const path = join(stateDir, 'run', 'harness.sock')
-  if (Buffer.byteLength(path) <= MAX_SOCKET_PATH) return path
-  return join(tmpdir(), `xh-${createHash('sha256').update(path).digest('hex').slice(0, 16)}.sock`)
-}
-
-function alternateSocketPath(path: string): string {
-  const candidate = join(dirname(path), `harness-${process.pid}-${randomBytes(8).toString('hex')}.sock`)
-  return Buffer.byteLength(candidate) <= MAX_SOCKET_PATH ? candidate : join(tmpdir(), `xh-${randomBytes(16).toString('hex')}.sock`)
-}
-
-/** A named pipe has no folder, file mode, or owner to check or clean up. */
-const isPipePath = (path: string): boolean => path.startsWith('\\\\.\\pipe\\')
-
-/** Names the folder and the user when the operating system refuses the socket, so the cause shows. */
-function refusedBind(path: string, error: unknown): unknown {
-  const code = (error as { code?: unknown } | null)?.code
-  if (code !== 'EACCES' && code !== 'EPERM') return error
-  if (isPipePath(path)) {
-    return new HarnessError(
-      'session_socket_denied',
-      `The session pipe ${path} could not be created (${code}).`,
-      'Start the harness again from your own user session. If it keeps failing, report this code and the Windows version.'
-    )
-  }
-  let folder: string
-  try {
-    const stat = statSync(dirname(path))
-    folder = `${dirname(path)} is owned by uid ${stat.uid} with mode ${(stat.mode & 0o777).toString(8)}`
-  } catch {
-    folder = `${dirname(path)} could not be read`
-  }
-  const uid = process.getuid?.() ?? 'unknown'
-  return new HarnessError(
-    'session_socket_denied',
-    `The session socket ${path} could not be created (${code}). ${folder}; this process runs as uid ${uid}.`,
-    'Run the harness from your own terminal, as the user that owns its state folder, or choose a state folder you own with --state.'
-  )
-}
-
-export class SessionSocket {
-  private server: Server | null = null
-  private listening: Promise<void> | null = null
-  private socketPathValue: string
-  private readonly grants = new Map<string, SocketGrant>()
-  /**
-   * A second key per token, handed out once. The token is in the session's environment, where a
-   * command the model runs can read it; this key is claimed by the session's extension as it
-   * loads, before any model turn, and kept in its memory only.
-   */
-  private readonly controls = new Map<string, string>()
-  private readonly clients = new Set<Socket>()
-
-  constructor(path: string, private readonly handlers: SocketHandlers) {
-    this.socketPathValue = path
-  }
-
-  get path(): string { return this.socketPathValue }
-
-  issue(grant: SocketGrant): string {
-    const token = `${newId()}${newId()}`.replaceAll('-', '')
-    this.grants.set(token, grant)
-    return token
-  }
-
-  revoke(token: string): void {
-    this.grants.delete(token)
-    this.controls.delete(token)
-  }
-
-  revokeSession(sessionId: string): void {
-    for (const [token, grant] of this.grants) if (grant.sessionId === sessionId) this.revoke(token)
-  }
-
-  /** Runs one request line and returns the reply line's object. */
-  async handle(line: string, connection?: { waiting: (grant: SocketGrant | null) => void }): Promise<{ result: unknown } | { error: unknown }> {
-    try {
-      let request: Record<string, unknown>
-      try {
-        request = JSON.parse(line) as Record<string, unknown>
-      } catch {
-        throw new HarnessError('invalid_request', 'The request is not JSON.')
-      }
-      const token = typeof request.token === 'string' ? request.token : ''
-      const grant = this.grants.get(token)
-      if (!grant) throw new HarnessError('unauthorized', 'This session token is not valid. It ends when its terminal session ends.')
-      if (typeof request.event === 'string') {
-        if (!grant.terminal) throw new HarnessError('unknown_method', 'This session has no terminal controller.')
-        connection?.waiting(grant)
-        try {
-          return { result: (await grant.terminal.accept(request.event, (request.data ?? {}) as Record<string, unknown>)) ?? {} }
-        } finally {
-          connection?.waiting(null)
-        }
-      }
-      const call = typeof request.call === 'string' ? request.call : ''
-      const params = (request.params && typeof request.params === 'object' ? request.params : {}) as Record<string, unknown>
-      if (['wiki.', 'memory.', 'recall.'].some((prefix) => call.startsWith(prefix))) return { result: this.handlers.memory(grant.caller(), call, params) }
-      if (call === 'tools.list' && !grant.broker) return { result: { tools: [] } }
-      if (['mcp.', 'tools.'].some((prefix) => call.startsWith(prefix))) {
-        if (!grant.broker) throw new HarnessError('mcp_unauthorized', 'Connected apps are not available to this session.')
-        return { result: await this.handlers.apps(grant.broker, call, params) }
-      }
-      if (call === 'control.claim') {
-        if (this.controls.has(token)) throw new HarnessError('unauthorized', "This session's control key was already claimed.")
-        const key = `${newId()}${newId()}`.replaceAll('-', '')
-        this.controls.set(token, key)
-        return { result: { key } }
-      }
-      if (call.startsWith('terminal.') && grant.terminal?.control) {
-        const key = this.controls.get(token)
-        if (!key || request.control !== key) throw new HarnessError('unauthorized', 'Only a person at this terminal can answer decisions or change its draft state.')
-        return { result: await grant.terminal.control(call, params) }
-      }
-      if ((call.startsWith('plugins.') || call.startsWith('hub.')) && this.handlers.plugins) {
-        const key = this.controls.get(token)
-        return { result: await this.handlers.plugins(grant, call, params, key !== undefined && request.control === key) }
-      }
-      if (call.startsWith('accounts.') && this.handlers.accounts) {
-        const key = this.controls.get(token)
-        return { result: await this.handlers.accounts(grant, call, params, key !== undefined && request.control === key) }
-      }
-      throw new HarnessError('unknown_method', `Unknown call ${call}.`)
-    } catch (error) {
-      return { error: toErrorShape(error) }
-    }
-  }
-
-  private serve(client: Socket): void {
-    let buffer = ''
-    let waiting: SocketGrant | null = null
-    this.clients.add(client)
-    client.on('error', () => {})
-    client.once('close', () => {
-      this.clients.delete(client)
-      // A decision the native process was waiting on can no longer reach it.
-      waiting?.terminal?.disconnected()
-    })
-    client.on('data', (chunk) => {
-      buffer += chunk.toString('utf8')
-      if (Buffer.byteLength(buffer) > MAX_REQUEST_BYTES) {
-        client.destroy()
-        return
-      }
-      const newline = buffer.indexOf('\n')
-      if (newline < 0) return
-      client.pause()
-      void this.handle(buffer.slice(0, newline), { waiting: (grant) => void (waiting = grant) }).then((reply) => client.end(`${JSON.stringify(reply)}\n`))
-    })
-  }
-
-  private bind(path: string): Promise<void> {
-    return new Promise<void>((resolve, reject) => {
-      const server = createServer((client) => this.serve(client))
-      server.once('error', reject)
-      server.listen(path, () => {
-        if (!isPipePath(path)) {
-          try {
-            chmodSync(path, 0o600)
-          } catch (error) {
-            log('session socket permissions', error instanceof Error ? error.message : String(error))
-          }
-        }
-        this.server = server
-        resolve()
-      })
-    })
-  }
-
-  /** Binds the usual path, or an instance-specific path if another Harness owns it. */
-  private async bindAvailablePath(): Promise<void> {
-    if (!isPipePath(this.path)) mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 })
-    try {
-      await this.bind(this.path)
-    } catch (error) {
-      if (isPipePath(this.path) || (error as NodeJS.ErrnoException).code !== 'EADDRINUSE') throw refusedBind(this.path, error)
-      this.socketPathValue = alternateSocketPath(this.path)
-      try {
-        await this.bind(this.path)
-      } catch (alternateError) {
-        throw refusedBind(this.path, alternateError)
-      }
-    }
-  }
-
-  /** Binds the socket once; later calls wait for the same bind. */
-  listen(): Promise<void> {
-    this.listening ??= this.bindAvailablePath().catch(error => {
-      this.listening = null
-      throw error
-    })
-    return this.listening
-  }
-
-  async close(): Promise<void> {
-    this.grants.clear()
-    const server = this.server
-    this.server = null
-    this.listening = null
-    for (const client of this.clients) client.destroy()
-    if (server) await new Promise<void>((resolve) => server.close(() => resolve()))
-    if (!isPipePath(this.path)) rmSync(this.path, { force: true })
-  }
-}

package/src/terminal/standalone.test.ts

@@ -1,167 +0,0 @@
-import { EventEmitter } from 'node:events'
-import { createHash } from 'node:crypto'
-import { existsSync, mkdtempSync, rmSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { join, resolve } from 'node:path'
-import type { ChildProcess, spawn as nodeSpawn } from 'node:child_process'
-import { afterEach, describe, expect, it, vi } from 'vitest'
-
-import { memorySecretStore } from '../accounts/secrets'
-import { createHarness, type Harness, type HarnessOptions } from '../harness'
-import { defaultAssets } from './terminals'
-import { parseStandaloneOptions, runStandaloneTerminal, standaloneArguments } from './standalone'
-import { socketPath } from './socket'
-import { SOCKET_ENV, TOKEN_ENV, socketCall } from './client'
-
-const scratch: string[] = []
-const harnesses: Harness[] = []
-
-afterEach(async () => {
-  for (const harness of harnesses.splice(0)) await harness.close()
-  for (const path of scratch.splice(0)) rmSync(path, { recursive: true, force: true })
-  vi.restoreAllMocks()
-})
-
-function temporaryDirectory(prefix: string): string {
-  const path = mkdtempSync(join(tmpdir(), prefix))
-  scratch.push(path)
-  return path
-}
-
-function fakeSpawn(onSpawn: (program: string, args: string[], options: { cwd?: string; env?: NodeJS.ProcessEnv; stdio?: string }) => void, outcome: { code?: number; error?: Error } = {}): typeof nodeSpawn {
-  return ((program: string, args: string[], options: { cwd?: string; env?: NodeJS.ProcessEnv; stdio?: string }) => {
-    onSpawn(program, args, options)
-    const child = new EventEmitter() as ChildProcess
-    child.kill = vi.fn(() => true)
-    queueMicrotask(() => {
-      if (outcome.error) child.emit('error', outcome.error)
-      else child.emit('exit', outcome.code ?? 0, null)
-    })
-    return child
-  }) as unknown as typeof nodeSpawn
-}
-
-function harnessFactory(options: HarnessOptions): Harness {
-  const harness = createHarness({ ...options, secrets: memorySecretStore(), piProgram: () => '/opt/pi/bin/pi' })
-  harnesses.push(harness)
-  return harness
-}
-
-describe('standalone terminal startup', () => {
-  it('routes the no-command and terminal invocations to Pi, leaving host commands explicit', () => {
-    expect(standaloneArguments([])).toEqual([])
-    expect(standaloneArguments(['--data', '/tmp/data'])).toEqual(['--data', '/tmp/data'])
-    expect(standaloneArguments(['terminal', '--state', '/tmp/state'])).toEqual(['--state', '/tmp/state'])
-    expect(standaloneArguments(['serve', '--state', '/tmp/state'])).toBeNull()
-  })
-
-  it('uses a dedicated default data and state root and accepts path overrides', () => {
-    expect(parseStandaloneOptions([], '/home/test', '/work/project')).toEqual({
-      dataRoot: '/home/test/.xingular-harness/data',
-      stateDir: '/home/test/.xingular-harness/state'
-    })
-    expect(parseStandaloneOptions(['--data', './knowledge', '--state', './device'], '/home/test', '/work/project')).toEqual({
-      dataRoot: '/work/project/knowledge',
-      stateDir: '/work/project/device'
-    })
-    expect(() => parseStandaloneOptions(['--data'])).toThrow('--data needs a directory path.')
-    expect(() => parseStandaloneOptions(['--model', 'unknown'])).toThrow('Unknown standalone option: --model')
-  })
-
-  it('refuses default folders under a home that is not a folder path, and accepts explicit absolute folders', () => {
-    expect(() => parseStandaloneOptions([], 'HOME', '/work/project')).toThrow('is not an absolute path')
-    expect(parseStandaloneOptions(['--data', '/data', '--state', '/state'], 'HOME', '/work/project')).toEqual({ dataRoot: '/data', stateDir: '/state' })
-  })
-
-  it('starts Pi in the current directory, creates the first isolated account, and cleans up on exit', async () => {
-    const home = temporaryDirectory('harness-standalone-')
-    const cwd = temporaryDirectory('harness-cwd-')
-    const paths = parseStandaloneOptions([], home)
-    let invocation: { program: string; args: string[]; options: { cwd?: string; env?: NodeJS.ProcessEnv; stdio?: string } } | undefined
-    const spawn = fakeSpawn((program, args, options) => {
-      invocation = { program, args, options }
-    })
-
-    expect(await runStandaloneTerminal([], { home, cwd, stdinIsTTY: true, stdoutIsTTY: true, createSessionId: () => 'standalone', createHarness: harnessFactory, spawn })).toBe(0)
-
-    const harness = harnesses.shift()!
-    expect(harness.accounts.overview().accounts).toMatchObject([{ label: 'Default', isDefault: true }])
-    expect(invocation?.program).toBe('/opt/pi/bin/pi')
-    expect(invocation?.options).toMatchObject({ cwd, stdio: 'inherit' })
-    expect(invocation?.args).toContain('--extension')
-    expect(invocation?.args).toContain(defaultAssets().piExtension)
-    expect(invocation?.args).toContain(join(paths.dataRoot, 'sessions', 'terminal', createHash('sha256').update(resolve(cwd)).digest('hex'), 'pi'))
-    expect(invocation?.options.env?.PI_CODING_AGENT_DIR).toContain(join(paths.stateDir, 'accounts'))
-    expect(invocation?.options.env?.XINGULAR_HARNESS_SOCKET).toBeTruthy()
-    expect(invocation?.options.env?.XINGULAR_HARNESS_TOKEN).toBeTruthy()
-    expect(existsSync(join(paths.stateDir, 'accounts', harness.accounts.overview().accounts[0].id, 'home', 'pi', 'auth.json'))).toBe(false)
-    expect(existsSync(socketPath(paths.stateDir))).toBe(false)
-    expect(harness.terminals.has('standalone')).toBe(false)
-  })
-
-  it('requires an interactive TTY before creating Harness data', async () => {
-    const create = vi.fn(harnessFactory)
-    await expect(runStandaloneTerminal([], { stdinIsTTY: false, stdoutIsTTY: true, createHarness: create })).rejects.toThrow('needs a TTY')
-    expect(create).not.toHaveBeenCalled()
-  })
-
-  it('cleans up the prepared terminal when Pi cannot be spawned', async () => {
-    const home = temporaryDirectory('harness-standalone-fail-')
-    const cwd = temporaryDirectory('harness-cwd-fail-')
-    const spawn = fakeSpawn(() => undefined, { error: new Error('spawn failed') })
-
-    await expect(runStandaloneTerminal([], { home, cwd, stdinIsTTY: true, stdoutIsTTY: true, createSessionId: () => 'failed', createHarness: harnessFactory, spawn })).rejects.toThrow('spawn failed')
-
-    const harness = harnesses.shift()!
-    const account = harness.accounts.overview().accounts[0]
-    expect(existsSync(join(harness.accounts.dir, account.id, 'home', 'pi', 'auth.json'))).toBe(false)
-    expect(existsSync(socketPath(harness.stateDir))).toBe(false)
-    expect(harness.terminals.has('failed')).toBe(false)
-  })
-
-  it('explains a missing Pi executable in terms of the terminal launch', async () => {
-    const home = temporaryDirectory('harness-standalone-enoent-')
-    const cwd = temporaryDirectory('harness-cwd-enoent-')
-    const error = Object.assign(new Error('spawn /opt/pi/bin/pi ENOENT'), { code: 'ENOENT' })
-    const spawn = fakeSpawn(() => undefined, { error })
-
-    await expect(runStandaloneTerminal([], { home, cwd, stdinIsTTY: true, stdoutIsTTY: true, createSessionId: () => 'missing-pi', createHarness: harnessFactory, spawn }))
-      .rejects.toThrow(/Could not start Pi terminal.*Pi executable.*\/opt\/pi\/bin\/pi/)
-  })
-})
-
-describe('switching the account of a running terminal', () => {
-  it('ends Pi when the person asks for another account, and starts it again on that account', async () => {
-    const home = temporaryDirectory('harness-switch-')
-    const cwd = temporaryDirectory('harness-switch-cwd-')
-    const paths = parseStandaloneOptions([], home)
-    const spawned: { args: string[]; env: NodeJS.ProcessEnv }[] = []
-    let spareId = ''
-    const spawn = ((_program: string, args: string[], options: { cwd?: string; env?: NodeJS.ProcessEnv; stdio?: string }) => {
-      spawned.push({ args, env: options.env ?? {} })
-      const child = new EventEmitter() as ChildProcess
-      child.kill = vi.fn(() => true)
-      void (async () => {
-        // Deferred, as a real process is: the launcher attaches its listeners after spawn returns.
-        await Promise.resolve()
-        if (spawned.length === 1) {
-          // The first Pi asks for the other account through its own extension, then ends.
-          spareId = harnesses[0].accounts.create('Spare', 'apiKey').accounts.find((account) => account.label === 'Spare')!.id
-          const connection = { socket: options.env![SOCKET_ENV]!, token: options.env![TOKEN_ENV]! }
-          const { key } = await socketCall<{ key: string }>(connection, 'control.claim')
-          await socketCall(connection, 'accounts.relaunch', { accountId: spareId }, 5_000, key)
-        }
-        child.emit('exit', 0, null)
-      })()
-      return child
-    }) as unknown as typeof nodeSpawn
-
-    expect(await runStandaloneTerminal([], { home, cwd, stdinIsTTY: true, stdoutIsTTY: true, createHarness: harnessFactory, spawn })).toBe(0)
-
-    expect(spawned).toHaveLength(2)
-    expect(spawned[1].env.PI_CODING_AGENT_DIR).toContain(join(paths.stateDir, 'accounts', spareId))
-    expect(spawned[1].env[TOKEN_ENV]).not.toBe(spawned[0].env[TOKEN_ENV])
-    // The session it ended is closed; nothing is left running in the harness.
-    expect(harnesses[0].terminals.has('standalone')).toBe(false)
-  })
-})

package/src/terminal/standalone.ts

@@ -1,165 +0,0 @@
-// The standalone host prepares an isolated Harness terminal and supervises its frontend.
-import { spawn as nodeSpawn } from 'node:child_process'
-import { createHash, randomUUID } from 'node:crypto'
-import { appendFileSync } from 'node:fs'
-import { homedir } from 'node:os'
-import { isAbsolute, join, resolve } from 'node:path'
-
-import { setLogSink } from '../core/bus'
-import { createHarness, type Harness, type HarnessOptions } from '../harness'
-import type { TerminalLaunch } from './terminals'
-
-export interface StandalonePaths {
-  dataRoot: string
-  stateDir: string
-}
-
-export interface StandaloneDependencies {
-  home?: string
-  cwd?: string
-  stdinIsTTY?: boolean
-  stdoutIsTTY?: boolean
-  createSessionId?: () => string
-  createHarness?: (options: HarnessOptions) => Harness
-  spawn?: typeof nodeSpawn
-}
-
-export function standaloneArguments(argv: string[]): string[] | null {
-  const command = argv[0]
-  if (!command || command.startsWith('--') || command === '-h') return argv
-  return command === 'terminal' ? argv.slice(1) : null
-}
-
-export function parseStandaloneOptions(argv: string[], home = homedir(), cwd = process.cwd()): StandalonePaths {
-  const root = join(home, '.xingular-harness')
-  const paths: StandalonePaths = {
-    dataRoot: join(root, 'data'),
-    stateDir: join(root, 'state')
-  }
-
-  const given = new Set<string>()
-  for (let index = 0; index < argv.length; index += 1) {
-    const argument = argv[index]
-    if (argument !== '--data' && argument !== '--state') throw new Error(`Unknown standalone option: ${argument}`)
-    const value = argv[index + 1]
-    if (!value || value.startsWith('--')) throw new Error(`${argument} needs a directory path.`)
-    paths[argument === '--data' ? 'dataRoot' : 'stateDir'] = resolve(cwd, value)
-    given.add(argument)
-    index += 1
-  }
-
-  // A home that is not a folder path (for example HOME set to the word "HOME") would put the
-  // defaults, and the session socket, in whatever folder the command was started from.
-  if (!isAbsolute(home) && !(given.has('--data') && given.has('--state'))) {
-    throw new Error(`The home folder "${home}" is not an absolute path, so the default data and state folders cannot be placed. Set HOME to your home folder, or pass --data and --state with absolute folders.`)
-  }
-
-  return paths
-}
-
-function processEnvironment(overrides: Record<string, string | null>): NodeJS.ProcessEnv {
-  const environment = { ...process.env }
-  for (const [name, value] of Object.entries(overrides)) {
-    if (value === null) delete environment[name]
-    else environment[name] = value
-  }
-  return environment
-}
-
-function exitCode(code: number | null, signal: NodeJS.Signals | null): number {
-  if (code !== null) return code
-  if (signal === 'SIGINT') return 130
-  if (signal === 'SIGTERM') return 143
-  if (signal === 'SIGHUP') return 129
-  return 1
-}
-
-function spawnError(error: Error, launch: TerminalLaunch): Error {
-  const code = (error as NodeJS.ErrnoException).code
-  if (code !== 'ENOENT' && code !== 'EACCES' && code !== 'EPERM') return error
-  if (launch.program === process.execPath || launch.env.XINGULAR_HARNESS_NODE === launch.program) {
-    return new Error(`Could not start the Harness terminal because Node could not run "${launch.args[0] ?? 'the bundled Harness CLI'}" (${code}). Verify Node and the Harness package are installed.`, { cause: error })
-  }
-  const problem = code === 'ENOENT' ? 'was not found' : `could not start (${code})`
-  return new Error(`Could not start Pi terminal. Pi executable "${launch.program}" ${problem}; verify it is installed and executable or check the configured terminal executable.`, { cause: error })
-}
-
-function spawnPi(launch: TerminalLaunch, cwd: string, spawn = nodeSpawn): Promise<number> {
-  return new Promise((resolveExit, reject) => {
-    const child = spawn(launch.program, launch.args, {
-      cwd,
-      env: processEnvironment(launch.env),
-      stdio: 'inherit'
-    })
-    let settled = false
-    const cleanup = (): void => {
-      process.off('SIGINT', onInterrupt)
-      process.off('SIGTERM', onTerminate)
-      process.off('SIGHUP', onHangup)
-    }
-    const finish = (action: () => void): void => {
-      if (settled) return
-      settled = true
-      cleanup()
-      action()
-    }
-    // Ctrl+C is delivered to both processes in the foreground process group. Keep this host
-    // alive while Pi handles it so the account credentials and harness socket are cleaned up.
-    const onInterrupt = (): void => undefined
-    const onTerminate = (): void => {
-      child.kill('SIGTERM')
-    }
-    const onHangup = (): void => undefined
-
-    process.on('SIGINT', onInterrupt)
-    process.on('SIGTERM', onTerminate)
-    process.on('SIGHUP', onHangup)
-    child.once('error', (error) => finish(() => reject(spawnError(error, launch))))
-    child.once('exit', (code, signal) => finish(() => resolveExit(exitCode(code, signal))))
-  })
-}
-
-export async function runStandaloneTerminal(argv: string[], dependencies: StandaloneDependencies = {}): Promise<number> {
-  if (!(dependencies.stdinIsTTY ?? process.stdin.isTTY) || !(dependencies.stdoutIsTTY ?? process.stdout.isTTY)) {
-    throw new Error('The interactive Harness terminal needs a TTY. Run it from a terminal, or use `xingular-harness serve` for a host process.')
-  }
-
-  const cwd = resolve(dependencies.cwd ?? process.cwd())
-  const paths = parseStandaloneOptions(argv, dependencies.home, cwd)
-  const makeHarness = dependencies.createHarness ?? createHarness
-  const harness = makeHarness({ dataRoot: paths.dataRoot, stateDir: paths.stateDir, productName: 'Xingular Harness' })
-  const newSessionId = dependencies.createSessionId ?? randomUUID
-  let current = { sessionId: newSessionId(), accountId: null as string | null, nativeSessionId: null as string | null }
-  // The frontend draws on this terminal, so the host's diagnostics go to a file the person can read instead.
-  const logFile = join(paths.stateDir, 'harness.log')
-  setLogSink((text) => {
-    try {
-      appendFileSync(logFile, `${new Date().toISOString()} ${text}\n`)
-    } catch {
-      // Diagnostics are best effort; a full disk must not stop the terminal.
-    }
-  })
-
-  try {
-    await harness.ready
-    if (harness.accounts.overview().accounts.length === 0) harness.accounts.create('Default', 'subscription')
-
-    const cwdHash = createHash('sha256').update(cwd).digest('hex')
-    const sessionFolder = join(paths.dataRoot, 'sessions', 'terminal', cwdHash)
-    for (;;) {
-      const launch = await harness.terminals.prepare({ ...current, cwd, sessionFolder })
-      const code = await spawnPi(launch, cwd, dependencies.spawn)
-      // `/accounts` asks for a switch and ends Pi. The conversation resumes on the chosen account.
-      const next = harness.terminals.takeRelaunch(current.sessionId)
-      if (!next) return code
-      const label = harness.accounts.find(next.accountId).label
-      process.stdout.write(`Switching this session to account ${label}.\n`)
-      await harness.terminals.dispose(current.sessionId)
-      current = { sessionId: newSessionId(), accountId: next.accountId, nativeSessionId: next.nativeSessionId }
-    }
-  } finally {
-    await harness.terminals.dispose(current.sessionId)
-    await harness.close()
-    setLogSink(null)
-  }
-}