@xingular/harness 0.1.6 → 2.0.0

package/src/terminal/accountsMenu.ts

@@ -0,0 +1,382 @@
+// The `/accounts` command of a terminal session, without Pi: what it lists, what it offers for
+// each account, and the sign-in conversation. It asks through the interface it is given and
+// changes accounts only through the session's `accounts.*` calls, so the same flow is tested
+// without a terminal. The app's Accounts screen does the same things (see App/src/modes/accounts).
+import type { AccountsOverview, AccountView, Limit } from '../accounts/store'
+import type { MenuUi } from './pluginMenu'
+
+export interface AccountsUi extends MenuUi {
+  input(title: string, placeholder?: string): Promise<string | undefined>
+}
+
+/** `accounts.*` over the session socket, with the session's control key. */
+export type AccountsCall = <T = unknown>(method: string, params?: Record<string, unknown>) => Promise<T>
+
+/** The account this session is on, from `accounts.session`. */
+export interface SessionAccount {
+  accountId: string
+  label: string
+}
+
+/** One entry of `accounts.providers`. */
+export interface ProviderOption {
+  id: string
+  name: string
+  oauth: boolean
+  oauthLabel: string | null
+  apiKey: boolean
+}
+
+/** `accounts.loginStatus`. `events` and `prompt` are the harness's own login steps, passed through. */
+interface LoginSnapshot {
+  loginId: string
+  revision: number
+  status: 'running' | 'completed' | 'failed' | 'cancelled'
+  events: Record<string, unknown>[]
+  prompt: Record<string, unknown> | null
+  error: string | null
+}
+
+/** The same words the app shows for each health state (`App/src/modes/accounts/accountModel.ts`). */
+const HEALTH: Record<string, string> = {
+  ok: 'Ready',
+  limited: 'Limit reached',
+  auth_expired: 'Sign in again',
+  signed_out: 'Signed out',
+  error: 'Needs attention',
+  unknown: 'Not checked'
+}
+
+const ADD = 'Add account'
+const POOLS = 'Pools'
+const CHECK_ALL = 'Check all accounts'
+const DONE = 'Done'
+const BACK = 'Back'
+const USE_HERE = 'Use for this session (restarts it)'
+const MAKE_DEFAULT = 'Make default for new sessions'
+const RENAME = 'Rename'
+const CHECK = 'Check'
+const DETAILS = 'Details'
+const ACTIVITY = 'Activity'
+const SIGN_IN = 'Sign in'
+const REMOVE_PROVIDER = 'Remove a provider'
+const SIGN_OUT = 'Sign out'
+const REMOVE = 'Remove account'
+const NEW_POOL = 'New pool'
+const EDIT = 'Edit'
+const DELETE = 'Delete'
+const SAVE_POOL = 'Save pool'
+const CANCEL = 'Cancel'
+const START_OVER = 'Start over'
+const REMOVE_LAST = 'Remove the last one'
+const CANCEL_SIGN_IN = 'Cancel sign-in'
+const CHECK_STATUS = 'Check status'
+
+const LOGIN_TIMEOUT_MS = 10 * 60_000
+const POLL_MS = 1000
+
+const message = (error: unknown): string => (error instanceof Error ? error.message : String(error))
+
+/** Runs one call, reports a failure through the menu, and says whether it worked. */
+async function attempt(ui: MenuUi, action: () => Promise<unknown>): Promise<boolean> {
+  try {
+    await action()
+    return true
+  } catch (error) {
+    ui.notify(message(error), 'error')
+    return false
+  }
+}
+
+/** A short "in 2h 5m" from an ISO time, or the time itself when it has passed. */
+export function resetIn(resetsAt: string, now = Date.now()): string {
+  const minutes = Math.round((Date.parse(resetsAt) - now) / 60_000)
+  if (Number.isNaN(minutes)) return resetsAt
+  if (minutes <= 0) return 'now'
+  if (minutes < 60) return `in ${minutes}m`
+  if (minutes < 60 * 24) return `in ${Math.floor(minutes / 60)}h ${minutes % 60}m`
+  return `in ${Math.floor(minutes / (60 * 24))}d`
+}
+
+/** One line per account, numbered so two accounts with the same name stay distinct in the menu. */
+export function accountRows(overview: AccountsOverview, session: SessionAccount | null): { label: string; account: AccountView }[] {
+  return overview.accounts.map((account, index) => {
+    const mark = account.isDefault ? '●' : '○'
+    const here = session?.accountId === account.id ? ' · this session' : ''
+    return { account, label: `${index + 1}. ${mark} ${account.label} · ${HEALTH[account.state.health] ?? HEALTH.unknown}${here}` }
+  })
+}
+
+const limitLine = (limit: Limit): string => `${limit.label}: ${limit.usedPercent ?? '?'}% used${limit.resetsAt ? `, resets ${resetIn(limit.resetsAt)}` : ''}`
+
+/** What `Details` shows for one account. */
+export function accountDetails(account: AccountView): string {
+  const state = account.state
+  const lines = [
+    account.label,
+    `Health: ${HEALTH[state.health] ?? HEALTH.unknown}`,
+    `Default for new sessions: ${account.isDefault ? 'yes' : 'no'}`,
+    `Signed in: ${state.signedIn === null ? 'not checked' : state.signedIn ? 'yes' : 'no'}`,
+    `Providers: ${state.piProviders.length ? state.piProviders.join(', ') : 'none'}`,
+    state.plan ? `Plan: ${state.plan}` : null,
+    state.identity ? `Identity: ${state.identity}` : null,
+    `Last checked: ${state.lastCheckedAt ? new Date(state.lastCheckedAt).toLocaleString() : 'never'}`,
+    state.lastError ? `Last error: ${state.lastError.message}${state.lastError.resetsAt ? ` (resets ${resetIn(state.lastError.resetsAt)})` : ''}` : null,
+    ...state.limits.map(limitLine),
+    state.limits.length ? null : 'Usage limits: Pi providers do not report them.',
+    state.capabilities.length ? `Detected: ${state.capabilities.join(', ')}` : null
+  ]
+  return lines.filter((line): line is string => line !== null).join('\n')
+}
+
+/** The text shown while a sign-in waits for the person: a link, or a code to enter. */
+function loginStep(step: Record<string, unknown>): string | null {
+  if (step.type === 'auth_url' && typeof step.url === 'string') return `Open this link to sign in:\n${step.url}${typeof step.instructions === 'string' ? `\n${step.instructions}` : ''}`
+  if (step.type === 'device_code' && typeof step.userCode === 'string') return `Enter the code ${step.userCode} at ${String(step.verificationUri ?? '')}`
+  return null
+}
+
+/** The whole `/accounts` conversation. Returns `'relaunch'` when the person chose to switch this session's account. */
+export async function runAccountsMenu(ui: AccountsUi, call: AccountsCall, session: SessionAccount): Promise<'relaunch' | void> {
+  for (;;) {
+    const overview = await call<AccountsOverview>('accounts.list')
+    const rows = accountRows(overview, session)
+    const options = [...rows.map((row) => row.label), ADD, POOLS, CHECK_ALL, DONE]
+    const picked = await ui.select('Accounts', options)
+    if (!picked || picked === DONE) return
+    if (picked === ADD) {
+      await addAccount(ui, call)
+      continue
+    }
+    if (picked === POOLS) {
+      await poolsMenu(ui, call)
+      continue
+    }
+    if (picked === CHECK_ALL) {
+      await attempt(ui, () => call('accounts.refresh'))
+      continue
+    }
+    const row = rows[options.indexOf(picked)]
+    if (!row) continue
+    if ((await accountMenu(ui, call, session, row.account.id)) === 'relaunch') return 'relaunch'
+  }
+}
+
+async function addAccount(ui: AccountsUi, call: AccountsCall): Promise<void> {
+  const label = await ui.input('Name for the new account', 'Work, Personal, …')
+  if (!label?.trim()) return
+  if (await attempt(ui, () => call('accounts.create', { label: label.trim(), authKind: 'subscription' }))) ui.notify('Account added. Sign in to use it.', 'info')
+}
+
+async function accountMenu(ui: AccountsUi, call: AccountsCall, session: SessionAccount, accountId: string): Promise<'relaunch' | void> {
+  const isSession = session.accountId === accountId
+  for (;;) {
+    const overview = await call<AccountsOverview>('accounts.list')
+    const account = overview.accounts.find((candidate) => candidate.id === accountId)
+    if (!account) return
+    const actions = [
+      ...(isSession ? [] : [USE_HERE]),
+      ...(account.isDefault ? [] : [MAKE_DEFAULT]),
+      RENAME,
+      CHECK,
+      DETAILS,
+      ACTIVITY,
+      SIGN_IN,
+      ...(account.state.piProviders.length ? [REMOVE_PROVIDER] : []),
+      SIGN_OUT,
+      // The session's own account is in use, so it cannot be removed from inside the session.
+      ...(isSession ? [] : [REMOVE]),
+      BACK
+    ]
+    const action = await ui.select(`${account.label} · ${HEALTH[account.state.health] ?? HEALTH.unknown}`, actions)
+    if (!action || action === BACK) return
+    if (action === USE_HERE) {
+      if (!(await ui.confirm('Switch this session?', `This ends the terminal's Pi process and resumes the conversation on ${account.label}. Work in progress stops.`))) continue
+      if (await attempt(ui, () => call('accounts.relaunch', { accountId }))) {
+        ui.notify(`Switching to ${account.label}.`, 'info')
+        return 'relaunch'
+      }
+    } else if (action === MAKE_DEFAULT) {
+      if (await attempt(ui, () => call('accounts.setDefault', { accountId }))) ui.notify(`${account.label} is the default for new sessions.`, 'info')
+    } else if (action === RENAME) {
+      const label = await ui.input('New name', account.label)
+      if (label?.trim()) await attempt(ui, () => call('accounts.rename', { accountId, label: label.trim() }))
+    } else if (action === CHECK) {
+      if (await attempt(ui, () => call('accounts.refresh', { accountId }))) ui.notify('Checked.', 'info')
+    } else if (action === DETAILS) {
+      await ui.select(accountDetails(account), [BACK])
+    } else if (action === ACTIVITY) {
+      await showActivity(ui, call, accountId, account.label)
+    } else if (action === SIGN_IN) {
+      await signIn(ui, call, account)
+    } else if (action === REMOVE_PROVIDER) {
+      const provider = await ui.select('Remove which provider?', [...account.state.piProviders, BACK])
+      if (!provider || provider === BACK) continue
+      if (await ui.confirm(`Remove ${provider}?`, `The stored ${provider} sign-in for ${account.label} is deleted from this device.`)) await attempt(ui, () => call('accounts.removeProvider', { accountId, provider }))
+    } else if (action === SIGN_OUT) {
+      if (await ui.confirm(`Sign out of ${account.label}?`, 'Stored sign-ins are deleted. The account stays, so you can sign in again.')) await attempt(ui, () => call('accounts.signOut', { accountId }))
+    } else if (action === REMOVE) {
+      const last = overview.accounts.length === 1
+      const consequence = last
+        ? 'This is the only account. New sessions will ask you to add one.'
+        : account.isDefault
+          ? 'New sessions will use another account.'
+          : 'Sessions pinned to it will ask for another account next time they start.'
+      if (!(await ui.confirm(`Remove ${account.label}?`, `Its stored sign-in and its runtime folder are deleted. ${consequence}`))) continue
+      if (await attempt(ui, () => call('accounts.remove', { accountId }))) ui.notify(`${account.label} was removed.`, 'info')
+      return
+    }
+  }
+}
+
+async function showActivity(ui: AccountsUi, call: AccountsCall, accountId: string, label: string): Promise<void> {
+  const entries = await call<{ at: string; action: string; detail: string }[]>('accounts.audit', { accountId, limit: 30 })
+  const lines = entries.map((entry) => `${new Date(entry.at).toLocaleString()} · ${entry.action} · ${entry.detail}`)
+  await ui.select(`${label}: activity\n${lines.join('\n') || 'Nothing has happened here yet.'}`, [BACK])
+}
+
+async function signIn(ui: AccountsUi, call: AccountsCall, account: AccountView): Promise<void> {
+  const providers = await call<ProviderOption[]>('accounts.providers')
+  if (!providers.length) {
+    ui.notify('No provider here can be signed in to.', 'warning')
+    return
+  }
+  const labels = providers.map((provider, index) => `${index + 1}. ${provider.name}${account.state.piProviders.includes(provider.id) ? ' · signed in' : ''}`)
+  const pickedLabel = await ui.select(`Sign in ${account.label} to which provider?`, [...labels, BACK])
+  const index = labels.indexOf(pickedLabel ?? '')
+  const provider = providers[index]
+  if (!provider) return
+  const methods = [...(provider.oauth ? [provider.oauthLabel ?? 'Sign in with the browser'] : []), ...(provider.apiKey ? ['Enter an API key'] : [])]
+  if (!methods.length) {
+    ui.notify(`${provider.name} has no sign-in from a terminal.`, 'warning')
+    return
+  }
+  const method = methods.length === 1 ? methods[0] : await ui.select(`${provider.name}: how to sign in`, [...methods, BACK])
+  if (!method || method === BACK) return
+  if (method === 'Enter an API key') {
+    const key = await ui.input(`API key for ${provider.name}`, 'Paste the key')
+    if (!key?.trim()) return
+    if (await attempt(ui, () => call('accounts.setApiKey', { accountId: account.id, provider: provider.id, key: key.trim() }))) ui.notify(`Key saved for ${provider.name}.`, 'info')
+    return
+  }
+  await runLogin(ui, call, account.id, provider.id)
+}
+
+/** Starts a provider sign-in and follows it until it ends: shows the link or code, answers prompts, and stops on a timeout. */
+async function runLogin(ui: AccountsUi, call: AccountsCall, accountId: string, provider: string): Promise<void> {
+  let loginId: string
+  try {
+    loginId = (await call<{ loginId: string }>('accounts.loginStart', { accountId, provider })).loginId
+  } catch (error) {
+    ui.notify(message(error), 'error')
+    return
+  }
+  return followLogin(ui, call, accountId, loginId)
+}
+
+async function followLogin(ui: AccountsUi, call: AccountsCall, accountId: string, loginId: string): Promise<void> {
+  const deadline = Date.now() + LOGIN_TIMEOUT_MS
+  let shownRevision = -1
+  for (;;) {
+    const snapshot = await call<LoginSnapshot | null>('accounts.loginStatus', { accountId })
+    // A newer sign-in on this account replaced ours; there is nothing left to follow.
+    if (!snapshot || snapshot.loginId !== loginId) return
+    if (snapshot.status !== 'running') return reportLogin(ui, snapshot)
+    if (snapshot.prompt) {
+      await answerPrompt(ui, call, loginId, snapshot.prompt)
+      continue
+    }
+    const step = [...snapshot.events].reverse().map(loginStep).find((text) => text !== null)
+    if (step && snapshot.revision !== shownRevision) {
+      shownRevision = snapshot.revision
+      const choice = await ui.select(`${step}\n\nFinish in your browser, then choose Check status.`, [CHECK_STATUS, CANCEL_SIGN_IN])
+      if (choice === CANCEL_SIGN_IN) {
+        await call('accounts.loginCancel', { accountId, loginId })
+        ui.notify('Sign-in cancelled.', 'warning')
+        return
+      }
+      continue
+    }
+    if (Date.now() > deadline) {
+      await call('accounts.loginCancel', { accountId, loginId })
+      ui.notify('Sign-in timed out and was cancelled.', 'error')
+      return
+    }
+    await new Promise((resolve) => setTimeout(resolve, POLL_MS))
+  }
+}
+
+function reportLogin(ui: AccountsUi, snapshot: LoginSnapshot): void {
+  if (snapshot.status === 'completed') ui.notify('Signed in.', 'info')
+  else if (snapshot.status === 'cancelled') ui.notify('Sign-in was cancelled.', 'warning')
+  else ui.notify(snapshot.error ?? 'Sign-in failed.', 'error')
+}
+
+async function answerPrompt(ui: AccountsUi, call: AccountsCall, loginId: string, prompt: Record<string, unknown>): Promise<void> {
+  const promptId = String(prompt.promptId ?? '')
+  const detail = (prompt.prompt ?? {}) as { type?: string; message?: string; placeholder?: string | null; options?: unknown }
+  const text = detail.message ?? 'Sign-in needs an answer.'
+  // A secret is typed with `input` like any other answer: it is never echoed or logged here.
+  let value: string | undefined
+  if (detail.type === 'select' && Array.isArray(detail.options)) {
+    if (detail.options.every((option) => typeof option === 'string')) {
+      value = await ui.select(text, detail.options as string[])
+    } else if (detail.options.every((option) => typeof option === 'object' && option !== null && 'id' in option && typeof option.id === 'string' && 'label' in option && typeof option.label === 'string')) {
+      const options = detail.options as { id: string; label: string }[]
+      const selected = await ui.select(text, options.map((option) => option.label))
+      value = options.find((option) => option.label === selected)?.id
+    }
+  } else {
+    value = await ui.input(text, detail.placeholder ?? undefined)
+  }
+  await call('accounts.loginRespond', { loginId, promptId, value: value ?? null })
+}
+
+async function poolsMenu(ui: AccountsUi, call: AccountsCall): Promise<void> {
+  for (;;) {
+    const overview = await call<AccountsOverview>('accounts.list')
+    const names = new Map(overview.accounts.map((account) => [account.id, account.label]))
+    const labels = overview.pools.map((pool, index) => `${index + 1}. ${pool.label} · ${pool.accountIds.map((id) => names.get(id) ?? 'removed account').join(' → ')}`)
+    const options = [NEW_POOL, ...labels, BACK]
+    const picked = await ui.select('Pools: new sessions use the first ready account in a pool, in this order', options)
+    if (!picked || picked === BACK) return
+    if (picked === NEW_POOL) {
+      await editPool(ui, call, overview, null)
+      continue
+    }
+    const pool = overview.pools[options.indexOf(picked) - 1]
+    if (!pool) continue
+    const action = await ui.select(pool.label, [EDIT, DELETE, BACK])
+    if (action === EDIT) await editPool(ui, call, overview, pool)
+    else if (action === DELETE && (await ui.confirm(`Delete ${pool.label}?`, 'The accounts stay. Only the pool is removed.'))) await attempt(ui, () => call('accounts.removePool', { poolId: pool.id }))
+  }
+}
+
+async function editPool(ui: AccountsUi, call: AccountsCall, overview: AccountsOverview, pool: { id: string; label: string; accountIds: string[] } | null): Promise<void> {
+  const label = await ui.input('Pool name', pool?.label)
+  if (!label?.trim()) return
+  const names = new Map(overview.accounts.map((account) => [account.id, account.label]))
+  const order: string[] = [...(pool?.accountIds ?? [])]
+  for (;;) {
+    const ordered = order.map((id, index) => `${index + 1}. ${names.get(id) ?? 'removed account'}`).join('  ')
+    const free = overview.accounts.filter((account) => !order.includes(account.id))
+    const addOptions = free.map((account) => `Add ${account.label}`)
+    const options = [...addOptions, ...(order.length ? [REMOVE_LAST, START_OVER] : []), SAVE_POOL, CANCEL]
+    const picked = await ui.select(`${label.trim()}: ${ordered || 'no accounts yet'}`, options)
+    if (!picked || picked === CANCEL) return
+    if (picked === SAVE_POOL) {
+      if (!order.length) {
+        ui.notify('A pool needs at least one account.', 'error')
+        continue
+      }
+      if (await attempt(ui, () => call('accounts.savePool', { pool: { id: pool?.id, label: label.trim(), accountIds: order } }))) ui.notify('Pool saved.', 'info')
+      return
+    }
+    if (picked === START_OVER) order.length = 0
+    else if (picked === REMOVE_LAST) order.pop()
+    else {
+      const account = free[addOptions.indexOf(picked)]
+      if (account) order.push(account.id)
+    }
+  }
+}

