@xingular/harness 0.0.0-stage → 0.1.0

package/src/terminal/pluginMenu.ts

@@ -0,0 +1,112 @@
+// The `/plugins` command of a terminal session, without Pi: what it lists, what it offers for
+// each row, and the conversation it has with the person. It asks through whatever interface it
+// is given (Pi's own dialogs in a terminal) and changes things through one function, so the
+// same flow is tested without a terminal.
+import type { Attachment } from '../plugins/attachments'
+import type { Contribution, Plugin } from '../plugins/types'
+
+export interface MenuUi {
+  select(title: string, options: string[]): Promise<string | undefined>
+  confirm(title: string, message: string): Promise<boolean>
+  notify(message: string, level?: 'info' | 'warning' | 'error'): void
+}
+
+/** `plugins.list`, `plugins.attach`, `plugins.detach`, `plugins.trust`, `plugins.untrust`. */
+export type MenuCall = <T = unknown>(method: string, params?: Record<string, unknown>) => Promise<T>
+
+export interface MenuRow {
+  /** The plugin's id, or one contribution's. */
+  id: string
+  label: string
+  on: boolean
+  /** The plugin it is, or belongs to. */
+  plugin: Plugin
+  /** Set when the row is the whole plugin. */
+  whole: boolean
+}
+
+const here = (attachment: Attachment, projectId: string | null): boolean => {
+  if (projectId && attachment.on.projectIds.includes(projectId)) return true
+  if (projectId && attachment.off.projectIds.includes(projectId)) return false
+  return attachment.global
+}
+
+const mark = (on: boolean): string => (on ? '●' : '○')
+
+/** What can be switched or trusted from here: each found or installed plugin, and each item of the rest that has a switch. */
+export function menuRows(plugins: readonly Plugin[], projectId: string | null): MenuRow[] {
+  const rows: MenuRow[] = []
+  for (const plugin of plugins) {
+    if (plugin.attachment) {
+      const on = here(plugin.attachment, projectId)
+      rows.push({ id: plugin.id, plugin, whole: true, on, label: `${mark(on)} ${plugin.title}${plugin.trust === 'untrusted' ? ' · code not trusted' : plugin.runsCode ? ' · runs code' : ''}` })
+      continue
+    }
+    if (plugin.trust !== 'none') rows.push({ id: plugin.id, plugin, whole: true, on: plugin.trust === 'trusted', label: `${mark(plugin.trust === 'trusted')} ${plugin.title} · ${plugin.trust === 'trusted' ? 'code trusted' : 'code not trusted'}` })
+    for (const entry of plugin.contributions) {
+      if (!entry.attachment) continue
+      rows.push({ id: entry.id, plugin, whole: false, on: entry.state === 'on', label: `${mark(entry.state === 'on')} ${entry.name} · ${kindWord(entry)} in ${plugin.title}` })
+    }
+  }
+  return rows
+}
+
+const kindWord = (entry: Contribution): string => (entry.kind === 'connection' ? 'connected app' : entry.kind === 'code' ? 'extension' : entry.kind)
+
+const SWITCH_OFF_PROJECT = 'Switch off for this project'
+const SWITCH_ON_PROJECT = 'Switch on for this project'
+const SWITCH_OFF_EVERYWHERE = 'Switch off everywhere'
+const SWITCH_ON_EVERYWHERE = 'Switch on everywhere'
+const TRUST = 'Trust its code'
+const UNTRUST = 'Stop trusting its code'
+const BACK = 'Back'
+const DONE = 'Done'
+
+/** What a person can do with one row. A whole plugin whose code waits for trust can be trusted here. */
+export function rowActions(row: MenuRow, projectId: string | null): string[] {
+  const switchable = row.whole ? row.plugin.attachment !== null : true
+  const actions: string[] = []
+  if (switchable) {
+    if (projectId) actions.push(row.on ? SWITCH_OFF_PROJECT : SWITCH_ON_PROJECT)
+    actions.push(row.on ? SWITCH_OFF_EVERYWHERE : SWITCH_ON_EVERYWHERE)
+  }
+  if (row.whole && row.plugin.code) actions.push(row.plugin.trust === 'untrusted' ? TRUST : UNTRUST)
+  return [...actions, BACK]
+}
+
+/**
+ * Runs the command: list, pick a row, pick what to do, until the person is done. Nothing changes
+ * without a choice made here, and trusting code asks once more with the files in view.
+ */
+export async function runPluginsMenu(ui: MenuUi, call: MenuCall, projectId: string | null): Promise<void> {
+  let changed = false
+  for (;;) {
+    const rows = menuRows(await call<Plugin[]>('plugins.list'), projectId)
+    if (!rows.length) {
+      ui.notify('There is nothing to switch or trust here yet.', 'info')
+      return
+    }
+    const picked = await ui.select(`Plugins${changed ? ' (changes apply when this session restarts)' : ''}`, [...rows.map((row) => row.label), DONE])
+    const row = rows.find((candidate) => candidate.label === picked)
+    if (!row) break
+    const action = await ui.select(`${row.plugin.title}: ${row.plugin.description || 'No description.'}`, rowActions(row, projectId))
+    if (!action || action === BACK) continue
+    try {
+      if (action === TRUST || action === UNTRUST) {
+        const code = row.plugin.code!
+        if (action === TRUST) {
+          const sure = await ui.confirm('Trust this code?', `${code.files.join('\n')}\n\nFingerprint ${code.hash.slice(0, 12)}. It runs inside the session and can do anything this app can, including reading your files and credentials.`)
+          if (!sure) continue
+        }
+        await call(action === TRUST ? 'plugins.trust' : 'plugins.untrust', { hash: code.hash })
+      } else {
+        const on = action === SWITCH_ON_PROJECT || action === SWITCH_ON_EVERYWHERE
+        await call(on ? 'plugins.attach' : 'plugins.detach', { id: row.id, everywhere: action === SWITCH_ON_EVERYWHERE || action === SWITCH_OFF_EVERYWHERE })
+      }
+      changed = true
+    } catch (error) {
+      ui.notify(error instanceof Error ? error.message : String(error), 'error')
+    }
+  }
+  if (changed) ui.notify('Saved. It applies when this session restarts.', 'info')
+}

