@xingular/harness 0.1.6 → 0.1.7

package/src/terminal/launch.ts

@@ -1,51 +1,14 @@
-import { existsSync, readFileSync } from 'node:fs'
-import { createRequire } from 'node:module'
-import { join, resolve } from 'node:path'
-
 import { HarnessError } from '../core/errors'
-import { findBinary } from '../core/path'
-
-const PI_PACKAGE = '@earendil-works/pi-coding-agent'
 
 export interface PiCommand {
   program: string
   argsPrefix: string[]
 }
 
-/** Resolve the Pi package's declared command instead of depending on its POSIX npm shim. */
-export function bundledPiCli(): string {
-  const require = createRequire(import.meta.url)
-  for (const nodeModules of require.resolve.paths(PI_PACKAGE) ?? []) {
-    const directory = join(nodeModules, ...PI_PACKAGE.split('/'))
-    const manifestPath = join(directory, 'package.json')
-    if (!existsSync(manifestPath)) continue
-    try {
-      const manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as {
-        name?: unknown
-        bin?: unknown
-      }
-      if (manifest.name === PI_PACKAGE) {
-        const executable = typeof manifest.bin === 'string'
-          ? manifest.bin
-          : manifest.bin && typeof manifest.bin === 'object' && typeof (manifest.bin as Record<string, unknown>).pi === 'string'
-            ? (manifest.bin as Record<string, string>).pi
-            : null
-        if (!executable) throw new Error('the package does not declare its pi command')
-        const cli = resolve(directory, executable)
-        if (!existsSync(cli)) throw new Error(`the declared command does not exist at ${cli}`)
-        return cli
-      }
-    } catch {
-      continue
-    }
-  }
-
-  throw new HarnessError('harness_unavailable', `The bundled ${PI_PACKAGE} package does not expose a usable pi command. Reinstall the Harness package and try again.`)
-}
-
 export function resolvePiCommand(options: {
   platform: NodeJS.Platform
   node: string
+  cli: string
   programOverride?: () => string | null
 }): PiCommand {
   if (options.programOverride) {
@@ -53,10 +16,7 @@ export function resolvePiCommand(options: {
     if (!program) throw new HarnessError('harness_unavailable', 'The Pi CLI was not found on PATH.')
     return { program, argsPrefix: [] }
   }
-  if (options.platform === 'win32') return { program: options.node, argsPrefix: [bundledPiCli()] }
-  const program = findBinary('pi')
-  if (!program) throw new HarnessError('harness_unavailable', 'The Pi CLI was not found on PATH.')
-  return { program, argsPrefix: [] }
+  return { program: options.node, argsPrefix: [options.cli, 'terminal-frontend'] }
 }
 
 function bashPath(path: string): string {

package/src/terminal/piExtension.lifecycle.test.ts

@@ -0,0 +1,55 @@
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+const transport = vi.hoisted(() => ({
+  socket: vi.fn(async (_connection: unknown, call: string) => call === 'control.claim' ? { key: 'lexical-key' } : { tools: [] }),
+  telemetry: vi.fn(async (event: string) => event === 'poll' ? { command: null } : {})
+}))
+vi.mock('./client', () => ({
+  connectionFromEnv: () => ({ socket: '/extension-test', token: 'lifecycle' }),
+  socketCall: transport.socket,
+  terminalCall: transport.telemetry
+}))
+
+import terminalExtension from './piExtension'
+
+function extension() {
+  const handlers = new Map<string, (...args: unknown[]) => unknown>()
+  const commands = new Map<string, unknown>()
+  const api = {
+    on: (event: string, handler: (...args: unknown[]) => unknown) => handlers.set(event, handler),
+    registerCommand: (name: string, command: unknown) => commands.set(name, command),
+    registerTool: vi.fn()
+  } as unknown as ExtensionAPI
+  const ctx = { sessionManager: { getSessionFile: () => '/history/session.jsonl' }, ui: { getEditorText: () => '' }, abort: vi.fn() } as unknown as ExtensionContext
+  return { api, ctx, handlers, commands }
+}
+
+afterEach(() => vi.useRealTimers())
+
+describe('terminal bridge lifecycle', () => {
+  it('keeps one private control claim while replacing native session pollers and restoring readiness', async () => {
+    vi.useFakeTimers()
+    const first = extension()
+    await terminalExtension(first.api)
+    await first.handlers.get('session_start')!({ type: 'session_start', reason: 'startup' }, first.ctx)
+    await vi.advanceTimersByTimeAsync(100)
+    const polls = transport.telemetry.mock.calls.filter(([event]) => event === 'poll').length
+    expect(polls).toBe(1)
+    await first.handlers.get('session_shutdown')!({ type: 'session_shutdown', reason: 'resume' }, first.ctx)
+    await vi.advanceTimersByTimeAsync(300)
+    expect(transport.telemetry.mock.calls.filter(([event]) => event === 'poll')).toHaveLength(polls)
+    expect(transport.telemetry.mock.calls.filter(([event]) => event === 'shutdown')).toHaveLength(1)
+    const next = extension()
+    await terminalExtension(next.api)
+    await next.handlers.get('session_start')!({ type: 'session_start', reason: 'resume' }, next.ctx)
+    await vi.advanceTimersByTimeAsync(100)
+    expect(transport.socket.mock.calls.filter(([, call]) => call === 'control.claim')).toHaveLength(1)
+    expect(transport.telemetry.mock.calls.filter(([event]) => event === 'ready')).toHaveLength(2)
+    expect(transport.telemetry.mock.calls.filter(([event]) => event === 'poll')).toHaveLength(polls + 1)
+    expect([...next.commands.keys()]).toEqual(['hub', 'plugins', 'accounts'])
+    await next.handlers.get('session_shutdown')!({ type: 'session_shutdown', reason: 'quit' }, next.ctx)
+    expect(transport.telemetry.mock.calls.filter(([event]) => event === 'shutdown')).toHaveLength(2)
+    expect(vi.getTimerCount()).toBe(0)
+  })
+})

package/src/terminal/piExtension.ts

@@ -6,7 +6,12 @@ import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-a
 import { Type } from 'typebox'
 
 import { connectionFromEnv, socketCall, terminalCall } from './client'
+import { runAccountsMenu, type SessionAccount } from './accountsMenu'
 import { runPluginsMenu } from './pluginMenu'
+import { runHubMenu } from './hubMenu'
+import { claimTerminalControl } from './control'
+import { askUserTool } from '../tools/askUser'
+import type { QuestionAnswer } from '../sessions/registry'
 
 interface SocketTool {
   name: string
@@ -43,7 +48,17 @@ export default async function (pi: ExtensionAPI) {
     const connection = connectionFromEnv()
     // Claimed here, before the model has run anything, and kept in this process's memory: a
     // command the model runs can read the session token from its environment, never this key.
-    const control = await socketCall<{ key: string }>(connection, 'control.claim', {}, 15_000).then((claimed) => claimed.key).catch(() => null)
+    const control = await claimTerminalControl(connection).catch(() => null)
+    pi.registerCommand('hub', {
+      description: 'Browse and install reviewed skills, plugins, and reusable documents',
+      handler: async (_args, ctx) => {
+        if (!control) return ctx.ui.notify('This session cannot install hub items.', 'warning')
+        await runHubMenu(
+          { select: (title, options) => ctx.ui.select(title, options), confirm: (title, message) => ctx.ui.confirm(title, message), notify: (message, level) => ctx.ui.notify(message, level) },
+          (method, params) => socketCall(connection, method, params ?? {}, 300_000, control)
+        )
+      }
+    })
     pi.registerCommand('plugins', {
       description: 'See what this session loads, and switch a plugin on or off or trust its code',
       handler: async (_args, ctx) => {
@@ -56,6 +71,26 @@ export default async function (pi: ExtensionAPI) {
         )
       }
     })
+    pi.registerCommand('accounts', {
+      description: 'Add, sign in to, check, switch, or remove the Pi accounts this harness uses',
+      handler: async (_args, ctx) => {
+        if (!control) return ctx.ui.notify('This session cannot manage accounts.', 'warning')
+        const session = await socketCall<SessionAccount>(connection, 'accounts.session', {}, 15_000, control).catch(() => null)
+        if (!session) return ctx.ui.notify('This session has no account to manage.', 'warning')
+        const outcome = await runAccountsMenu(
+          {
+            select: (title, options) => ctx.ui.select(title, options),
+            confirm: (title, message) => ctx.ui.confirm(title, message),
+            input: (title, placeholder) => ctx.ui.input(title, placeholder),
+            notify: (message, level) => ctx.ui.notify(message, level)
+          },
+          (method, params) => socketCall(connection, method, params ?? {}, 120_000, control),
+          session
+        )
+        // The session restarts on the account it chose: Pi ends here, and the launcher starts it again.
+        if (outcome === 'relaunch') ctx.shutdown()
+      }
+    })
     const { tools } = await socketCall<{ tools: SocketTool[] }>(connection, 'tools.list', {}, 15_000)
     stage = 'Tool registration'
     for (const tool of tools) {
@@ -77,6 +112,7 @@ export default async function (pi: ExtensionAPI) {
 
   pi.on('session_start', async (_event, ctx) => {
     context = ctx
+    if (timer) clearInterval(timer)
     await terminalCall('ready', { nativeSessionId: ctx.sessionManager.getSessionFile() })
     timer = setInterval(() => {
       if (polling || !context) return
@@ -190,8 +226,21 @@ export default async function (pi: ExtensionAPI) {
   })
   pi.on('session_shutdown', async () => {
     if (timer) clearInterval(timer)
+    timer = null
+    context = null
+    // This clears the controller's readiness while the next native session binds. The
+    // process-level control claim survives replacement; only the session poller stops.
     await terminalCall('shutdown').catch(() => {})
   })
+  const ask = askUserTool({ requestAnswers: questions => terminalCall<QuestionAnswer[]>('questions', { questions }, 1_230_000) })
+  pi.registerTool({
+    name: ask.name, label: ask.label, description: ask.description,
+    parameters: Type.Unsafe(ask.parameters(Type) as Record<string, unknown>),
+    async execute(_id, input) {
+      const result = await ask.execute(input as Record<string, unknown>)
+      return { content: [{ type: 'text', text: typeof result === 'string' ? result : result.text }], details: undefined }
+    }
+  })
   pi.registerTool({
     name: 'ask_user_question',
     label: 'Ask a question',

package/src/terminal/socket.ts

@@ -23,7 +23,7 @@ export interface SocketGrant {
   /** 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 }
+  terminal?: { accept(event: string, data: Record<string, unknown>): Promise<unknown>; disconnected(): void; control?(call: string, data: Record<string, unknown>): unknown }
 }
 
 export interface SocketHandlers {
@@ -36,6 +36,8 @@ export interface SocketHandlers {
    * 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
@@ -149,10 +151,19 @@ export class SessionSocket {
         this.controls.set(token, key)
         return { result: { key } }
       }
-      if (call.startsWith('plugins.') && this.handlers.plugins) {
+      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) }

package/src/terminal/standalone.test.ts

@@ -11,6 +11,7 @@ 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[] = []
@@ -128,3 +129,39 @@ describe('standalone terminal startup', () => {
       .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,5 +1,4 @@
-// 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.
+// 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 { homedir } from 'node:os'
@@ -77,7 +76,7 @@ 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 Pi terminal because Node could not run "${launch.args[0] ?? 'the bundled Pi CLI'}" (${code}). Verify Node and the bundled Pi package are installed.`, { cause: error })
+    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 })
@@ -127,7 +126,8 @@ export async function runStandaloneTerminal(argv: string[], dependencies: Standa
   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)()
+  const newSessionId = dependencies.createSessionId ?? randomUUID
+  let current = { sessionId: newSessionId(), accountId: null as string | null, nativeSessionId: null as string | null }
 
   try {
     await harness.ready
@@ -135,10 +135,19 @@ export async function runStandaloneTerminal(argv: string[], dependencies: Standa
 
     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)
+    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(sessionId)
+    await harness.terminals.dispose(current.sessionId)
     await harness.close()
   }
 }

package/src/terminal/terminal.test.ts

@@ -282,7 +282,8 @@ describe('a pi terminal session', () => {
     const listed = await socketCall<{ tools: { name: string; parameters: { type: string } }[] }>(connection, 'tools.list')
     expect(listed.tools.map((tool) => tool.name)).toEqual(['mcp_list_tools', 'mcp_call_tool'])
     expect(listed.tools[0].parameters.type).toBe('object')
-    await expect(socketCall(connection, 'accounts.list')).rejects.toMatchObject({ code: 'unknown_method' })
+    // Account calls exist, but only the session's extension holds the key that unlocks them.
+    await expect(socketCall(connection, 'accounts.list')).rejects.toMatchObject({ code: 'unauthorized' })
     await expect(socketCall({ ...connection, token: 'guess' }, 'wiki.list')).rejects.toMatchObject({ code: 'unauthorized' })
     await harness.terminals.dispose('term-1')
     await expect(socketCall(connection, 'wiki.list')).rejects.toMatchObject({ code: 'unauthorized' })
@@ -328,3 +329,71 @@ describe('xagent-wiki command', () => {
     expect(parseCli(['nonsense'])).toEqual({ kind: 'help' })
   })
 })
+
+
+describe('decisions in the Harness-owned frontend', () => {
+  it('requires the private input-owner key for pending decisions and exact draft state', async () => {
+    const { connection, harness, tell } = await setup()
+    await tell('ready', { nativeSessionId: '/native.jsonl' })
+    await expect(socketCall(connection, 'terminal.pending')).rejects.toMatchObject({ code: 'unauthorized' })
+    const { key } = await socketCall<{ key: string }>(connection, 'control.claim')
+    await socketCall(connection, 'terminal.draft', { dirty: true }, 1000, key)
+    expect(harness.terminals.state('term-1').dirty).toBe(true)
+    await socketCall(connection, 'terminal.draft', { dirty: false }, 1000, key)
+    expect(harness.terminals.state('term-1').dirty).toBe(false)
+    await expect(socketCall(connection, 'terminal.approve', { requestId: 'missing', decision: 'approved' }, 1000, key)).rejects.toMatchObject({ code: 'invalid_request' })
+  })
+
+  it('answers through the existing run registry and rejects stale answers', async () => {
+    const { connection, tell, events } = await setup()
+    const { key } = await socketCall<{ key: string }>(connection, 'control.claim')
+    await tell('ready')
+    await tell('begin', { text: 'Ask a question' })
+    const answer = tell('question', { requestId: 'native-question', question: 'Choose?', options: [{ label: 'A', description: 'First' }], multiSelect: false })
+    let id = ''
+    await vi.waitFor(async () => {
+      const pending = await socketCall<{ requests: Array<{ requestId: string }> }>(connection, 'terminal.pending', {}, 1000, key)
+      expect(pending.requests).toHaveLength(1)
+      id = pending.requests[0].requestId
+    })
+    await socketCall(connection, 'terminal.answer', { requestId: id, answer: { selected: ['A'] } }, 1000, key)
+    expect(await answer).toEqual({ selected: ['A'] })
+    expect(events.some(event => event.type === 'question.answered')).toBe(true)
+    await expect(socketCall(connection, 'terminal.answer', { requestId: id, answer: { selected: ['A'] } }, 1000, key)).rejects.toMatchObject({ code: 'invalid_request' })
+  })
+
+  it('keeps an approval and question with the same native tool id independent', async () => {
+    const { connection, tell } = await setup()
+    const { key } = await socketCall<{ key: string }>(connection, 'control.claim')
+    await tell('ready'); await tell('begin', { text: 'Ask after approval' })
+    const approval = tell('approval', { requestId: 'same-tool-call', target: 'ask_user_question', action: '{}' })
+    let approvalId = ''
+    await vi.waitFor(async () => {
+      const { requests } = await socketCall<{ requests: Array<{ requestId: string }> }>(connection, 'terminal.pending', {}, 1000, key)
+      expect(requests).toHaveLength(1); approvalId = requests[0].requestId
+    })
+    await socketCall(connection, 'terminal.approve', { requestId: approvalId, decision: 'approved' }, 1000, key)
+    expect(await approval).toEqual({ decision: 'approved' })
+    const question = tell('question', { requestId: 'same-tool-call', question: 'Continue?', options: [{ label: 'Yes' }] })
+    let questionId = ''
+    await vi.waitFor(async () => {
+      const { requests } = await socketCall<{ requests: Array<{ requestId: string; type: string }> }>(connection, 'terminal.pending', {}, 1000, key)
+      expect(requests).toHaveLength(1); expect(requests[0].type).toBe('question'); questionId = requests[0].requestId
+    })
+    expect(questionId).not.toBe(approvalId)
+    await socketCall(connection, 'terminal.answer', { requestId: questionId, answer: { selected: ['Yes'] } }, 1000, key)
+    expect(await question).toEqual({ selected: ['Yes'] })
+  })
+
+  it('cancels a pending question through the run interrupt path', async () => {
+    const { connection, tell, harness } = await setup()
+    const { key } = await socketCall<{ key: string }>(connection, 'control.claim')
+    await tell('ready')
+    await tell('begin', { text: 'Wait for a question' })
+    const answer = tell('question', { requestId: 'cancel-question', question: 'Wait?', options: [], multiSelect: false })
+    await vi.waitFor(async () => expect((await socketCall<{ requests: unknown[] }>(connection, 'terminal.pending', {}, 1000, key)).requests).toHaveLength(1))
+    await socketCall(connection, 'terminal.interrupt', {}, 1000, key)
+    expect(await answer).toEqual({ selected: [] })
+    expect(harness.terminals.state('term-1').active).toBe(false)
+  })
+})

package/src/terminal/terminals.ts

@@ -1,15 +1,13 @@
-// Terminal sessions: a person working with the `pi` command in a terminal that the embedding
-// application draws. The harness prepares the launch (isolated account, compiled instructions,
-// skills, the session socket), then follows the process through its extension. It never owns
-// the terminal: the application spawns the process from the spec returned here and reports when
-// it exits.
+// A host owns the PTY and process supervision; Harness owns the terminal application inside it.
+// This service prepares the isolated account, compiled context, trusted resource selection and
+// socket bridge. The default launch runs our frontend with Pi's persistent SDK runtime.
 import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 import type { Accounts } from '../accounts/accounts'
 import { configDir, launchEnv } from '../accounts/env'
-import type { Account } from '../accounts/store'
+import { readAudit, type Account } from '../accounts/store'
 import type { Bus } from '../core/bus'
 import { log } from '../core/bus'
 import type { HarnessEnv } from '../core/env'
@@ -20,8 +18,9 @@ import type { BrokerSession, ConnectedApps } from '../mcp/service'
 import type { CallerContext } from '../memory/caller'
 import { dispatch } from '../memory/dispatch'
 import type { AttachParams, PluginScope } from '../plugins/api'
-import type { Plugins } from '../plugins/plugins'
+import type { Loading, Plugins } from '../plugins/plugins'
 import type { Plugin } from '../plugins/types'
+import type { Hub } from '../hub/hub'
 import { compile, copyToRun, memoryDelta, record, render, saveForSession, type Launch } from '../prompt/compile'
 import type { RunRecord } from '../sessions/contracts'
 import { isActiveStatus } from '../sessions/contracts'
@@ -36,6 +35,16 @@ import { TerminalController, type PolicyReply } from './controller'
 import { resolvePiCommand, terminalCommandFiles } from './launch'
 import { SessionSocket, socketPath } from './socket'
 
+/** Identity of the exact resource decision that this terminal was prepared with. */
+function resourceIdentity(loading: Loading | null): string {
+  if (!loading) return 'null'
+  return JSON.stringify({
+    extensions: loading.extensionPaths, builtins: loading.builtins, skills: loading.skillPaths,
+    prompts: loading.promptPaths, themes: loading.themePaths, detached: loading.detached,
+    project: loading.projectCode, packages: loading.packageCode
+  })
+}
+
 /** The files a terminal session needs on disk, outside this process. */
 export interface TerminalAssets {
   /** The Node binary that runs the commands. */
@@ -102,8 +111,9 @@ export interface TerminalsOptions {
   plugins?: Plugins
   /** Lists plugins and applies a person's choices, for the session's `/plugins` command. */
   pluginControl?: PluginControl
+  hub?: Hub
   assets?: TerminalAssets
-  /** The `pi` executable. Defaults to the PATH command on POSIX and the bundled CLI on Windows. */
+  /** The `pi` executable. Defaults to the pinned bundled CLI through the active Node runtime. */
   program?: () => string | null
 }
 
@@ -121,13 +131,17 @@ export class Terminals {
   private readonly sessions = new Map<string, Live>()
   private readonly socket: SessionSocket
   private readonly assets: TerminalAssets
+  /** A session's `/accounts` switch, taken once its Pi process has ended. */
+  private readonly relaunches = new Map<string, { accountId: string; nativeSessionId: string | null }>()
 
   constructor(private readonly options: TerminalsOptions) {
     this.assets = options.assets ?? defaultAssets()
+    options.runs.listen(event => this.sessions.get(event.sessionId)?.controller.observe(event))
     this.socket = new SessionSocket(socketPath(options.stateDir), {
       memory: (caller, call, params) => dispatch(options.env, caller, call, params),
       apps: (session, call, params) => this.appsCall(session, call, params),
-      plugins: (grant, call, params, control) => this.pluginsCall(grant.sessionId, call, params, control)
+      plugins: (grant, call, params, control) => this.pluginsCall(grant.sessionId, call, params, control),
+      accounts: (grant, call, params, control) => this.accountsCall(grant.sessionId, call, params, control)
     })
   }
 
@@ -200,6 +214,12 @@ export class Terminals {
     if (!api || !live) throw new HarnessError('unknown_method', `Unknown call ${call}.`)
     const projectId = live.input.projectId ?? null
     const scope = { cwd: live.input.cwd, accountId: live.account.id, projectId }
+    if (call === 'hub.list' && this.options.hub) return this.options.hub.list(params.refresh === true)
+    if (call === 'hub.install' && this.options.hub) {
+      if (!control) throw new HarnessError('unauthorized', 'Only a person at this terminal can install items. Type /hub.')
+      if (typeof params.id !== 'string' || typeof params.version !== 'string') throw invalid('An item id and version are required.')
+      return this.options.hub.install(params.id, params.version)
+    }
     if (call === 'plugins.list') return api.list(scope)
     if (call === 'plugins.session') return { projectId }
     if (!control) throw new HarnessError('unauthorized', 'Only a person at this terminal can change plugins. Type /plugins.')
@@ -220,6 +240,86 @@ export class Terminals {
     }
   }
 
+  /**
+   * `/accounts` in a terminal. Every call needs the session's control key: adding, signing in,
+   * or removing an account is a person's choice, never the model's shell command.
+   */
+  private async accountsCall(sessionId: string, call: string, params: Record<string, unknown>, control: boolean): Promise<unknown> {
+    const { accounts } = this.options
+    const live = this.sessions.get(sessionId)
+    if (!live) throw new HarnessError('unknown_method', `Unknown call ${call}.`)
+    if (!control) throw new HarnessError('unauthorized', 'Only a person at this terminal can manage accounts. Type /accounts.')
+    const text = (name: string): string => {
+      if (typeof params[name] !== 'string' || !params[name]) throw invalid(`${name} is required.`)
+      return params[name] as string
+    }
+    const optional = (name: string): string | null => (typeof params[name] === 'string' ? (params[name] as string) : null)
+    switch (call) {
+      case 'accounts.deviceId':
+        return accounts.installationDeviceId()
+      case 'accounts.list':
+        return accounts.overview()
+      case 'accounts.session':
+        return { accountId: live.account.id, label: live.account.label }
+      case 'accounts.create':
+        return accounts.create(text('label'), optional('authKind') ?? 'subscription')
+      case 'accounts.rename':
+        return accounts.rename(text('accountId'), text('label'))
+      case 'accounts.setDefault':
+        return accounts.setDefault(text('accountId'))
+      case 'accounts.remove': {
+        const accountId = text('accountId')
+        // Every terminal in this process counts, this session's own included. Another process's terminals are not visible here.
+        if (accounts.terminalCount(accountId) > 0) throw new HarnessError('account_in_use', 'A running terminal is using this account, this one included.', 'Switch this session to another account first, then remove it.')
+        return accounts.remove(accountId)
+      }
+      case 'accounts.refresh':
+        return accounts.refresh(optional('accountId'))
+      case 'accounts.providers':
+        return accounts.providers()
+      case 'accounts.loginStart':
+        return accounts.loginStart(text('accountId'), text('provider'), optional('method'))
+      case 'accounts.loginStatus':
+        return accounts.loginStatus(text('accountId'))
+      case 'accounts.loginRespond':
+        accounts.loginRespond(text('loginId'), text('promptId'), optional('value'))
+        return {}
+      case 'accounts.loginCancel':
+        accounts.loginCancel(text('accountId'), optional('loginId'))
+        return {}
+      case 'accounts.setApiKey':
+        return accounts.setApiKey(text('accountId'), text('key'), text('provider'))
+      case 'accounts.removeProvider':
+        return accounts.removeProvider(text('accountId'), text('provider'))
+      case 'accounts.signOut':
+        return accounts.signOut(text('accountId'))
+      case 'accounts.savePool': {
+        const pool = params.pool as { id?: unknown; label?: unknown; accountIds?: unknown } | undefined
+        if (!pool || typeof pool.label !== 'string' || !Array.isArray(pool.accountIds) || !pool.accountIds.every((id) => typeof id === 'string')) throw invalid('A pool needs a label and its account ids.')
+        return accounts.savePool({ id: typeof pool.id === 'string' ? pool.id : undefined, label: pool.label, accountIds: pool.accountIds as string[] })
+      }
+      case 'accounts.removePool':
+        return accounts.removePool(text('poolId'))
+      case 'accounts.audit':
+        return readAudit(accounts.dir, optional('accountId'), typeof params.limit === 'number' ? params.limit : 100)
+      case 'accounts.relaunch': {
+        // Checked here so a bad choice is refused before the session is asked to end.
+        const target = accounts.resolve(text('accountId'))
+        this.relaunches.set(sessionId, { accountId: target.id, nativeSessionId: live.controller.nativeSessionId })
+        return { accountId: target.id, label: target.label }
+      }
+      default:
+        throw new HarnessError('unknown_method', `Unknown call ${call}.`)
+    }
+  }
+
+  /** The account a session asked to switch to. Taken once, after its Pi process has ended and before `dispose`. */
+  takeRelaunch(sessionId: string): { accountId: string; nativeSessionId: string | null } | null {
+    const request = this.relaunches.get(sessionId) ?? null
+    this.relaunches.delete(sessionId)
+    return request
+  }
+
   private live(sessionId: string): Live {
     const live = this.sessions.get(sessionId)
     if (!live) throw new HarnessError('terminal_not_ready', 'The terminal controller is unavailable. Reopen this session.')
@@ -307,7 +407,7 @@ export class Terminals {
     const { root } = env
     if (!input?.sessionId || !input.cwd || !input.sessionFolder) throw invalid('A terminal session needs an id, a working folder, and its own folder.')
     await this.dispose(input.sessionId)
-    const command = resolvePiCommand({ platform: process.platform, node: this.assets.node, programOverride: this.options.program })
+    const command = resolvePiCommand({ platform: process.platform, node: this.assets.node, cli: this.assets.cli, programOverride: this.options.program })
     // A pinned account is used as it is; it is never exchanged for another one.
     const account = input.accountId ? accounts.find(input.accountId) : accounts.resolve(null, null)
     const launch = launchEnv(accounts.dir, account)
@@ -339,14 +439,23 @@ export class Terminals {
           begin: ({ reservedRunId, text }) => this.begin(live, reservedRunId, text),
           policy: (run, tool, args) => this.decide(live, run, tool, args),
           native: (nativeSessionId) => bus.emit({ type: 'terminal.native', sessionId, nativeSessionId }),
-          telemetry: (event) => bus.emit({ type: 'terminal.telemetry', sessionId, event })
+          telemetry: (event) => bus.emit({ type: 'terminal.telemetry', sessionId, event }),
+          interrupt: runId => this.options.runs.interrupt(runId),
+          resolveApproval: (runId, id, decision) => this.options.runs.resolveApproval(runId, id, decision),
+          answerQuestion: (runId, id, answer) => this.options.runs.answerQuestion(runId, id, answer),
+          answerQuestions: (runId, batchId, answers) => this.options.runs.answerQuestions(runId, batchId, answers)
         })
       }
       token = this.socket.issue({
         sessionId,
         caller: () => ({ ...caller, runId: live.controller.activeRun?.runId ?? null }),
         broker,
-        terminal: { accept: (event, data) => live.controller.accept(event, data), disconnected: () => live.controller.disconnected() }
+        terminal: { accept: (event, data) => live.controller.accept(event, data), disconnected: () => live.controller.disconnected(), control: async (call, params) => {
+          if (call !== 'terminal.resources') return live.controller.control(call, params)
+          const current = await this.options.plugins?.loading({ cwd: input.cwd, agentDir: configDir(accounts.dir, account), install: false, caller: { projectId: input.projectId ?? null } }) ?? null
+          if (resourceIdentity(current) !== resourceIdentity(loading)) throw new HarnessError('terminal_resources_changed', 'Trusted resources changed since this terminal was prepared. Review /plugins and reopen the terminal to load the new selection.')
+          return {}
+        } }
       })
       live.token = token
       this.sessions.set(sessionId, live)
@@ -370,6 +479,7 @@ export class Terminals {
         args,
         env: {
           ...launch,
+          XINGULAR_HARNESS_NAME: env.productName,
           ...(process.platform === 'win32' ? { XINGULAR_HARNESS_NODE: this.assets.node, XINGULAR_HARNESS_CLI: this.assets.cli } : {}),
           ...prependSearchPath(this.ensureCommands(), searchPath()),
           [SOCKET_ENV]: this.socket.path,