@xingular/harness 0.0.0-stage → 0.1.0

package/src/terminal/controller.ts

@@ -0,0 +1,227 @@
+// One `pi` command running in a terminal, as the harness sees it. The terminal itself belongs
+// to whoever embeds the harness; this follows the native process through its extension's
+// telemetry (never by reading the screen), turns each native turn into a run, and answers the
+// extension's questions about policy, approvals, and what to do next.
+import { createHash, randomUUID } from 'node:crypto'
+
+import { HarnessError } from '../core/errors'
+import type { ActiveRun, ApprovalDecision, QuestionAnswer } from '../sessions/registry'
+
+export interface PolicyReply {
+  allowed: boolean
+  reason?: string | null
+  requiresApproval?: boolean
+}
+
+export interface ControllerHooks {
+  sessionId: string
+  nativeSessionId: string | null
+  /** Reserves or creates the run for a native turn and starts tracking it. */
+  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>
+  /** The native conversation identity changed. */
+  native(nativeSessionId: string): void
+  telemetry(event: string): void
+}
+
+interface Delivery {
+  runId: string
+  text: string
+  resolve: () => void
+  reject: (error: Error) => void
+}
+
+type Command = { type: 'interrupt' } | { type: 'send'; text: string }
+
+const READY_TIMEOUT_MS = 90_000
+const ACK_TIMEOUT_MS = 25_000
+
+export class TerminalController {
+  private run: ActiveRun | null = null
+  private ready = false
+  private disposed = false
+  private dirty = false
+  private multilineDraft = false
+  private startupError: string | null = null
+  private startupPhase = 'Waiting for the native extension'
+  private delivery: Delivery | null = null
+  private nativeId: string | null
+  private readonly seen = new Map<string, Promise<unknown>>()
+  private readonly commands: Command[] = []
+
+  constructor(private readonly hooks: ControllerHooks) {
+    this.nativeId = hooks.nativeSessionId
+  }
+
+  get nativeSessionId(): string | null {
+    return this.nativeId
+  }
+
+  get activeRun(): ActiveRun | null {
+    return this.run && !this.run.finished ? this.run : null
+  }
+
+  state(): { ready: boolean; dirty: boolean; active: boolean } {
+    return { ready: this.ready, dirty: this.dirty, active: !!this.activeRun || !!this.delivery }
+  }
+
+  private requestId(nativeId: string): string {
+    return createHash('sha256').update(`${this.hooks.sessionId}:${this.run?.runId}:${nativeId}`).digest('hex')
+  }
+
+  private begin(nativeTurnId: string, text: string): ActiveRun {
+    if (this.startupError) throw new Error(this.startupError)
+    this.dirty = false
+    this.multilineDraft = false
+    if (this.run && !this.run.finished) return this.run
+    const delivery = this.delivery
+    if (delivery && text && delivery.text !== text) throw new Error('The native prompt did not match the reserved delivery. Inspect the terminal before continuing.')
+    const run = this.hooks.begin({ reservedRunId: delivery?.runId ?? null, nativeTurnId, text })
+    this.run = run
+    run.onInterrupt(() => void this.commands.push({ type: 'interrupt' }))
+    if (text) run.emit('message.completed', { messageId: nativeTurnId, role: 'user', text })
+    delivery?.resolve()
+    this.delivery = null
+    return run
+  }
+
+  private finish(outcome: 'completed' | 'failed' | 'interrupted', message?: string): void {
+    this.run?.finish(outcome, message ? { code: 'terminal_attention', message } : undefined)
+    this.run = null
+    this.seen.clear()
+  }
+
+  /** Hands the native process an instruction and waits until it acknowledges the prompt. */
+  async send(runId: string, text: string): Promise<void> {
+    if (this.disposed) throw new HarnessError('terminal_not_ready', 'Reopen the terminal before sending instructions.')
+    if (this.activeRun || this.delivery) throw new HarnessError('session_busy', 'This terminal has an active task or delivery.')
+    const deadline = Date.now() + READY_TIMEOUT_MS
+    while (!this.ready && !this.startupError && !this.disposed && Date.now() < deadline) await new Promise((resolve) => setTimeout(resolve, 50))
+    if (this.disposed) throw new HarnessError('terminal_not_ready', 'The terminal stopped during initialization.')
+    if (this.startupError) throw new HarnessError('terminal_not_ready', this.startupError)
+    if (!this.ready) throw new HarnessError('terminal_not_ready', `The native telemetry handshake is missing (${this.startupPhase}). Inspect the terminal sign-in or trust screen.`)
+    if (this.dirty) throw new HarnessError('terminal_has_draft', 'The terminal contains user input. Submit or clear it before handing back control.')
+    let timer: ReturnType<typeof setTimeout>
+    const ack = new Promise<void>((resolve, reject) => {
+      timer = setTimeout(() => reject(new HarnessError('delivery_uncertain', 'The native prompt acknowledgement was not received. Inspect the terminal; this instruction will not be resent.')), ACK_TIMEOUT_MS)
+      this.delivery = { runId, text, resolve, reject }
+    })
+    // Delivery can fail while the native process is still starting the turn. Observe it immediately.
+    void ack.catch(() => {})
+    try {
+      this.commands.push({ type: 'send', text })
+      await ack
+    } catch (error) {
+      this.ready = false
+      this.startupError = error instanceof Error ? error.message : String(error)
+      this.delivery = null
+      this.commands.length = 0
+      this.commands.push({ type: 'interrupt' })
+      this.finish('failed', this.startupError)
+      throw error
+    } finally {
+      clearTimeout(timer!)
+    }
+  }
+
+  /** What the person typed into the terminal, so an instruction is never sent over their draft. */
+  onInput(data: string): void {
+    if (!this.ready || this.activeRun || data === '\u0003') return
+    if (data.includes('\n') || data.includes('\r')) this.multilineDraft = true
+    this.dirty = data !== '\u0015' || this.multilineDraft
+  }
+
+  /** The native process hung up while it was waiting for a decision. */
+  disconnected(): void {
+    if (this.disposed) return
+    this.ready = false
+    this.commands.push({ type: 'interrupt' })
+    this.finish('failed', 'The native decision callback disconnected. Inspect the terminal before continuing.')
+  }
+
+  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)
+    if (event === 'startup') {
+      this.startupPhase = String(data.phase)
+      return {}
+    }
+    if (event === 'startupFailed') {
+      this.startupError = String(data.reason ?? 'The native extension could not initialize.')
+      this.ready = false
+      this.finish('failed', this.startupError)
+      return {}
+    }
+    if (event === 'poll') return { command: this.commands.shift() ?? null }
+    if (event === 'ready') {
+      if (!this.ready) {
+        this.dirty = false
+        this.multilineDraft = false
+      }
+      this.ready = true
+      if (typeof data.nativeSessionId === 'string' && data.nativeSessionId) {
+        this.nativeId = data.nativeSessionId
+        this.hooks.native(data.nativeSessionId)
+      }
+      return {}
+    }
+    if (event === 'begin') {
+      this.begin(String(data.turnId ?? randomUUID()), String(data.text ?? ''))
+      return {}
+    }
+    if (event === 'shutdown') {
+      this.ready = false
+      this.finish('interrupted')
+      return {}
+    }
+    if (event === 'settled') {
+      this.finish(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 === 'approval' || event === 'question') {
+      const key = this.requestId(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.seen.set(key, response)
+        return response
+      }
+      const response: Promise<ApprovalDecision> = run.requestApproval({
+        requestId: key,
+        target: String(data.target ?? 'Native action'),
+        action: String(data.action ?? '{}'),
+        operation: { tool: String(data.tool ?? data.target), args: data.args ?? {} },
+        rememberable: false
+      })
+      this.seen.set(key, response)
+      return { decision: await response }
+    }
+    if (event === 'usage') run.emit('usage.updated', data)
+    else if (event === 'file') run.emit('file.changed', data)
+    else if (event === 'message') run.emit('message.completed', { messageId: data.id ?? randomUUID(), role: data.role ?? 'assistant', text: String(data.text) })
+    else if (event === 'tool') {
+      run.emit(data.phase === 'start' ? 'tool.started' : 'tool.completed', {
+        toolCallId: String(data.id),
+        name: String(data.name),
+        ...(data.phase === 'start'
+          ? { summary: String(data.summary ?? '') }
+          : { ok: data.ok !== false, ...(typeof data.durationMs === 'number' ? { durationMs: data.durationMs } : {}), ...(typeof data.resultChars === 'number' ? { resultChars: data.resultChars } : {}) })
+      })
+    }
+    return {}
+  }
+
+  dispose(): void {
+    if (this.disposed) return
+    this.disposed = true
+    this.ready = false
+    this.delivery?.reject(new Error('The terminal stopped before prompt acknowledgement.'))
+    this.delivery = null
+    this.finish('interrupted')
+  }
+}