package/src/terminal/control.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it, vi } from 'vitest'
+
+const calls = vi.hoisted(() => ({ socket: vi.fn(async (_connection: unknown, call: string) => call === 'control.claim' ? { key: 'lexical-secret' } : { done: true }), env: { socket: '/fake/socket', token: 'unique-control-test' } }))
+vi.mock('./client', () => ({ connectionFromEnv: () => calls.env, socketCall: calls.socket }))
+
+import { claimTerminalControl, controlCall } from './control'
+
+describe('the process-lifetime terminal control claim', () => {
+  it('shares one concurrent claim with the bridge and frontend and passes the key only in protected calls', async () => {
+    const [first, second] = await Promise.all([claimTerminalControl(), claimTerminalControl()])
+    expect(first).toBe('lexical-secret')
+    expect(second).toBe(first)
+    await expect(controlCall('terminal.pending', { cursor: 'question' }, 321)).resolves.toEqual({ done: true })
+    expect(calls.socket.mock.calls.filter(([, call]) => call === 'control.claim')).toHaveLength(1)
+    expect(calls.socket).toHaveBeenLastCalledWith(calls.env, 'terminal.pending', { cursor: 'question' }, 321, 'lexical-secret')
+    expect(calls.env).toEqual({ socket: '/fake/socket', token: 'unique-control-test' })
+  })
+
+  it('keeps a different terminal grant separate', async () => {
+    await claimTerminalControl({ socket: '/fake/socket', token: 'different-terminal' })
+    expect(calls.socket.mock.calls.filter(([, call]) => call === 'control.claim')).toHaveLength(2)
+  })
+})