package/src/terminal/socket.ts

@@ -0,0 +1,182 @@
+// The session socket: how a process the harness did not start in-process (the `pi` command in
+// a terminal, with its extension and the `agentx-wiki` / `agentx-mcp` commands) reaches the
+// session it belongs to. Owner-only Unix socket, 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 } from 'node:crypto'
+import { chmodSync, mkdirSync, rmSync } 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 }
+}
+
+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>
+}
+
+const MAX_REQUEST_BYTES = 1024 * 1024
+/** macOS refuses a socket path longer than 103 bytes. */
+const MAX_SOCKET_PATH = 100
+
+export function socketPath(stateDir: string): string {
+  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`)
+}
+
+export class SessionSocket {
+  private server: Server | null = null
+  private listening: Promise<void> | null = null
+  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(
+    readonly path: string,
+    private readonly handlers: SocketHandlers
+  ) {}
+
+  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 (['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('plugins.') && this.handlers.plugins) {
+        const key = this.controls.get(token)
+        return { result: await this.handlers.plugins(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`))
+    })
+  }
+
+  /** Binds the socket once; later calls wait for the same bind. */
+  listen(): Promise<void> {
+    this.listening ??= new Promise<void>((resolve, reject) => {
+      mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 })
+      rmSync(this.path, { force: true })
+      const server = createServer((client) => this.serve(client))
+      server.once('error', (error) => {
+        this.listening = null
+        reject(error)
+      })
+      server.listen(this.path, () => {
+        try {
+          chmodSync(this.path, 0o600)
+        } catch (error) {
+          log('session socket permissions', error instanceof Error ? error.message : String(error))
+        }
+        this.server = server
+        resolve()
+      })
+    })
+    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()))
+    rmSync(this.path, { force: true })
+  }
+}

package/src/terminal/standalone.test.ts

@@ -0,0 +1,115 @@
+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'
+
+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('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)
+  })
+})

package/src/terminal/standalone.ts

@@ -0,0 +1,126 @@
+// The standalone entry point for people using the harness directly. Pi owns the interface;
+// the harness prepares the isolated account, context, extension, and session socket.
+import { spawn as nodeSpawn } from 'node:child_process'
+import { createHash, randomUUID } from 'node:crypto'
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+
+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')
+  }
+
+  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)
+    index += 1
+  }
+
+  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 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(error)))
+    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 sessionId = (dependencies.createSessionId ?? randomUUID)()
+
+  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)
+    const launch = await harness.terminals.prepare({ sessionId, cwd, sessionFolder })
+    return await spawnPi(launch, cwd, dependencies.spawn)
+  } finally {
+    await harness.terminals.dispose(sessionId)
+    await harness.close()
+  }
+}