@xingular/harness 0.1.5 → 0.1.7

package/src/sessions/runner.ts

@@ -84,6 +84,10 @@ export interface PiSessionLike {
   getAllTools?(): Array<{ name: string; description?: string; parameters?: unknown }>
   subscribe(listener: (event: PiEvent) => void): () => void
   prompt(text: string, options?: { images?: unknown[] }): Promise<void>
+  /** Queues a message for the model after the current step. Resolves `handled` when Pi takes it without queueing. */
+  steer?(text: string): Promise<'handled' | 'queued'>
+  /** Drops queued messages Pi has not delivered. */
+  clearQueue?(): unknown
   sendCustomMessage?(message: { customType: string; content: string; display: boolean; details: unknown }, options: { triggerTurn: boolean }): Promise<void>
   abort(): Promise<void>
   dispose(): void
@@ -255,11 +259,35 @@ export async function runTurn(run: ActiveRun, session: PiSessionLike, params: Tu
     await session.abort()
   })
 
+  // Steers handed to Pi and not yet delivered, oldest first. Pi delivers them in that order, after
+  // the prompt's own user message, which is the first user message it starts.
+  const pendingSteers: string[] = []
+  let accepting = false
+  let promptStarted = false
+  const forgetSteer = (text: string): void => {
+    const index = pendingSteers.lastIndexOf(text)
+    if (index >= 0) pendingSteers.splice(index, 1)
+  }
+  run.onSteer(async (text) => {
+    if (!accepting || !session.steer) throw new HarnessError('run_not_active', 'This reply is not accepting messages.')
+    pendingSteers.push(text)
+    try {
+      if ((await session.steer(text)) === 'handled') forgetSteer(text)
+    } catch (error) {
+      forgetSteer(text)
+      throw error
+    }
+  })
+
   const unsubscribe = session.subscribe((event) => {
     switch (event.type) {
       case 'message_start': {
         const { message } = event as Extract<PiEvent, { type: 'message_start' }>
         if (message.role === 'assistant') currentMessageId = `${run.runId}:m${messageIndex++}`
+        else if (message.role === 'user' && promptStarted) {
+          const text = pendingSteers.shift()
+          if (text !== undefined) run.emit('message.steered', { text })
+        } else if (message.role === 'user') promptStarted = true
         break
       }
       case 'turn_start': {
@@ -424,7 +452,14 @@ export async function runTurn(run: ActiveRun, session: PiSessionLike, params: Tu
     }
     const prompt = params.preamble && !extensionCommand ? `${params.preamble}\n\n${params.text}` : params.text
     const images = (params.images ?? []).map((image) => ({ type: 'image', mimeType: image.mediaType, data: image.data }))
-    await session.prompt(prompt, images.length ? { images } : undefined)
+    accepting = true
+    try {
+      await session.prompt(prompt, images.length ? { images } : undefined)
+    } finally {
+      // A message Pi has not delivered by now never will be; the caller sends it again as a new reply.
+      accepting = false
+      session.clearQueue?.()
+    }
     if (aborted) run.finish('interrupted')
     else if (lastError) run.finish('failed', { code: 'provider_error', message: lastError })
     else run.finish('completed')

package/src/sessions/sessions.test.ts

@@ -326,6 +326,36 @@ describe('session turns on Pi', () => {
     expect(events.at(-1)?.type).toBe('completed')
   })
 
+  it('asks a person for a humanOnly call even when the tool was remembered', async () => {
+    let blockReason: string | null | undefined
+    const policy: ToolPolicy = { scope: async () => ({ allowed: false, requiresApproval: true, humanOnly: true, reason: 'Run this command?' }) }
+    const { events, run, harness } = setup(async ({ gate }) => fakeSession(async (_emit, check) => void (blockReason = await check()), gate), policy)
+    harness.approvals.remember('agent-1', 'bash')
+    harness.approvals.setAuto('chat', true)
+    await run('run-human', { text: 'npm install' })
+    await tick()
+    const requested = events.find((event) => event.type === 'approval.requested')!.payload as { approvalId: string }
+    expect(requested).toMatchObject({ target: 'bash', rememberable: false })
+    expect(requested).not.toHaveProperty('automatic')
+    expect(events.some((event) => event.type === 'status.changed' && (event.payload as { status: string }).status === 'waiting_for_approval')).toBe(true)
+    harness.runs.resolveApproval('run-human', requested.approvalId, 'approved')
+    await tick()
+    expect(blockReason).toBeNull()
+  })
+
+  it('lets the Agent chat switch approve humanOnly calls without remembering the tool', async () => {
+    let blockReason: string | null | undefined
+    const policy: ToolPolicy = { scope: async () => ({ allowed: false, requiresApproval: true, humanOnly: true, allowGlobalApproval: true, reason: 'Run this command?' }) }
+    const { events, run, harness } = setup(async ({ gate }) => fakeSession(async (_emit, check) => void (blockReason = await check()), gate), policy)
+    harness.approvals.setAuto('chat', true)
+    await run('run-human-auto', { text: 'run command' })
+    await tick()
+    expect(blockReason).toBeNull()
+    expect(events.find((event) => event.type === 'approval.requested')?.payload).toMatchObject({ target: 'bash', rememberable: false, automatic: 'always' })
+    expect(events.find((event) => event.type === 'approval.resolved')?.payload).toMatchObject({ decision: 'approved', automatic: 'always' })
+    expect(events.some((event) => event.type === 'status.changed' && (event.payload as { status: string }).status === 'waiting_for_approval')).toBe(false)
+  })
+
   it('still asks when the application cannot say what is allowed', async () => {
     const { events, run } = setup(async ({ gate }) => fakeSession(async (_emit, check) => void (await check()), gate), { approval: async () => { throw new Error('down') } })
     await run('run-ask', { text: 'list files' })
@@ -344,14 +374,32 @@ describe('session turns on Pi', () => {
         if (authorized > 1) throw new Error('Tool unavailable in the app settings.')
       }
     }
-    const { run } = setup(async ({ gate }) => fakeSession(async () => {
+    const { run, harness } = setup(async ({ gate }) => fakeSession(async () => {
       reasons.push(await gate.check('bash', {}), await gate.check('read', {}), await gate.check('read', {}))
     }, gate), policy)
+    harness.approvals.setAuto('chat', true)
     await run('run-scope')
     await tick()
     expect(reasons).toEqual(['Scheduled workers may use scoped file tools only.', null, 'Tool unavailable in the app settings.'])
   })
 
+  it('forwards opaque caller policy context to the application tool policy', async () => {
+    const contexts: unknown[] = []
+    const policy: ToolPolicy = {
+      scope: async ({ caller }) => {
+        contexts.push(caller.policyContext)
+        return { allowed: true }
+      }
+    }
+    const { run } = setup(async ({ gate }) => fakeSession(async (_emit, check) => void (await check()), gate), policy)
+    const policyContext = { delegatesTo: ['worker-1'], snapshot: 'run-start' }
+    await run('run-policy-context', {
+      caller: { agentId: 'agent-1', agentName: 'Helper', actor: 'Chat', policyContext }
+    })
+    await tick()
+    expect(contexts).toEqual([policyContext])
+  })
+
   it('aborts the Pi session on interrupt', async () => {
     let session: (PiSessionLike & { aborted: boolean }) | null = null
     const { events, run, harness } = setup(async ({ gate }) => (session = fakeSession(() => new Promise((resolve) => setTimeout(resolve, 50)), gate)))
@@ -438,6 +486,52 @@ describe('history selection', () => {
   })
 })
 
+describe('subagents', () => {
+  it('starts a child run of the same caller with no more tools than its parent, and returns its result', async () => {
+    const seen = new Map<string, { allow: string[]; tools: string[]; depth: string | null }>()
+    let parentResult: unknown = null
+    const { harness, run } = setup(async ({ gate, params, allow, tools }) => {
+      seen.set(params.runId, { allow: [...allow], tools: tools.map((tool) => tool.name), depth: null })
+      return fakeSession(async (emit) => {
+        if (params.runId === 'parent') {
+          const spawn = tools.find((tool) => tool.name === 'spawn_subagent')!
+          expect(await spawn.execute({ brief: 'Find the bug', tools: ['bash', 'web'] })).toMatch(/cannot have tools you do not have: web/)
+          parentResult = await spawn.execute({ brief: 'Find the bug', tools: ['read'] })
+          return
+        }
+        emit({ type: 'message_start', message: { role: 'assistant' } })
+        emit({ type: 'message_end', message: { role: 'assistant', content: [{ type: 'text', text: 'Found it in parser.ts' }] } })
+      }, gate)
+    })
+    await run('parent', { subagents: { maxDepth: 1 } })
+    for (let attempt = 0; attempt < 50 && !parentResult; attempt++) await tick()
+    expect(parentResult).toMatch(/Subagent run .* · completed\nResult:\nFound it in parser.ts/)
+    expect(seen.get('parent')!.allow).toContain('spawn_subagent')
+    const [childId] = [...seen.keys()].filter((id) => id !== 'parent')
+    const child = seen.get(childId)!
+    expect(child.allow).toContain('read')
+    expect(child.allow).not.toContain('bash')
+    // At the depth limit the child cannot start subagents of its own.
+    expect(child.allow).not.toContain('spawn_subagent')
+    expect(loadRun(harness.env.root, childId)).toMatchObject({ parentRunId: 'parent', relation: 'subagent', agentId: 'agent-1', status: 'completed' })
+  })
+
+  it('offers no subagent tool unless the caller asks for it, and can run without the application\'s tool providers', async () => {
+    const offered: string[][] = []
+    const { harness, run } = setup(async ({ gate, tools }) => {
+      offered.push(tools.map((tool) => tool.name))
+      return fakeSession(async () => undefined, gate)
+    })
+    harness.sessions.provide(() => [{ name: 'app_tool', label: 'App', description: 'An app tool', parameters: (Type) => Type.Object({}), execute: async () => 'ok' }])
+    await run('plain', { tools: { allow: ['app_tool'] } })
+    await run('solo', { tools: { allow: ['app_tool'] }, providers: false })
+    await tick()
+    expect(offered[0]).toContain('app_tool')
+    expect(offered[0]).not.toContain('spawn_subagent')
+    expect(offered[1]).not.toContain('app_tool')
+  })
+})
+
 describe('standing approvals', () => {
   const policy = { auto: { pi: true }, remembered: { 'pane-1': ['shell'] } }
   const facts = (unattended: boolean, readOnly: boolean): ApprovalFacts => ({ unattended, readOnly })

package/src/sessions/sessions.ts

@@ -21,6 +21,7 @@ import { FIRST_PARTY_PLUGINS, firstPartyExtensions, type InlineExtension } from
 import * as registry from '../skills/registry'
 import { ASK_USER, askUserTool } from '../tools/askUser'
 import { PLUGIN_PROPOSE, pluginProposeTool } from '../tools/pluginPropose'
+import { SPAWN_SUBAGENT, SUBAGENT_RELATION, spawnSubagentTool, subagentDepth, type SubagentOptions } from '../tools/spawnSubagent'
 import { WIKI_TOOL_NAMES } from '../tools/definitions'
 import { memoryTools } from '../tools/memoryTools'
 import type { ToolProvider, ToolSession, ToolSpec } from '../tools/types'
@@ -66,6 +67,10 @@ export interface SessionRunInput {
   capabilities?: CapabilitySet
   /** Hops from the user to this session (0 when the user started it). */
   depth?: number
+  /** Offer `spawn_subagent`: the model may start child runs of this caller, up to this depth. */
+  subagents?: SubagentOptions | null
+  /** Ask the application's tool providers for tools (the default). False runs with the harness's own tools only. */
+  providers?: boolean
 }
 
 /** The connected-apps broker, as a session sees it. */
@@ -126,9 +131,15 @@ export class Sessions {
         } catch (error) {
           return error instanceof Error ? error.message : 'Tool unavailable in the app settings.'
         }
-        if (scope.allowed && (scope.automatic || !gated.has(tool))) return null
-        // A call outside the scope is approved one at a time; a gated tool may be remembered.
-        const decision = await run.requestApproval({ target: tool, action: summarize(args), operation: { tool, args: (args && typeof args === 'object' ? args : {}) as Record<string, unknown> }, rememberable: scope.allowed })
+        if (scope.allowed && !scope.humanOnly && (scope.automatic || !gated.has(tool))) return null
+        // A call outside the scope is approved one at a time; a gated tool may be remembered, unless only a person may decide it.
+        const decision = await run.requestApproval({
+          target: tool,
+          action: summarize(args),
+          operation: { tool, args: (args && typeof args === 'object' ? args : {}) as Record<string, unknown> },
+          rememberable: scope.allowed && !scope.humanOnly,
+          standing: scope.humanOnly ? (scope.allowGlobalApproval ? 'switch' : 'none') : undefined
+        })
         if (decision !== 'approved') return 'The user denied this action. Ask how they would like to proceed.'
         try {
           await policy.authorize?.(call)
@@ -140,6 +151,35 @@ export class Sessions {
     }
   }
 
+  /** `spawn_subagent` for a run: each child is this caller again, one hop deeper, with no more tools than the parent. */
+  private subagentTool(input: SessionRunInput, runId: string, accountId: string, parent: CapabilitySet): ToolSpec {
+    const parentTools = parent.tools.filter((name) => name !== SPAWN_SUBAGENT)
+    return spawnSubagentTool({
+      root: this.env.root,
+      parentRunId: runId,
+      parentSessionId: input.run.sessionId,
+      parentTools,
+      sessionDir: input.sessionDir,
+      start: (child) => this.run({
+        ...input,
+        run: { ...input.run, id: child.runId, sessionId: child.sessionId, parentRunId: runId, relation: SUBAGENT_RELATION, goal: takeChars(child.brief, 4000), resumedFromRunId: null, handoffId: null },
+        accountId,
+        poolId: null,
+        sessionDir: child.sessionDir,
+        resume: null,
+        text: child.brief,
+        images: undefined,
+        requiresImageInput: false,
+        preamble: null,
+        caller: { ...input.caller, runId: undefined, sessionId: child.sessionId },
+        tools: { allow: [...child.tools, SPAWN_SUBAGENT], gated: (input.tools.gated ?? []).filter((name) => child.tools.includes(name)) },
+        // Never wider than the parent's frozen set; the session intersects it with what is available now.
+        capabilities: { ...parent, tools: [...parent.tools.filter((name) => child.tools.includes(name)), SPAWN_SUBAGENT] },
+        depth: (input.depth ?? 0) + 1
+      })
+    })
+  }
+
   /**
    * Starts one turn. Returns once the Pi session is open; the reply arrives as run events. A
    * session that cannot be opened ends its run as failed and returns no native session id.
@@ -151,14 +191,17 @@ export class Sessions {
     const account = this.options.accounts.resolve(input.accountId, input.poolId)
     const context = this.options.accounts.context(account)
     const runId = input.run.id
-    const caller: CallerContext = { ...input.caller, runId, sessionId: input.caller.sessionId ?? input.run.sessionId }
+    const caller: CallerContext = { ...input.caller, maintenanceJobIds: input.caller.maintenanceJobIds?.slice(), runId, sessionId: input.caller.sessionId ?? input.run.sessionId }
     const broker = input.connections ? this.options.broker : null
+    const depth = input.depth ?? 0
+    const canSpawn = Boolean(input.subagents) && depth < subagentDepth(input.subagents ?? undefined)
     const requestedTools = [...new Set([
-      ...input.tools.allow,
+      ...input.tools.allow.filter((name) => name !== SPAWN_SUBAGENT),
       ASK_USER,
       ...(input.automatic ? [] : [PLUGIN_PROPOSE]),
       ...WIKI_TOOL_NAMES,
-      ...(broker?.toolNames ?? [])
+      ...(broker?.toolNames ?? []),
+      ...(canSpawn ? [SPAWN_SUBAGENT] : [])
     ])]
     const available = this.options.resolveCapabilities
       ? await this.options.resolveCapabilities(caller, requestedTools, input.cwd)
@@ -232,7 +275,7 @@ export class Sessions {
     if (run.finished) return { runId, nativeSessionId: null }
     // What every session has, after the tools the caller switched on and in a fixed order.
     const allow = capabilities.tools
-    const session: ToolSession = { run, caller, allow, depth: input.depth ?? 0, cwd: input.cwd, capabilities }
+    const session: ToolSession = { run, caller, allow, depth, cwd: input.cwd, capabilities }
     const { plugins } = this.options
 
     let pi: PiSessionLike
@@ -241,9 +284,10 @@ export class Sessions {
         ...(broker ? broker.tools(session, { readOnly: typeof input.connections === 'object' && input.connections.readOnly === true }) : []),
         ...memoryTools(this.options.env, caller, capabilities.contributions),
         askUserTool(run),
-        pluginProposeTool(this.options.env, caller)
+        pluginProposeTool(this.options.env, caller),
+        ...(allow.includes(SPAWN_SUBAGENT) ? [this.subagentTool(input, runId, account.id, capabilities)] : [])
       ]
-      for (const provider of this.providers) tools.push(...(await provider(session)))
+      if (input.providers !== false) for (const provider of this.providers) tools.push(...(await provider(session)))
       const params: TurnParams = {
         runId,
         cwd: input.cwd,

package/src/skills/registry.ts

@@ -291,11 +291,16 @@ export function create(root: string, kind: string, rawName: string): RegistrySta
 
 /** Imports complete user-owned skill folders without replacing existing or built-in items. */
 export function importSkills(root: string, bundles: SkillBundleInput[]): RegistryState {
+  return importItems(root, 'skills', bundles)
+}
+
+/** Imports inert registry resources. Prompts and rules are single UTF-8 Markdown documents. */
+export function importItems(root: string, kind: RegistryKind, bundles: SkillBundleInput[]): RegistryState {
   if (!Array.isArray(bundles) || bundles.length === 0 || bundles.length > MAX_SKILL_BUNDLES) {
     throw invalid(`Import between 1 and ${MAX_SKILL_BUNDLES} skills at a time.`)
   }
 
-  const directory = kindDir(root, 'skills')
+  const directory = kindDir(root, kind)
   mkdirSync(directory, { recursive: true })
   const existing = new Set(list(root).map((item) => item.id))
   const seen = new Set<string>()
@@ -308,10 +313,10 @@ export function importSkills(root: string, bundles: SkillBundleInput[]): Registr
     if (name.length > 64) throw invalid('Use a skill name with at most 64 letters or numbers.')
     const slug = Array.from(name.toLowerCase(), (character) => (/^[a-z0-9]$/.test(character) ? character : '-')).join('').split('-').filter(Boolean).join('-')
     if (!slug || slug.length > 64) throw invalid('Use a skill name with at most 64 letters or numbers.')
-    const id = `skills/${slug}`
+    const id = `${kind}/${slug}`
     if (existing.has(id) || seen.has(id)) throw invalid(`The skill “${name}” already exists.`)
     try {
-      lstatSync(join(directory, slug))
+      lstatSync(join(directory, kind === 'skills' ? slug : `${slug}.md`))
       throw invalid(`The skill “${name}” already exists.`)
     } catch (error) {
       if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
@@ -350,7 +355,8 @@ export function importSkills(root: string, bundles: SkillBundleInput[]): Registr
       if (file.encoding === 'base64' && bytes.toString('base64') !== file.content) throw invalid(`The file “${relative}” is not valid base64.`)
       files.set(relative, bytes)
     }
-    if (!files.has('SKILL.md')) throw invalid(`The skill “${name}” must include SKILL.md at its root.`)
+    if (kind === 'skills' && !files.has('SKILL.md')) throw invalid(`The skill “${name}” must include SKILL.md at its root.`)
+    if (kind !== 'skills' && (bundle.files.length !== 1 || bundle.files[0].encoding !== 'utf8' || bundle.files[0].path !== 'CONTENT.md')) throw invalid('A prompt or rule must contain one UTF-8 CONTENT.md file.')
     return { name, slug, files }
   })
 
@@ -366,8 +372,8 @@ export function importSkills(root: string, bundles: SkillBundleInput[]): Registr
       }
     }
     for (const bundle of prepared) {
-      const target = join(directory, bundle.slug)
-      renameSync(join(staging, bundle.slug), target)
+      const target = join(directory, kind === 'skills' ? bundle.slug : `${bundle.slug}.md`)
+      renameSync(kind === 'skills' ? join(staging, bundle.slug) : join(staging, bundle.slug, 'CONTENT.md'), target)
       installed.push(target)
     }
   } catch (error) {
@@ -383,7 +389,7 @@ export function importSkills(root: string, bundles: SkillBundleInput[]): Registr
  * Writes a skill, prompt, or rule (an accepted proposal), keeping an existing item's location.
  * The previous content and the new content are recorded as Wiki revisions of the item.
  */
-export function writeItem(root: string, kind: string, name: string, description: string, body: string, reason: string): string {
+export function writeItem(root: string, kind: string, name: string, description: string, body: string, reason: string, actor = 'user'): string {
   const plural = kind === 'skill' ? 'skills' : kind === 'prompt' ? 'prompts' : kind === 'rule' ? 'rules' : null
   if (!plural) throw invalid('Only skills, prompts, and rules can be written.')
   const stem = store.slug(name)
@@ -395,13 +401,13 @@ export function writeItem(root: string, kind: string, name: string, description:
   const wiki = store.wikiDir(root)
   if (existing) {
     try {
-      store.snapshot(wiki, id, readFileSync(existing.path, 'utf8'), 'user', 'Before accepted proposal')
+      store.snapshot(wiki, id, readFileSync(existing.path, 'utf8'), actor, 'Before accepted proposal')
     } catch {
       // Nothing readable to keep.
     }
   }
   atomicWrite(path, text)
-  store.snapshot(wiki, id, text, 'user', reason)
-  store.log(wiki, `- ${now()} · user · ${existing ? 'updated' : 'created'} \`${id}\` · ${reason}`)
+  store.snapshot(wiki, id, text, actor, reason)
+  store.log(wiki, `- ${now()} · ${actor} · ${existing ? 'updated' : 'created'} \`${id}\` · ${reason}`)
   return id
 }

package/src/terminal/accountsMenu.test.ts

@@ -0,0 +1,225 @@
+import { mkdtempSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+
+import type { AccountsOverview, AccountView } from '../accounts/store'
+import { memorySecretStore } from '../accounts/secrets'
+import { createHarness, type Harness } from '../harness'
+import { rootWithProject, writeFile } from '../../tests/helpers'
+import { SOCKET_ENV, TOKEN_ENV, socketCall, type SocketConnection } from './client'
+import { accountDetails, accountRows, resetIn, runAccountsMenu, type AccountsCall, type AccountsUi, type SessionAccount } from './accountsMenu'
+
+const open: Harness[] = []
+afterEach(async () => {
+  for (const harness of open.splice(0)) await harness.close()
+})
+
+/**
+ * A person at the terminal. Each answer picks the first option that contains it (select), or
+ * is the typed text (input), or is the yes/no (confirm). A select with no matching option fails
+ * the test, so a changed menu label shows up here.
+ */
+function person(answers: (string | boolean | undefined)[]) {
+  const shown: string[] = []
+  const said: { message: string; level?: string }[] = []
+  const next = () => answers.shift()
+  const ui: AccountsUi = {
+    select: async (title, options) => {
+      shown.push(title)
+      const answer = next()
+      if (answer === undefined) return undefined
+      const found = options.find((option) => option.includes(String(answer)))
+      if (!found) throw new Error(`No option containing "${answer}" in: ${options.join(' | ')}`)
+      return found
+    },
+    confirm: async (title) => {
+      shown.push(title)
+      return next() === true
+    },
+    input: async (title) => {
+      shown.push(title)
+      const answer = next()
+      return typeof answer === 'string' ? answer : undefined
+    },
+    notify: (message, level) => void said.push({ message, level })
+  }
+  return { ui, shown, said, remaining: () => answers.length }
+}
+
+function view(id: string, label: string, overrides: Partial<AccountView> = {}): AccountView {
+  return {
+    id,
+    provider: 'pi',
+    label,
+    authKind: 'subscription',
+    createdAt: '2026-10-01T00:00:00.000Z',
+    isDefault: false,
+    state: { health: 'unknown', signedIn: null, authMethod: null, plan: null, identity: null, limits: [], lastError: null, lastCheckedAt: null, cliVersion: null, capabilities: [], piProviders: [] },
+    ...overrides
+  }
+}
+
+describe('the accounts menu, without a terminal', () => {
+  it('numbers each account, marks the default and this session, and shows its health', () => {
+    const overview: AccountsOverview = {
+      accounts: [view('a1', 'Main', { isDefault: true, state: { ...view('a1', 'Main').state, health: 'limited' } }), view('a2', 'Spare')],
+      pools: [],
+      defaults: { pi: 'a1' }
+    }
+    const rows = accountRows(overview, { accountId: 'a2', label: 'Spare' } satisfies SessionAccount)
+    expect(rows.map((row) => row.label)).toEqual(['1. ● Main · Limit reached', '2. ○ Spare · Not checked · this session'])
+    expect(rows[1].account.id).toBe('a2')
+  })
+
+  it('says what the account can do and that providers do not report usage when none is reported', () => {
+    const text = accountDetails(view('a1', 'Main', { state: { ...view('a1', 'Main').state, health: 'auth_expired', piProviders: ['anthropic'], lastError: { category: 'rate_limited', message: 'Slow down.', at: '2026-10-01T00:00:00.000Z', resetsAt: null } } }))
+    expect(text).toContain('Health: Sign in again')
+    expect(text).toContain('Providers: anthropic')
+    expect(text).toContain('Last error: Slow down.')
+    expect(text).toContain('Pi providers do not report them.')
+  })
+
+  it('formats a reset time as a short countdown', () => {
+    const now = Date.parse('2026-10-01T00:00:00.000Z')
+    expect(resetIn('2026-10-01T00:05:00.000Z', now)).toBe('in 5m')
+    expect(resetIn('2026-10-01T02:30:00.000Z', now)).toBe('in 2h 30m')
+    expect(resetIn('2026-10-03T00:00:00.000Z', now)).toBe('in 2d')
+    expect(resetIn('2026-09-30T00:00:00.000Z', now)).toBe('now')
+  })
+})
+
+async function session() {
+  const root = rootWithProject()
+  const base = mkdtempSync(join(tmpdir(), 'accounts-menu-'))
+  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 main = harness.accounts.create('Main', 'apiKey').accounts[0]
+  const spare = harness.accounts.create('Spare', 'apiKey').accounts.find((account) => account.label === 'Spare')!
+  const launch = await harness.terminals.prepare({ sessionId: 'term-1', accountId: main.id, cwd: base, sessionFolder: join(root, 'sessions', 'term-1') })
+  const connection: SocketConnection = { socket: String(launch.env[SOCKET_ENV]), token: String(launch.env[TOKEN_ENV]) }
+  // The extension claims the key before the model runs; the menu uses it for every change.
+  const { key } = await socketCall<{ key: string }>(connection, 'control.claim')
+  const call: AccountsCall = (method, params) => socketCall(connection, method, params ?? {}, 5_000, key)
+  return { harness, main, spare, connection, key, call }
+}
+
+describe('the accounts menu, over the session socket', () => {
+  it('refuses account calls from the shell token, and serves them to the extension with its key', async () => {
+    const { connection, key, main, harness } = await session()
+    await expect(socketCall(connection, 'accounts.list')).rejects.toMatchObject({ code: 'unauthorized' })
+    await expect(socketCall(connection, 'accounts.list', {}, 5_000, 'guessed')).rejects.toMatchObject({ code: 'unauthorized' })
+    await expect(socketCall(connection, 'accounts.deviceId')).rejects.toMatchObject({ code: 'unauthorized' })
+    const listed = await socketCall<AccountsOverview>(connection, 'accounts.list', {}, 5_000, key)
+    expect(listed.accounts.map((account) => account.id)).toContain(main.id)
+    expect(await socketCall<{ accountId: string; label: string }>(connection, 'accounts.session', {}, 5_000, key)).toEqual({ accountId: main.id, label: 'Main' })
+    expect(await socketCall(connection, 'accounts.deviceId', {}, 5_000, key)).toBe(await harness.accounts.installationDeviceId())
+  })
+
+  it('will not remove an account a running terminal is using, this session included', async () => {
+    const { call, main, spare, harness } = await session()
+    await expect(call('accounts.remove', { accountId: main.id })).rejects.toMatchObject({ code: 'account_in_use' })
+    expect(harness.accounts.find(main.id).id).toBe(main.id)
+    // An account with no terminal on it is removed as usual.
+    await call('accounts.remove', { accountId: spare.id })
+    expect(() => harness.accounts.find(spare.id)).toThrow()
+  })
+
+  it('makes an account the default from the menu', async () => {
+    const { call, harness, spare, main } = await session()
+    const { ui, said } = person(['Spare', 'Make default', 'Back', 'Done'])
+    expect(await runAccountsMenu(ui, call, { accountId: main.id, label: 'Main' })).toBeUndefined()
+    expect(harness.accounts.overview().defaults.pi).toBe(spare.id)
+    expect(said.map((entry) => entry.message)).toContain('Spare is the default for new sessions.')
+  })
+
+  it('switches this session to another account by ending Pi, and leaves the choice for the launcher', async () => {
+    const { call, harness, spare, main } = await session()
+    const { ui } = person(['Spare', 'Use for this session', true])
+    const outcome = await runAccountsMenu(ui, call, { accountId: main.id, label: 'Main' })
+    expect(outcome).toBe('relaunch')
+    expect(harness.terminals.takeRelaunch('term-1')).toEqual({ accountId: spare.id, nativeSessionId: null })
+    // Taken once: a second read finds nothing.
+    expect(harness.terminals.takeRelaunch('term-1')).toBeNull()
+  })
+
+  it('does not switch when the person declines the confirmation', async () => {
+    const { call, harness, spare, main } = await session()
+    const { ui } = person(['Spare', 'Use for this session', false, 'Back', 'Done'])
+    expect(await runAccountsMenu(ui, call, { accountId: main.id, label: 'Main' })).toBeUndefined()
+    expect(harness.terminals.takeRelaunch('term-1')).toBeNull()
+    expect(harness.accounts.find(spare.id).id).toBe(spare.id)
+  })
+})
+
+describe('signing in from the accounts menu', () => {
+  it('shows structured OAuth choices and returns the selected provider choice ID', async () => {
+    const overview: AccountsOverview = { accounts: [view('a1', 'Main')], pools: [], defaults: { pi: 'a1' } }
+    const answered: Record<string, unknown>[] = []
+    const statuses = [
+      { loginId: 'L2', revision: 1, status: 'running', events: [], prompt: { type: 'prompt', promptId: 'P2', prompt: { type: 'select', message: 'Select OpenAI Codex login method:', options: [{ id: 'device_code', label: 'Device code login' }, { id: 'browser', label: 'Browser login' }] } }, success: null, error: null, accountId: 'a1', provider: 'openai-codex', method: 'oauth' },
+      { loginId: 'L2', revision: 2, status: 'completed', events: [], prompt: null, success: true, error: null, accountId: 'a1', provider: 'openai-codex', method: 'oauth' }
+    ]
+    const call = (async (method: string, params?: Record<string, unknown>) => {
+      switch (method) {
+        case 'accounts.list':
+          return overview
+        case 'accounts.providers':
+          return [{ id: 'openai-codex', name: 'OpenAI Codex', oauth: true, oauthLabel: 'Sign in with ChatGPT', apiKey: false }]
+        case 'accounts.loginStart':
+          return { loginId: 'L2' }
+        case 'accounts.loginStatus':
+          return statuses.shift()
+        case 'accounts.loginRespond':
+          answered.push(params!)
+          return {}
+        default:
+          throw new Error(`unexpected ${method}`)
+      }
+    }) as unknown as AccountsCall
+    const script = person(['Main', 'Sign in', 'OpenAI Codex', 'Device code login', 'Back', 'Done'])
+
+    expect(await runAccountsMenu(script.ui, call, { accountId: 'a1', label: 'Main' })).toBeUndefined()
+
+    expect(answered).toEqual([{ loginId: 'L2', promptId: 'P2', value: 'device_code' }])
+    expect(script.shown).toContain('Select OpenAI Codex login method:')
+  })
+
+  it('follows a browser sign-in, answers its prompt, and reports the result', async () => {
+    const overview: AccountsOverview = { accounts: [view('a1', 'Main')], pools: [], defaults: { pi: 'a1' } }
+    const answered: Record<string, unknown>[] = []
+    const statuses = [
+      { loginId: 'L1', revision: 1, status: 'running', events: [{ type: 'auth_url', url: 'https://auth.example/start' }], prompt: null, success: null, error: null, accountId: 'a1', provider: 'anthropic', method: 'oauth' },
+      { loginId: 'L1', revision: 2, status: 'running', events: [], prompt: { type: 'prompt', promptId: 'P1', prompt: { type: 'secret', message: 'Paste the code', placeholder: null, options: null } }, success: null, error: null, accountId: 'a1', provider: 'anthropic', method: 'oauth' },
+      { loginId: 'L1', revision: 3, status: 'completed', events: [], prompt: null, success: true, error: null, accountId: 'a1', provider: 'anthropic', method: 'oauth' }
+    ]
+    const call = (async (method: string, params?: Record<string, unknown>) => {
+      switch (method) {
+        case 'accounts.list':
+          return overview
+        case 'accounts.session':
+          return { accountId: 'a1', label: 'Main' }
+        case 'accounts.providers':
+          return [{ id: 'anthropic', name: 'Anthropic', oauth: true, oauthLabel: 'Claude', apiKey: false }]
+        case 'accounts.loginStart':
+          expect(params).toEqual({ accountId: 'a1', provider: 'anthropic' })
+          return { loginId: 'L1' }
+        case 'accounts.loginStatus':
+          return statuses.shift()
+        case 'accounts.loginRespond':
+          answered.push(params!)
+          return {}
+        default:
+          throw new Error(`unexpected ${method}`)
+      }
+    }) as unknown as AccountsCall
+    // Account, then Sign in, then the provider; one sign-in method means no second pick. The
+    // browser step is answered with "Check status", and the prompt is typed as '123'.
+    const script = person(['Main', 'Sign in', 'Anthropic', 'Check status', '123', 'Back', 'Done'])
+    expect(await runAccountsMenu(script.ui, call, { accountId: 'a1', label: 'Main' })).toBeUndefined()
+    expect(answered).toEqual([{ loginId: 'L1', promptId: 'P1', value: '123' }])
+    expect(script.said.map((entry) => entry.message)).toContain('Signed in.')
+    expect(script.remaining()).toBe(0)
+  })
+})