@xingular/harness 0.1.6 → 2.0.0

package/src/terminal/hubMenu.ts

@@ -0,0 +1,24 @@
+import type { HubOverview, HubReceipt } from '../hub/schema'
+import type { MenuCall, MenuUi } from './pluginMenu'
+
+/** The terminal's catalog uses the same exact-version installer as embedding applications. */
+export async function runHubMenu(ui: MenuUi, call: MenuCall): Promise<void> {
+  for (;;) {
+    const catalog = await call<HubOverview>('hub.list')
+    const labels = catalog.entries.map((entry) => `${entry.title} · ${entry.category} · ${entry.id}@${entry.version}`)
+    const picked = await ui.select('Hub', [...labels, 'Refresh catalog', 'Done'])
+    if (picked === 'Refresh catalog') {
+      const refreshed = await call<HubOverview>('hub.list', { refresh: true })
+      if (refreshed.error) ui.notify(`${refreshed.error} Using ${refreshed.origin} content.`, 'warning')
+      continue
+    }
+    const entry = catalog.entries[labels.indexOf(picked ?? '')]
+    if (!entry) return
+    const summary = `${entry.description}\n\nPublisher: ${entry.publisher}\nLicense: ${entry.license}\nSource: ${entry.sourceUrl}\n\n${entry.delivery.kind === 'document' ? 'Saved as data for a compatible application. Nothing is created or enabled.' : 'Installed switched off. Code remains untrusted and approvals remain unchanged.'}`
+    if (!await ui.confirm(`Install ${entry.title} ${entry.version}?`, summary)) continue
+    try {
+      const receipt = await call<HubReceipt>('hub.install', { id: entry.id, version: entry.version })
+      ui.notify(receipt.document ? 'Saved in this library for a compatible application.' : 'Installed, switched off. Use /plugins to review and attach it. Changes apply after restarting the session.', 'info')
+    } catch (error) { ui.notify(error instanceof Error ? error.message : String(error), 'error') }
+  }
+}

package/src/terminal/launch.test.ts

@@ -1,26 +1,17 @@
-import { spawnSync } from 'node:child_process'
 import { describe, expect, it } from 'vitest'
 