package/src/terminal/piExtension.ts

@@ -0,0 +1,208 @@
+// Loaded by the `pi` command in a terminal session (`--extension`). It reports what the native
+// session does to the harness, asks before each tool call, takes instructions the harness
+// queues for it, and gives the session the harness's own tools. It runs in the `pi` process,
+// so everything it knows about the harness comes through the session socket.
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
+import { Type } from 'typebox'
+
+import { connectionFromEnv, socketCall, terminalCall } from './client'
+import { runPluginsMenu } from './pluginMenu'
+
+interface SocketTool {
+  name: string
+  label: string
+  description: string
+  parameters: Record<string, unknown>
+}
+
+/** How much text a tool handed back to the model. */
+function resultSize(result: unknown): number | null {
+  const content = (result as { content?: unknown } | null | undefined)?.content
+  if (!Array.isArray(content)) return typeof result === 'string' ? result.length : null
+  return content.reduce((total: number, part: { type?: string; text?: unknown }) => total + (part?.type === 'text' && typeof part.text === 'string' ? part.text.length : 0), 0)
+}
+
+export default async function (pi: ExtensionAPI) {
+  await terminalCall('startup', { phase: 'Pi extension loaded' })
+  let context: ExtensionContext | null = null
+  let timer: ReturnType<typeof setInterval> | null = null
+  let polling = false
+  let failure: string | undefined
+  const emptyUsage = () => ({ inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, requests: 0, costUsd: 0 })
+  let usage = emptyUsage()
+  let reasoningTokens: number | undefined
+  let costReported = false
+  let requestStartedAt: number | null = null
+  const toolStartedAt = new Map<string, number>()
+  const fileTools = new Map<string, string>()
+
+  // The harness's own tools for this session (connected apps and what the application offers).
+  let stage = 'Tool discovery'
+  try {
+    await terminalCall('startup', { phase: stage })
+    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)
+    pi.registerCommand('plugins', {
+      description: 'See what this session loads, and switch a plugin on or off or trust its code',
+      handler: async (_args, ctx) => {
+        if (!control) return ctx.ui.notify('This session cannot change plugins.', 'warning')
+        const { projectId } = await socketCall<{ projectId: string | null }>(connection, 'plugins.session', {}, 15_000, control).catch(() => ({ projectId: null }))
+        await runPluginsMenu(
+          { 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 ?? {}, 60_000, control),
+          projectId
+        )
+      }
+    })
+    const { tools } = await socketCall<{ tools: SocketTool[] }>(connection, 'tools.list', {}, 15_000)
+    stage = 'Tool registration'
+    for (const tool of tools) {
+      pi.registerTool({
+        name: tool.name,
+        label: tool.label,
+        description: tool.description,
+        parameters: Type.Unsafe(tool.parameters),
+        async execute(_id, input) {
+          const result = await socketCall<{ text: string }>(connection, 'tools.call', { name: tool.name, input: input as Record<string, unknown> }, 1_230_000)
+          return { content: [{ type: 'text', text: result.text }], details: undefined }
+        }
+      })
+    }
+  } catch (error) {
+    await terminalCall('startupFailed', { reason: `${stage} failed: ${error instanceof Error ? error.message : 'Unavailable'}` }).catch(() => {})
+    throw error
+  }
+
+  pi.on('session_start', async (_event, ctx) => {
+    context = ctx
+    await terminalCall('ready', { nativeSessionId: ctx.sessionManager.getSessionFile() })
+    timer = setInterval(() => {
+      if (polling || !context) return
+      polling = true
+      void terminalCall<{ command: { type: string; text?: string } | null }>('poll', {}, 5_000)
+        .then(({ command }) => {
+          if (command?.type === 'interrupt') context?.abort()
+          else if (command?.type === 'send') {
+            if (context?.ui.getEditorText().trim()) throw new Error('The terminal contains a user draft.')
+            pi.sendUserMessage(command.text!)
+          }
+        })
+        .catch(() => {
+          context?.abort()
+          if (timer) clearInterval(timer)
+        })
+        .finally(() => {
+          polling = false
+        })
+    }, 100)
+  })
+  pi.on('before_agent_start', async (event, ctx) => {
+    context = ctx
+    failure = undefined
+    usage = emptyUsage()
+    reasoningTokens = undefined
+    costReported = false
+    await terminalCall('begin', { text: event.prompt })
+  })
+  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}`
+    const text = event.message.content.filter((part) => part.type === 'text').map((part) => part.text).join('\n')
+    if (text) await terminalCall('message', { text })
+    if (event.message.usage) {
+      const reported = event.message.usage
+      usage.inputTokens += reported.input ?? 0
+      usage.outputTokens += reported.output ?? 0
+      usage.cacheReadTokens += reported.cacheRead ?? 0
+      usage.cacheWriteTokens += reported.cacheWrite ?? 0
+      usage.requests += 1
+      if (typeof reported.reasoning === 'number') reasoningTokens = (reasoningTokens ?? 0) + reported.reasoning
+      const cost = reported.cost?.total
+      if (typeof cost === 'number') {
+        usage.costUsd += cost
+        costReported = true
+      }
+      const identity = { model: event.message.model, provider: event.message.provider }
+      const { costUsd, ...tokens } = usage
+      await terminalCall('usage', {
+        ...tokens,
+        ...(costReported ? { costUsd, costSource: 'harness' } : {}),
+        ...(reasoningTokens === undefined ? {} : { reasoningTokens }),
+        contextTokens: (reported.input ?? 0) + (reported.cacheRead ?? 0) + (reported.cacheWrite ?? 0),
+        ...(context?.model?.contextWindow ? { contextWindow: context.model.contextWindow } : {}),
+        ...identity,
+        request: {
+          index: usage.requests,
+          ...identity,
+          responseId: event.message.responseId,
+          inputTokens: reported.input ?? 0,
+          cacheReadTokens: reported.cacheRead ?? 0,
+          cacheWriteTokens: reported.cacheWrite ?? 0,
+          outputTokens: reported.output ?? 0,
+          ...(typeof reported.reasoning === 'number' ? { reasoningTokens: reported.reasoning } : {}),
+          ...(typeof cost === 'number' ? { costUsd: cost, costSource: 'harness' } : {}),
+          ...(requestStartedAt === null ? {} : { durationMs: Date.now() - requestStartedAt }),
+          stopReason: event.message.stopReason
+        }
+      })
+      requestStartedAt = null
+    }
+  })
+  pi.on('turn_start', async () => {
+    requestStartedAt = Date.now()
+  })
+  pi.on('tool_call', async (event) => {
+    try {
+      const policy = await terminalCall<{ allowed: boolean; reason?: string; requiresApproval?: boolean }>('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 })
+        if (approval.decision === 'approved') return
+        return { block: true, reason: 'The user denied this action. Ask how they would like to proceed.' }
+      }
+      if (!policy.allowed) return { block: true, reason: policy.reason ?? 'Outside what this session may do.' }
+    } catch {
+      return { block: true, reason: 'The terminal controller is unavailable.' }
+    }
+  })
+  pi.on('tool_execution_start', async (event) => {
+    if (['edit', 'write'].includes(event.toolName) && typeof event.args.path === 'string') fileTools.set(event.toolCallId, event.args.path)
+    toolStartedAt.set(event.toolCallId, Date.now())
+    await terminalCall('tool', { phase: 'start', id: event.toolCallId, name: event.toolName, summary: JSON.stringify(event.args).slice(0, 200) })
+  })
+  pi.on('tool_execution_end', async (event) => {
+    const started = toolStartedAt.get(event.toolCallId)
+    toolStartedAt.delete(event.toolCallId)
+    const resultChars = resultSize(event.result)
+    await terminalCall('tool', { phase: 'end', id: event.toolCallId, name: event.toolName, ok: !event.isError, ...(started === undefined ? {} : { durationMs: Date.now() - started }), ...(resultChars === null ? {} : { resultChars }) })
+    const path = fileTools.get(event.toolCallId)
+    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('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)
+    await terminalCall('shutdown').catch(() => {})
+  })
+  pi.registerTool({
+    name: 'ask_user_question',
+    label: 'Ask a question',
+    description: 'Ask the user a question and wait for their answer.',
+    parameters: Type.Object({
+      question: Type.String(),
+      options: Type.Optional(Type.Array(Type.Object({ label: Type.String(), description: Type.Optional(Type.String()) }))),
+      multiSelect: Type.Optional(Type.Boolean())
+    }),
+    async execute(id, input) {
+      const answer = await terminalCall('question', { requestId: id, ...input })
+      return { content: [{ type: 'text', text: JSON.stringify(answer) }], details: undefined }
+    }
+  })
+  await terminalCall('startup', { phase: 'Pi hooks registered' })
+}

package/src/terminal/pluginControl.test.ts

@@ -0,0 +1,146 @@
+import { existsSync, mkdtempSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { memorySecretStore } from '../accounts/secrets'
+import { createHarness, type Harness } from '../harness'
+import { runPluginsCli } from '../plugins/cli'
+import type { Plugin } from '../plugins/types'
+import { rootWithProject, writeFile } from '../../tests/helpers'
+import { SOCKET_ENV, TOKEN_ENV, socketCall, type SocketConnection } from './client'
+import { menuRows, rowActions, runPluginsMenu, type MenuUi } from './pluginMenu'
+
+const open: Harness[] = []
+afterEach(async () => {
+  for (const harness of open.splice(0)) await harness.close()
+})
+
+function kit(folder: string): void {
+  writeFile(join(folder, 'package.json'), JSON.stringify({ name: 'review-kit', description: 'Review helpers.', version: '1.0.0' }))
+  writeFile(join(folder, 'extensions/guard.ts'), 'export default function () {}\n')
+  writeFile(join(folder, 'skills/audit/SKILL.md'), '---\nname: audit\ndescription: Audit a change.\n---\nSteps.\n')
+}
+
+async function session() {
+  const root = rootWithProject()
+  const base = mkdtempSync(join(tmpdir(), 'control-'))
+  writeFile(join(root, 'registry/rules/tests.md'), '---\nname: Run tests\ndescription: Always test.\n---\nAlways run the tests.\n')
+  const harness = createHarness({ dataRoot: root, stateDir: join(base, 'state'), secrets: memorySecretStore(), piProgram: () => '/opt/pi/bin/pi', assets: { node: '/opt/node', cli: '/opt/harness/cli.js', piExtension: '/opt/harness/terminal-pi.js' } })
+  open.push(harness)
+  const account = harness.accounts.create('Main', 'apiKey').accounts[0]
+  harness.plugins.trust.adopt([])
+  kit(join(root, 'plugins/review-kit'))
+  const launch = await harness.terminals.prepare({ sessionId: 'term-1', accountId: account.id, projectId: 'p1', cwd: base, sessionFolder: join(root, 'sessions', 'p1', 'term-1') })
+  const connection: SocketConnection = { socket: String(launch.env[SOCKET_ENV]), token: String(launch.env[TOKEN_ENV]) }
+  return { harness, root, base, connection }
+}
+
+/** A person at the terminal, answering each dialog in turn from a script. */
+function person(answers: (string | boolean | undefined)[]) {
+  const shown: string[] = []
+  const said: string[] = []
+  const ui: MenuUi = {
+    select: async (title, options) => {
+      shown.push(`${title} → ${options.join(' | ')}`)
+      return answers.shift() as string | undefined
+    },
+    confirm: async (title, message) => {
+      shown.push(`${title} ${message}`)
+      return answers.shift() === true
+    },
+    notify: (message) => void said.push(message)
+  }
+  return { ui, shown, said }
+}
+
+describe('plugin control from a terminal session', () => {
+  it("lists for anyone in the session, and changes only for the session's own extension", async () => {
+    const { connection } = await session()
+    const listed = await socketCall<Plugin[]>(connection, 'plugins.list')
+    const plugin = listed.find((candidate) => candidate.id === 'package:review-kit')!
+    expect(plugin).toMatchObject({ trust: 'untrusted' })
+    // A command the model runs in the shell has the session token and nothing more.
+    await expect(socketCall(connection, 'plugins.trust', { hash: plugin.code!.hash })).rejects.toThrow('Only a person at this terminal can change plugins')
+    await expect(socketCall(connection, 'plugins.detach', { id: plugin.id })).rejects.toThrow('Only a person at this terminal')
+    await expect(socketCall(connection, 'plugins.trust', { hash: plugin.code!.hash }, 5_000, 'guessed')).rejects.toThrow('Only a person at this terminal')
+
+    // The extension claims the key as it loads. It is given out once.
+    const { key } = await socketCall<{ key: string }>(connection, 'control.claim')
+    await expect(socketCall(connection, 'control.claim')).rejects.toThrow('already claimed')
+    const trusted = await socketCall<Plugin[]>(connection, 'plugins.trust', { hash: plugin.code!.hash }, 5_000, key)
+    expect(trusted.find((candidate) => candidate.id === plugin.id)).toMatchObject({ trust: 'trusted' })
+    // Without "everywhere", a switch from a terminal is for the session's project.
+    const off = await socketCall<Plugin[]>(connection, 'plugins.detach', { id: plugin.id }, 5_000, key)
+    expect(off.find((candidate) => candidate.id === plugin.id)!.attachment).toEqual({ global: true, on: { agentIds: [], projectIds: [] }, off: { agentIds: [], projectIds: ['p1'] } })
+  })
+
+  it('walks a person through switching and trusting, and changes nothing they did not choose', async () => {
+    const { harness, connection } = await session()
+    const { key } = await socketCall<{ key: string }>(connection, 'control.claim')
+    const call = <T>(method: string, params?: Record<string, unknown>) => socketCall<T>(connection, method, params ?? {}, 5_000, key)
+    const rows = menuRows(await call<Plugin[]>('plugins.list'), 'p1')
+    expect(rows.map((row) => row.label)).toEqual(['● review-kit · code not trusted', '○ Run tests · instruction in Yours', '○ Budget guard · runs code', '○ Output trim · runs code'])
+    expect(rowActions(rows[0], 'p1')).toEqual(['Switch off for this project', 'Switch off everywhere', 'Trust its code', 'Back'])
+    expect(rowActions(rows[1], null)).toEqual(['Switch on everywhere', 'Back'])
+    // A part that ships with the harness needs no trust: it is the harness's own code.
+    expect(rowActions(rows[2], 'p1')).toEqual(['Switch on for this project', 'Switch on everywhere', 'Back'])
+
+    // Declining the trust question leaves the code untrusted; then they trust it, switch a rule on, and leave.
+    const { ui, shown, said } = person(['● review-kit · code not trusted', 'Trust its code', false, '● review-kit · code not trusted', 'Trust its code', true, '○ Run tests · instruction in Yours', 'Switch on for this project', 'Done'])
+    await runPluginsMenu(ui, call, 'p1')
+    expect(shown.find((line) => line.startsWith('Trust this code?'))).toContain('extensions/guard.ts')
+    expect(shown.find((line) => line.startsWith('Trust this code?'))).toContain('can do anything this app can')
+    expect(said).toEqual(['Saved. It applies when this session restarts.'])
+    const after = await call<Plugin[]>('plugins.list')
+    expect(after.find((plugin) => plugin.id === 'package:review-kit')).toMatchObject({ trust: 'trusted' })
+    expect(after.flatMap((plugin) => plugin.contributions).find((entry) => entry.id === 'yours/rules/tests')).toMatchObject({ state: 'on', scope: 'App' })
+    expect(harness.plugins.trust.list()).toHaveLength(1)
+
+    // Leaving at once changes nothing and says nothing.
+    const idle = person([undefined])
+    await runPluginsMenu(idle.ui, call, 'p1')
+    expect(idle.said).toEqual([])
+  })
+})
+
+describe('the plugins command', () => {
+  it('lists, installs, switches, trusts only on a yes, and removes, on its own data', async () => {
+    const base = mkdtempSync(join(tmpdir(), 'plugins-cli-'))
+    kit(join(base, 'kit'))
+    const lines: string[] = []
+    const run = (argv: string[], answer?: string) => runPluginsCli([...argv, '--data', join(base, 'data'), '--state', join(base, 'state')], { home: base, cwd: base, write: (text) => void lines.push(text), ...(answer === undefined ? {} : { ask: async () => answer }) })
+    const last = (): string => lines.at(-1) ?? ''
+
+    expect(await run(['list'])).toBe(0)
+    expect(last()).toMatch(/^memory\s+required\s+Memory$/m)
+    expect(await run(['install', join(base, 'kit')])).toBe(0)
+    expect(last()).toContain('Installed, switched off.')
+    expect(last()).toContain('trust its code with "plugins trust <id>"')
+    expect(await run(['list'])).toBe(0)
+    expect(last()).toMatch(/^package:review-kit\s+off, code not trusted\s+review-kit$/m)
+
+    expect(await run(['attach', 'package:review-kit'])).toBe(0)
+    expect(last()).toBe('package:review-kit is on everywhere. It applies from the next session start.\n')
+    // No terminal to ask on and no --yes: the files are shown and nothing is trusted.
+    expect(await run(['trust', 'package:review-kit'])).toBe(1)
+    expect(lines.at(-2)).toContain('extensions/guard.ts')
+    expect(last()).toBe('Read the files, then run this again with --yes to trust them.\n')
+    expect(await run(['trust', 'package:review-kit'], 'no')).toBe(1)
+    expect(last()).toBe('Not trusted.\n')
+    expect(await run(['trust', 'package:review-kit'], 'yes')).toBe(0)
+    expect(await run(['show', 'package:review-kit'])).toBe(0)
+    expect(last()).toContain('State: on')
+    expect(last()).toContain('Code (trusted)')
+    expect(last()).toContain('● skill audit (package:review-kit/skill/audit)')
+
+    expect(await run(['detach', 'memory'])).toBe(1)
+    expect(last()).toContain('Memory cannot be switched off.')
+    expect(await run(['untrust', 'package:review-kit'])).toBe(0)
+    expect(await run(['remove', 'package:review-kit'])).toBe(0)
+    expect(await run(['show', 'package:review-kit'])).toBe(1)
+    expect(await run(['nonsense'])).toBe(2)
+    // The folder that was installed in place is still the person's.
+    expect(existsSync(join(base, 'kit/package.json'))).toBe(true)
+  })
+})