package/src/terminal/control.ts

@@ -0,0 +1,23 @@
+import { connectionFromEnv, socketCall, type SocketConnection } from './client'
+
+const claims = new Map<string, Promise<string>>()
+
+/** A process owns the claim across native session replacement; it never enters the environment. */
+export function claimTerminalControl(connection: SocketConnection = connectionFromEnv()): Promise<string> {
+  const identity = JSON.stringify([connection.socket, connection.token])
+  let claim = claims.get(identity)
+  if (!claim) {
+    claim = socketCall<{ key: string }>(connection, 'control.claim', {}, 15_000).then(({ key }) => {
+      if (!key) throw new Error('The terminal controller returned no control key.')
+      return key
+    })
+    claims.set(identity, claim)
+  }
+  return claim
+}
+
+export async function controlCall<T = unknown>(call: string, params: Record<string, unknown> = {}, timeoutMs = 120_000): Promise<T> {
+  const connection = connectionFromEnv()
+  const control = await claimTerminalControl(connection)
+  return socketCall<T>(connection, call, params, timeoutMs, control)
+}

package/src/terminal/controller.ts

@@ -5,12 +5,15 @@
 import { createHash, randomUUID } from 'node:crypto'
 
 import { HarnessError } from '../core/errors'
-import type { ActiveRun, ApprovalDecision, QuestionAnswer } from '../sessions/registry'
+import type { RunEvent } from '../sessions/contracts'
+import type { ActiveRun, ApprovalDecision, QuestionAnswer, QuestionInput } from '../sessions/registry'
 
 export interface PolicyReply {
   allowed: boolean
   reason?: string | null
   requiresApproval?: boolean
+  rememberable?: boolean
+  standing?: 'full' | 'switch' | 'none'
 }
 
 export interface ControllerHooks {
@@ -20,9 +23,15 @@ export interface ControllerHooks {
   begin(input: { reservedRunId: string | null; nativeTurnId: string; text: string }): ActiveRun
   /** Whether a native tool call may run. */
   policy(run: ActiveRun, tool: string, args: unknown): Promise<PolicyReply>
+  /** Saves a user-selected tool grant in the shared local approval store. */
+  allowToolGlobally(target: string): void
   /** The native conversation identity changed. */
   native(nativeSessionId: string): void
   telemetry(event: string): void
+  interrupt?(runId: string): Promise<void>
+  resolveApproval?(runId: string, requestId: string, decision: ApprovalDecision): void
+  answerQuestion?(runId: string, requestId: string, answer: QuestionAnswer): void
+  answerQuestions?(runId: string, batchId: string, answers: Array<{ questionId: string; answer: QuestionAnswer }>): void
 }
 
 interface Delivery {
@@ -39,6 +48,7 @@ const ACK_TIMEOUT_MS = 25_000
 
 export class TerminalController {
   private run: ActiveRun | null = null
+  private readonly pending = new Map<string, Record<string, unknown>>()
   private ready = false
   private disposed = false
   private dirty = false
@@ -90,6 +100,7 @@ export class TerminalController {
     this.run?.finish(outcome, message ? { code: 'terminal_attention', message } : undefined)
     this.run = null
     this.seen.clear()
+    this.pending.clear()
   }
 
   /** Hands the native process an instruction and waits until it acknowledges the prompt. */
@@ -140,6 +151,111 @@ export class TerminalController {
     this.finish('failed', 'The native decision callback disconnected. Inspect the terminal before continuing.')
   }
 
+  /** Project registry-owned questions, including grouped requests, into the terminal inbox. */
+  observe(event: RunEvent, descendant = false): void {
+    if (this.disposed || !this.activeRun || (!descendant && event.runId !== this.activeRun.runId)) return
+    if (event.type === 'question.requested') {
+      const payload = event.payload as Record<string, unknown>
+      this.pending.set(String(payload.questionId), { ...payload, type: 'question', requestId: payload.questionId, runId: event.runId })
+    } else if (descendant && event.type === 'approval.requested') {
+      const payload = event.payload as Record<string, unknown>
+      if (!payload.automatic) this.pending.set(String(payload.approvalId), { ...payload, type: 'approval', requestId: payload.approvalId, runId: event.runId })
+    } else if (event.type === 'approval.resolved') {
+      this.pending.delete(String((event.payload as { approvalId: string }).approvalId))
+    } else if (event.type === 'question.answered') {
+      this.pending.delete(String((event.payload as { questionId: string }).questionId))
+    }
+  }
+
+  /** The socket grants this interface only to the process that owns terminal input. */
+  async control(call: string, data: Record<string, any>): Promise<unknown> {
+    if (this.disposed) throw new HarnessError('terminal_not_ready', 'This terminal has ended.')
+    if (call === 'terminal.draft') {
+      this.dirty = data.dirty === true
+      this.multilineDraft = false
+      return {}
+    }
+    if (call === 'terminal.pending') return { requests: [...this.pending.values()] }
+    if (call === 'terminal.interrupt') return this.activeRun && this.hooks.interrupt ? this.hooks.interrupt(this.activeRun.runId) : {}
+    if (call === 'terminal.policy') {
+      const run = this.activeRun
+      if (!run || typeof data.tool !== 'string' || !data.tool) throw new HarnessError('invalid_request', 'An active run and tool name are required.')
+      return this.hooks.policy(run, data.tool, data.args ?? {})
+    }
+    if (call === 'terminal.approval') return this.requestNativeApproval(data)
+    if (call === 'terminal.answers' && this.hooks.answerQuestions) {
+      const run = this.activeRun
+      const batchId = String(data.batchId ?? '')
+      const requests = [...this.pending.values()].filter(request => request.batchId === batchId)
+      if (!run || !batchId || !requests.length || !Array.isArray(data.answers)) throw new HarnessError('invalid_request', 'This question batch is no longer pending.')
+      this.hooks.answerQuestions(String(requests[0].runId ?? run.runId), batchId, data.answers)
+      return {}
+    }
+    const requestId = String(data.requestId ?? '')
+    const request = this.pending.get(requestId)
+    const run = this.activeRun
+    if (!request || !run) throw new HarnessError('invalid_request', 'This terminal decision is no longer pending.')
+    if (call === 'terminal.approve' && request.type === 'approval' && this.hooks.resolveApproval) {
+      if (data.decision !== 'approved' && data.decision !== 'denied') throw new HarnessError('invalid_request', 'Choose approve or deny.')
+      const alwaysAllow = data.alwaysAllow === true
+      if (alwaysAllow && request.rememberable !== true) throw new HarnessError('invalid_request', 'This approval cannot be remembered for other sessions.')
+      let decision: ApprovalDecision = data.decision
+      if (decision === 'approved' && request.direct === true) {
+        const operation = request.operation as { tool?: unknown; args?: unknown } | undefined
+        const tool = typeof operation?.tool === 'string' ? operation.tool : ''
+        const current = await this.hooks.policy(run, tool, operation?.args ?? {})
+        if (!current.allowed && !current.requiresApproval) decision = 'denied'
+        if (alwaysAllow && current.rememberable !== true) {
+          request.rememberable = false
+          throw new HarnessError('invalid_request', 'This tool can no longer be allowed across sessions. Review the approval again.')
+        }
+      }
+      if (decision === 'approved' && alwaysAllow) this.hooks.allowToolGlobally(String(request.target ?? ''))
+      this.hooks.resolveApproval(String(request.runId ?? run.runId), requestId, decision)
+      return {}
+    }
+    if (call === 'terminal.answer' && request.type === 'question' && this.hooks.answerQuestion) {
+      if (!data.answer || !Array.isArray(data.answer.selected)) throw new HarnessError('invalid_request', 'A question answer is required.')
+      this.hooks.answerQuestion(String(request.runId ?? run.runId), requestId, data.answer)
+      return {}
+    }
+    throw new HarnessError('unknown_method', `Unknown terminal control ${call}.`)
+  }
+
+  private async requestNativeApproval(data: Record<string, any>): Promise<unknown> {
+    const run = this.activeRun
+    const requestId = typeof data.requestId === 'string' ? data.requestId : ''
+    const tool = typeof data.tool === 'string' ? data.tool : ''
+    if (!run || !requestId || !tool) throw new HarnessError('invalid_request', 'An active run, request id, and tool name are required.')
+    const args = data.args && typeof data.args === 'object' && !Array.isArray(data.args) ? data.args as Record<string, unknown> : {}
+    const policy = await this.hooks.policy(run, tool, args)
+    if (!policy.allowed && !policy.requiresApproval) return { decision: 'denied' }
+    if (policy.allowed && !policy.requiresApproval) return { decision: 'approved' }
+    const key = this.requestId(`approval:${requestId}`)
+    const existing = this.seen.get(key)
+    if (existing) return { decision: await existing }
+    const action = JSON.stringify(args)
+    const operation = { tool, args }
+    const response = run.requestApproval({
+      requestId: key,
+      target: tool,
+      action,
+      operation,
+      rememberable: policy.rememberable === true,
+      standing: policy.standing
+    })
+    this.pending.set(key, {
+      type: 'approval', requestId: key, runId: run.runId, target: tool, action,
+      operation, rememberable: policy.rememberable === true, direct: true
+    })
+    this.seen.set(key, response)
+    try {
+      return { decision: await response }
+    } finally {
+      this.pending.delete(key)
+    }
+  }
+
   async accept(event: string, data: Record<string, any>): Promise<unknown> {
     if (this.disposed) throw new Error('This terminal controller was disposed.')
     if (event !== 'poll') this.hooks.telemetry(event)
@@ -167,8 +283,8 @@ export class TerminalController {
       return {}
     }
     if (event === 'begin') {
-      this.begin(String(data.turnId ?? randomUUID()), String(data.text ?? ''))
-      return {}
+      const run = this.begin(String(data.turnId ?? randomUUID()), String(data.text ?? ''))
+      return { runId: run.runId }
     }
     if (event === 'shutdown') {
       this.ready = false
@@ -176,20 +292,26 @@ export class TerminalController {
       return {}
     }
     if (event === 'settled') {
-      this.finish(data.error ? 'failed' : 'completed', data.error ? String(data.error) : undefined)
+      this.finish(data.aborted ? 'interrupted' : data.error ? 'failed' : 'completed', data.error ? String(data.error) : undefined)
       return {}
     }
     const run = this.run
     if (!run) throw new Error('Native telemetry arrived without an active turn.')
     if (event === 'policy') return this.hooks.policy(run, String(data.tool), data.args ?? {})
+    if (event === 'questions') {
+      if (!Array.isArray(data.questions) || !data.questions.length || data.questions.length > 5) throw new HarnessError('invalid_request', 'Ask between one and five questions.')
+      const questions = (data.questions as QuestionInput[]).map(question => ({ ...question, requestId: randomUUID() }))
+      return run.requestAnswers(questions)
+    }
     if (event === 'approval' || event === 'question') {
-      const key = this.requestId(String(data.requestId ?? JSON.stringify(data)))
+      const key = this.requestId(`${event}:${String(data.requestId ?? JSON.stringify(data))}`)
       const existing = this.seen.get(key)
       if (existing) return event === 'approval' ? { decision: await existing } : existing
       if (event === 'question') {
         const response: Promise<QuestionAnswer> = run.requestAnswer({ requestId: key, question: String(data.question ?? ''), options: data.options ?? [], multiSelect: !!data.multiSelect, allowText: true })
+        this.pending.set(key, { type: 'question', requestId: key, question: String(data.question ?? ''), options: data.options ?? [], multiSelect: !!data.multiSelect })
         this.seen.set(key, response)
-        return response
+        return response.finally(() => this.pending.delete(key))
       }
       const response: Promise<ApprovalDecision> = run.requestApproval({
         requestId: key,
@@ -198,8 +320,13 @@ export class TerminalController {
         operation: { tool: String(data.tool ?? data.target), args: data.args ?? {} },
         rememberable: false
       })
+      this.pending.set(key, { type: 'approval', requestId: key, target: String(data.target ?? 'Action'), action: String(data.action ?? '{}') })
       this.seen.set(key, response)
-      return { decision: await response }
+      try {
+        return { decision: await response }
+      } finally {
+        this.pending.delete(key)
+      }
     }
     if (event === 'usage') run.emit('usage.updated', data)
     else if (event === 'file') run.emit('file.changed', data)