-import { bundledPiCli, resolvePiCommand, terminalCommandFiles } from './launch'
+import { resolvePiCommand, terminalCommandFiles } from './launch'
 
 describe('terminal launch commands', () => {
-  it('runs the pinned Pi CLI with the active Node runtime on Windows', () => {
-    const launch = resolvePiCommand({ platform: 'win32', node: 'C:\\Program Files\\nodejs\\node.exe' })
+  it.each(['darwin', 'linux', 'win32'] as const)('runs the owned Harness frontend with the active Node runtime on %s', (platform) => {
+    const launch = resolvePiCommand({ platform, node: 'C:\\Program Files\\nodejs\\node.exe', cli: '/bundle/cli.js' })
 
     expect(launch.program).toBe('C:\\Program Files\\nodejs\\node.exe')
-    expect(launch.argsPrefix[0]).toMatch(/[\\/]node_modules[\\/]@earendil-works[\\/]pi-coding-agent[\\/]dist[\\/]bundle[\\/]cli\.js$/)
-  })
-
-  it('runs the package CLI through Node for a no-model help smoke', () => {
-    const result = spawnSync(process.execPath, [bundledPiCli(), '--help'], { encoding: 'utf8', timeout: 20_000 })
-
-    expect(result.error).toBeUndefined()
-    expect(result.status).toBe(0)
-    expect(`${result.stdout}${result.stderr}`).toMatch(/usage|options|pi/i)
+    expect(launch.argsPrefix).toEqual(['/bundle/cli.js', 'terminal-frontend'])
   })
 
   it('keeps an explicitly configured executable even on Windows', () => {
-    expect(resolvePiCommand({ platform: 'win32', node: 'node.exe', programOverride: () => 'C:\\Tools\\pi.exe' }))
+    expect(resolvePiCommand({ platform: 'win32', node: 'node.exe', cli: '/bundle/cli.js', programOverride: () => 'C:\\Tools\\pi.exe' }))
       .toEqual({ program: 'C:\\Tools\\pi.exe', argsPrefix: [] })
   })
 

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,13 @@ 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, controlCall } from './control'
+import { SUBAGENT_OWNER, SUBAGENT_RECEIPT, SUBAGENT_RESULTS, subagentHistory, type SubagentReceipt } from '../sessions/subagents'
+import { askUserTool } from '../tools/askUser'
+import type { QuestionAnswer } from '../sessions/registry'
 
 interface SocketTool {
   name: string
@@ -22,9 +28,18 @@ function resultSize(result: unknown): number | null {
   return content.reduce((total: number, part: { type?: string; text?: unknown }) => total + (part?.type === 'text' && typeof part.text === 'string' ? part.text.length : 0), 0)
 }
 
+async function withParentCancellation<T>(signal: AbortSignal | undefined, work: () => Promise<T>): Promise<T> {
+  const stop = () => { void controlCall('terminal.interrupt').catch(() => {}) }
+  if (signal?.aborted) stop()
+  signal?.addEventListener('abort', stop, { once: true })
+  try { return await work() } finally { signal?.removeEventListener('abort', stop) }
+}
+
 export default async function (pi: ExtensionAPI) {
   await terminalCall('startup', { phase: 'Pi extension loaded' })
   let context: ExtensionContext | null = null
+  let nativeSubagents = false
+  let subagentParent = false
   let timer: ReturnType<typeof setInterval> | null = null
   let polling = false
   let failure: string | undefined
@@ -43,7 +58,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 +81,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) {
@@ -70,6 +115,15 @@ export default async function (pi: ExtensionAPI) {
         }
       })
     }
+    const native = await controlCall<{ tools: SocketTool[] }>('terminal.subagents.tools')
+    nativeSubagents = native.tools.length > 0
+    for (const tool of native.tools) pi.registerTool({
+      name: tool.name, label: tool.label, description: tool.description, parameters: Type.Unsafe(tool.parameters),
+      execute: async (_id, input, signal) => {
+        const result = await withParentCancellation(signal, () => controlCall<{ text: string; details?: Record<string, unknown> }>('terminal.subagents.call', { name: tool.name, input }, 2_147_483_647))
+        return { content: [{ type: 'text' as const, text: result.text }], details: result.details ?? {} }
+      }
+    })
   } catch (error) {
     await terminalCall('startupFailed', { reason: `${stage} failed: ${error instanceof Error ? error.message : 'Unavailable'}` }).catch(() => {})
     throw error
@@ -77,6 +131,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
@@ -106,8 +161,21 @@ export default async function (pi: ExtensionAPI) {
     reasoningTokens = undefined
     costReported = false
     // A run a plugin starts with a custom message has no user prompt to record; it still begins a turn.
-    await terminalCall('begin', { text: event.messageType === 'user' ? event.prompt : '' })
+    const begun = await terminalCall<{ runId: string }>('begin', { text: event.messageType === 'user' ? event.prompt : '' })
+    if (nativeSubagents) {
+      pi.appendEntry(SUBAGENT_OWNER, { runId: begun.runId })
+      await controlCall('terminal.subagents.register', { tools: pi.getActiveTools(), model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : null, effort: pi.getThinkingLevel(), history: subagentHistory(ctx.sessionManager.getBranch()) })
+      subagentParent = true
+    }
   })
+  const deliverChildren = async (event: any, ctx: ExtensionContext, settle: boolean) => {
+    if (!nativeSubagents || (settle && event.outcome !== 'completed') || ctx.signal?.aborted) return
+    const result = await withParentCancellation(ctx.signal, () => controlCall<{ text: string; receipt: SubagentReceipt } | null>('terminal.subagents.delivery', { history: subagentHistory([...ctx.sessionManager.getBranch(), ...event.entries]), settle }, 2_147_483_647))
+    if (!result) return
+    return { entries: [...event.entries, { type: 'custom_message' as const, customType: SUBAGENT_RESULTS, content: result.text, display: false, details: { [SUBAGENT_RECEIPT]: result.receipt } }], continue: true }
+  }
+  pi.on('turn_end', (event, ctx) => deliverChildren(event, ctx, false))
+  pi.on('agent_before_settle', (event, ctx) => deliverChildren(event, ctx, true))
   pi.on('message_end', async (event) => {
     if (event.message.role !== 'assistant') return
     if (event.message.stopReason === 'error' || event.message.stopReason === 'aborted') failure = event.message.errorMessage ?? `Pi stopped: ${event.message.stopReason}`
@@ -157,9 +225,9 @@ export default async function (pi: ExtensionAPI) {
   })
   pi.on('tool_call', async (event) => {
     try {
-      const policy = await terminalCall<{ allowed: boolean; reason?: string; requiresApproval?: boolean }>('policy', { tool: event.toolName, args: event.input })
+      const policy = await controlCall<{ allowed: boolean; reason?: string; requiresApproval?: boolean }>('terminal.policy', { tool: event.toolName, args: event.input })
       if (policy.requiresApproval) {
-        const approval = await terminalCall<{ decision: string }>('approval', { requestId: event.toolCallId, target: event.toolName, action: JSON.stringify(event.input), tool: event.toolName, args: event.input })
+        const approval = await controlCall<{ decision: string }>('terminal.approval', { requestId: event.toolCallId, tool: event.toolName, args: event.input })
         if (approval.decision === 'approved') return
         return { block: true, reason: 'The user denied this action. Ask how they would like to proceed.' }
       }
@@ -182,16 +250,33 @@ export default async function (pi: ExtensionAPI) {
     fileTools.delete(event.toolCallId)
     if (!event.isError && path) await terminalCall('file', { path, change: 'modified' })
   })
-  pi.on('agent_settled', async () => {
-    await terminalCall('settled', { error: failure })
+  pi.on('agent_settled', async (event, ctx) => {
+    if (subagentParent && !event.aborted && !failure) {
+      try { await controlCall('terminal.subagents.verify', { history: subagentHistory(ctx.sessionManager.getBranch()) }, 2_147_483_647) } catch (error) { failure = error instanceof Error ? error.message : String(error) }
+    }
+    subagentParent = false
+    await terminalCall('settled', { error: failure, aborted: event.aborted })
   })
   pi.on('user_bash', async () => {
     throw new Error('Use the bash tool so this action can be checked.')
   })
   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.test.ts

@@ -33,6 +33,29 @@ describe('session socket path', () => {
 })
 
 describe('session socket', () => {
+  it.skipIf(process.platform === 'win32')('keeps an existing Harness socket reachable when another instance uses the same state folder', async () => {
+    const base = mkdtempSync(join(tmpdir(), 'sock-shared-state-'))
+    const path = socketPath(base)
+    const first = new SessionSocket(path, handlers)
+    const second = new SessionSocket(path, handlers)
+    const canConnect = (socketPath: string): Promise<void> => new Promise((resolve, reject) => {
+      const client = createConnection(socketPath)
+      client.once('connect', () => { client.end(); resolve() })
+      client.once('error', reject)
+    })
+    try {
+      await first.listen()
+      await second.listen()
+      expect(second.path).not.toBe(first.path)
+      await second.close()
+      await expect(canConnect(first.path)).resolves.toBeUndefined()
+    } finally {
+      await first.close()
+      await second.close()
+      rmSync(base, { recursive: true, force: true })
+    }
+  })
+
   it.skipIf(process.platform !== 'win32')('listens on a named pipe and answers a request on Windows', async () => {
     const socket = new SessionSocket(socketPath('unused'), handlers)
     await socket.listen()

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
@@ -54,6 +56,11 @@ export function socketPath(stateDir: string): string {
   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\\')
 
@@ -86,6 +93,7 @@ function refusedBind(path: string, error: unknown): unknown {
 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
@@ -95,10 +103,11 @@ export class SessionSocket {
   private readonly controls = new Map<string, string>()
   private readonly clients = new Set<Socket>()
 
-  constructor(
-    readonly path: string,
-    private readonly handlers: SocketHandlers
-  ) {}
+  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('-', '')
@@ -139,6 +148,7 @@ export class SessionSocket {
       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) }
@@ -149,10 +159,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) }
@@ -182,22 +201,14 @@ export class SessionSocket {
     })
   }
 
-  /** Binds the socket once; later calls wait for the same bind. */
-  listen(): Promise<void> {
-    this.listening ??= new Promise<void>((resolve, reject) => {
-      if (!isPipePath(this.path)) {
-        mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 })
-        rmSync(this.path, { force: true })
-      }
+  private bind(path: string): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
       const server = createServer((client) => this.serve(client))
-      server.once('error', (error) => {
-        this.listening = null
-        reject(refusedBind(this.path, error))
-      })
-      server.listen(this.path, () => {
-        if (!isPipePath(this.path)) {
+      server.once('error', reject)
+      server.listen(path, () => {
+        if (!isPipePath(path)) {
           try {
-            chmodSync(this.path, 0o600)
+            chmodSync(path, 0o600)
           } catch (error) {
             log('session socket permissions', error instanceof Error ? error.message : String(error))
           }
@@ -206,6 +217,30 @@ export class SessionSocket {
         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
   }
 

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,10 +1,11 @@
-// 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 { 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'
 
@@ -77,7 +78,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 +128,17 @@ 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 }
+  // 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
@@ -135,10 +146,20 @@ 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()
+    setLogSink(null)
   }
 }