@xingular/harness 0.1.5 → 0.1.7

package/src/terminal/tui/runtime.ts

@@ -0,0 +1,388 @@
+import {
+  createAgentSession, createAgentSessionRuntime, DefaultResourceLoader, ModelRuntime, resolveCliModel,
+  SessionManager, SettingsManager,
+  type AgentSession, type AgentSessionEventListener, type AgentSessionRuntime, type AgentSessionServices,
+  type CreateAgentSessionRuntimeFactory, type ExtensionUIContext
+} from '@earendil-works/pi-coding-agent'
+import { closeSync, openSync, readSync, realpathSync } from 'node:fs'
+import { isAbsolute, join, relative, resolve, sep } from 'node:path'
+
+import terminalExtension from '../piExtension'
+import { claimTerminalControl, controlCall } from '../control'
+import { loadPiAdapter } from './piAdapter'
+import type { SessionAccount } from '../accountsMenu'
+import type { QuestionAnswer } from '../../sessions/registry'
+import type { TerminalQuestion } from './questions'
+import { sessionUiContext } from './sessionUi'
+
+export interface TerminalArguments {
+  appendSystemPrompt: string[]
+  extensions: string[]
+  skills: string[]
+  prompts: string[]
+  themes: string[]
+  sessionDir: string
+  session?: string
+  model?: string
+}
+
+/** The launch specification comes from Terminals.prepare(), never from Pi's own discovery. */
+export function parseTerminalArguments(args: string[]): TerminalArguments {
+  const result: TerminalArguments = { appendSystemPrompt: [], extensions: [], skills: [], prompts: [], themes: [], sessionDir: '' }
+  const lists: Record<string, string[]> = {
+    '--append-system-prompt': result.appendSystemPrompt, '--extension': result.extensions,
+    '--skill': result.skills, '--prompt-template': result.prompts, '--theme': result.themes
+  }
+  const flags = new Set(['--no-extensions', '--no-skills', '--no-prompt-templates', '--no-themes'])
+  for (let index = 0; index < args.length; index++) {
+    const argument = args[index]
+    if (flags.has(argument)) continue
+    if (!(argument in lists) && !['--session-dir', '--session', '--model'].includes(argument)) {
+      throw new Error(`Unsupported prepared terminal argument: ${argument}`)
+    }
+    const value = args[++index]
+    if (!value || value.startsWith('--')) throw new Error(`${argument} needs a value.`)
+    if (argument in lists) lists[argument].push(value)
+    else if (argument === '--session-dir') result.sessionDir = value
+    else if (argument === '--session') result.session = value
+    else result.model = value
+  }
+  if (!result.sessionDir) throw new Error('The Harness terminal requires its prepared --session-dir.')
+  if (!result.extensions.length) throw new Error('The Harness terminal requires its prepared bridge extension.')
+  return result
+}
+
+export interface TerminalRuntimeHost {
+  ui: ExtensionUIContext
+  shutdown(): void
+  notify(message: string): void
+  changed(): void
+  resources?(services: AgentSessionServices): void
+}
+
+type SessionChangeListener = (session: AgentSession) => void | Promise<void>
+type NewOptions = Parameters<AgentSessionRuntime['newSession']>[0]
+type SwitchOptions = Parameters<AgentSessionRuntime['switchSession']>[1]
+type ForkOptions = Parameters<AgentSessionRuntime['fork']>[1]
+type TreeOptions = Parameters<AgentSession['navigateTree']>[1]
+
+export interface TerminalSnapshot {
+  readonly sessionId: string
+  readonly sessionFile?: string
+  readonly name?: string
+  readonly cwd: string
+  readonly account: Readonly<SessionAccount> | null
+  readonly model?: Readonly<{ id: string; provider: string; name: string; reasoning: boolean; contextWindow: number }>
+  readonly thinkingLevel: AgentSession['thinkingLevel']
+  readonly isStreaming: boolean
+  readonly idle: boolean
+  readonly hasUserMessages: boolean
+  readonly hideThinking: boolean
+  readonly context: Readonly<{ percent: number | null; window: number }>
+  readonly costUsd: number
+  readonly subscription: boolean
+  readonly queue: Readonly<{ steering: readonly string[]; followUp: readonly string[] }>
+}
+
+export interface TerminalDecision extends TerminalQuestion { type: 'approval' | 'question'; target?: string; action?: string }
+
+export interface TerminalRuntime {
+  pending(): Promise<TerminalDecision[]>
+  approve(requestId: string, decision: 'approved' | 'denied'): Promise<void>
+  answer(requestId: string, answer: QuestionAnswer): Promise<void>
+  answerBatch(batchId: string, answers: Array<{ questionId: string; answer: QuestionAnswer }>): Promise<void>
+  snapshot(): TerminalSnapshot
+  submit(text: string, followUp?: boolean): Promise<void>
+  readonly session: AgentSession
+  readonly services: AgentSessionServices
+  readonly cwd: string
+  readonly sessionDirectory: string
+  subscribe(listener: AgentSessionEventListener): () => void
+  onSessionChange(listener: SessionChangeListener): () => void
+  onBeforeSessionChange(listener: () => void): () => void
+  newSession(options?: NewOptions): ReturnType<AgentSessionRuntime['newSession']>
+  switchSession(path: string, options?: SwitchOptions): ReturnType<AgentSessionRuntime['switchSession']>
+  fork(entryId: string, options?: ForkOptions): ReturnType<AgentSessionRuntime['fork']>
+  navigateTree(targetId: string, options?: TreeOptions): ReturnType<AgentSession['navigateTree']>
+  importFromJsonl(path: string, cwdOverride?: string): ReturnType<AgentSessionRuntime['importFromJsonl']>
+  installationDeviceId(): Promise<string>
+  reload(): Promise<void>
+  interrupt(): Promise<void>
+  dispose(): Promise<void>
+}
+
+/** Saved native history stays in the prepared project folder, including symlink targets. */
+export function assertTerminalHistoryPath(path: string, sessionDirectory: string): void {
+  const within = relative(realpathSync(sessionDirectory), realpathSync(path))
+  if (!within || within === '..' || within.startsWith(`..${sep}`) || isAbsolute(within)) {
+    throw new Error('Resume only from this terminal history folder. Use /import for another native session file in this working folder.')
+  }
+}
+
+/** Inspect the header before any native switch/import can invalidate a session or copy a file. */
+export function assertTerminalSessionScope(path: string, cwd: string, cwdOverride?: string): void {
+  if (cwdOverride !== undefined && realpathSync(resolve(cwdOverride)) !== realpathSync(cwd)) {
+    throw new Error('Resume this conversation in a terminal opened for its own working folder.')
+  }
+  const descriptor = openSync(path, 'r')
+  let first: string
+  try {
+    const buffer = Buffer.alloc(65_536)
+    const size = readSync(descriptor, buffer, 0, buffer.length, 0)
+    const text = buffer.subarray(0, size).toString('utf8').replace(/^\uFEFF/, '')
+    const newline = text.indexOf('\n')
+    if (newline === -1 && size === buffer.length) throw new Error('The native session header is too large.')
+    first = newline === -1 ? text : text.slice(0, newline)
+  } finally {
+    closeSync(descriptor)
+  }
+  let header: { type?: string; cwd?: string }
+  try {
+    header = JSON.parse(first) as typeof header
+  } catch {
+    throw new Error('This file does not have a readable native session header.')
+  }
+  if (header.type !== 'session' || !header.cwd || !isAbsolute(header.cwd)) {
+    throw new Error('The native session must record its original absolute working folder.')
+  }
+  if (realpathSync(header.cwd) !== realpathSync(cwd)) {
+    throw new Error('This conversation belongs to another working folder. Open its terminal to keep project permissions and context isolated.')
+  }
+}
+
+export async function createTerminalRuntime(args: string[], host: TerminalRuntimeHost): Promise<TerminalRuntime> {
+  const prepared = parseTerminalArguments(args)
+  const cwd = realpathSync(process.cwd())
+  const agentDirValue = process.env.PI_CODING_AGENT_DIR
+  if (!agentDirValue || !isAbsolute(agentDirValue)) throw new Error('The Harness terminal requires its isolated account directory.')
+  const agentDir = realpathSync(agentDirValue)
+  const sessionDirectory = realpathSync(resolve(cwd, prepared.sessionDir))
+  if (prepared.session) {
+    const path = resolve(cwd, prepared.session)
+    assertTerminalHistoryPath(path, sessionDirectory)
+    assertTerminalSessionScope(path, cwd)
+  }
+
+  // Claim before loading any plugin code and retain it in the trusted process across reloads.
+  await claimTerminalControl()
+  const identity = await controlCall<SessionAccount>('accounts.session').catch(() => null)
+  const account = identity && typeof identity.accountId === 'string' && typeof identity.label === 'string'
+    ? Object.freeze({ accountId: identity.accountId, label: identity.label }) : null
+  const adapter = await loadPiAdapter()
+  const modelRuntime = await ModelRuntime.create({ authPath: join(agentDir, 'auth.json'), modelsPath: join(agentDir, 'models.json') })
+  const listeners = new Set<AgentSessionEventListener>()
+  const changes = new Set<SessionChangeListener>()
+  const beforeChanges = new Set<() => void>()
+  let unsubscribe: (() => void) | undefined
+  let changing = false
+  let disposed = false
+  let uiGeneration = 0
+  let deviceIdPromise: Promise<string> | null = null
+  const installationDeviceId = (): Promise<string> => {
+    if (!deviceIdPromise) {
+      deviceIdPromise = controlCall<string>('accounts.deviceId').catch((error: unknown) => {
+        deviceIdPromise = null
+        throw error
+      })
+    }
+    return deviceIdPromise
+  }
+  const currentUi = () => {
+    const generation = uiGeneration
+    return sessionUiContext(host.ui, () => !disposed && generation === uiGeneration)
+  }
+
+  const factory: CreateAgentSessionRuntimeFactory = async ({ cwd: targetCwd, sessionManager, sessionStartEvent }) => {
+    if (realpathSync(targetCwd) !== cwd) throw new Error('A native session cannot change this terminal working folder.')
+    const settingsManager = SettingsManager.create(cwd, agentDir)
+    const resourceLoader = new DefaultResourceLoader({
+      cwd, agentDir,
+      // The real settings still control models and tools; empty discovery settings prevent a
+      // second resource decision outside the Harness's trusted prepare() result.
+      settingsManager: SettingsManager.inMemory({}),
+      noExtensions: true, noSkills: true, noPromptTemplates: true, noThemes: true,
+      additionalExtensionPaths: prepared.extensions.slice(0, -1),
+      additionalSkillPaths: prepared.skills, additionalPromptTemplatePaths: prepared.prompts,
+      additionalThemePaths: prepared.themes,
+      extensionFactories: [...adapter.builtins, { name: 'harness-terminal-bridge', factory: terminalExtension, hidden: true }],
+      appendSystemPromptOverride: (base) => [...base, ...prepared.appendSystemPrompt]
+    })
+    const reloadResources = resourceLoader.reload.bind(resourceLoader)
+    resourceLoader.reload = async (options) => {
+      // Recheck the host's exact package trust and attachment identities before every load,
+      // including the reload performed internally by AgentSession.reload().
+      await controlCall('terminal.resources', {}, 30_000)
+      await reloadResources(options)
+    }
+    await resourceLoader.reload()
+    const errors = resourceLoader.getExtensions().errors
+    if (errors.length) throw new Error(errors.map((error) => `${error.path}: ${error.error}`).join('\n'))
+    let selected: ReturnType<typeof resolveCliModel> | undefined
+    if (prepared.model && sessionStartEvent?.reason === 'startup') {
+      selected = resolveCliModel({ cliModel: prepared.model, modelRuntime })
+      if (selected.error || !selected.model) throw new Error(selected.error ?? `Model ${prepared.model} is unavailable.`)
+    }
+    const created = await createAgentSession({
+      cwd, agentDir, modelRuntime, settingsManager, resourceLoader, sessionManager, sessionStartEvent,
+      ...(selected?.model ? { model: selected.model } : {}),
+      ...(selected?.thinkingLevel ? { thinkingLevel: selected.thinkingLevel } : {})
+    })
+    const services: AgentSessionServices = { cwd, agentDir, modelRuntime, settingsManager, resourceLoader, diagnostics: [] }
+    host.resources?.(services)
+    return { ...created, services, diagnostics: services.diagnostics }
+  }
+  const native = await createAgentSessionRuntime(factory, {
+    cwd, agentDir,
+    sessionManager: prepared.session ? SessionManager.open(resolve(cwd, prepared.session), sessionDirectory) : SessionManager.create(cwd, sessionDirectory),
+    sessionStartEvent: { type: 'session_start', reason: 'startup' }
+  })
+
+  const before = () => {
+    uiGeneration += 1
+    unsubscribe?.()
+    unsubscribe = undefined
+    for (const listener of beforeChanges) listener()
+  }
+  const announce = async () => {
+    for (const listener of changes) await listener(native.session)
+    host.changed()
+  }
+  const exclusive = async <T>(action: () => Promise<T>): Promise<T> => {
+    if (disposed) throw new Error('The terminal runtime has closed.')
+    if (changing) throw new Error('A native session change is already in progress.')
+    if (!native.session.isIdle) throw new Error('Stop the current response before changing or reloading this session.')
+    changing = true
+    try {
+      await controlCall('terminal.resources', {}, 30_000)
+      return await action()
+    } finally {
+      changing = false
+    }
+  }
+  const decide = async (call: string, params: Record<string, unknown>): Promise<void> => {
+    if (disposed) throw new Error('The terminal runtime has closed.')
+    await controlCall(call, params)
+  }
+  const runtime: TerminalRuntime = {
+    async pending() {
+      if (disposed) return []
+      return (await controlCall<{ requests: TerminalDecision[] }>('terminal.pending')).requests
+    },
+    approve: (requestId, decision) => decide('terminal.approve', { requestId, decision }),
+    answer: (requestId, answer) => decide('terminal.answer', { requestId, answer }),
+    answerBatch: (batchId, answers) => decide('terminal.answers', { batchId, answers }),
+    snapshot() {
+      const session = native.session
+      const usage = session.getContextUsage()
+      const model = session.model?.id === 'unknown' ? undefined : session.model
+      return Object.freeze({
+        sessionId: session.sessionId, sessionFile: session.sessionFile, name: session.sessionName,
+        cwd, account,
+        model: model ? Object.freeze({ id: model.id, provider: model.provider, name: model.name, reasoning: model.reasoning, contextWindow: model.contextWindow }) : undefined,
+        thinkingLevel: session.thinkingLevel, isStreaming: session.isStreaming, idle: session.isIdle,
+        hasUserMessages: session.state.messages.some(message => message.role === 'user'),
+        hideThinking: session.settingsManager.getHideThinkingBlock(),
+        context: Object.freeze({ percent: usage?.percent ?? null, window: usage?.contextWindow ?? model?.contextWindow ?? 0 }),
+        costUsd: session.getSessionStats().cost,
+        subscription: model ? session.modelRuntime.isUsingSubscription(model.provider) : false,
+        queue: Object.freeze({ steering: Object.freeze([...session.getSteeringMessages()]), followUp: Object.freeze([...session.getFollowUpMessages()]) })
+      })
+    },
+    async submit(text, followUp = false) {
+      if (disposed) throw new Error('The terminal runtime has closed.')
+      if (changing) throw new Error('Wait for the native session change to finish before submitting.')
+      const input = text.trimStart().startsWith('/') ? text.trimStart() : text
+      await native.session.prompt(input, native.session.isStreaming ? { streamingBehavior: followUp ? 'followUp' : 'steer' } : {})
+    },
+    get session() { return native.session },
+    get services() { return native.services },
+    cwd, sessionDirectory,
+    subscribe(listener) { listeners.add(listener); return () => { listeners.delete(listener) } },
+    onSessionChange(listener) { changes.add(listener); return () => { changes.delete(listener) } },
+    onBeforeSessionChange(listener) { beforeChanges.add(listener); return () => { beforeChanges.delete(listener) } },
+    newSession: (options) => exclusive(() => native.newSession(options)),
+    switchSession: (path, options) => exclusive(async () => {
+      const target = resolve(cwd, path)
+      assertTerminalHistoryPath(target, sessionDirectory)
+      assertTerminalSessionScope(target, cwd, options?.cwdOverride)
+      return native.switchSession(target, options)
+    }),
+    fork: (entryId, options) => exclusive(() => native.fork(entryId, options)),
+    navigateTree: (targetId, options) => exclusive(async () => {
+      const result = await native.session.navigateTree(targetId, options)
+      if (!result.cancelled) await announce()
+      return result
+    }),
+    importFromJsonl: (path, cwdOverride) => exclusive(async () => {
+      const target = resolve(cwd, path)
+      assertTerminalSessionScope(target, cwd, cwdOverride)
+      return native.importFromJsonl(target, cwdOverride)
+    }),
+    installationDeviceId,
+    reload: () => exclusive(async () => {
+      // Refuse a revoked or changed resource set before tearing down the currently usable UI.
+      await controlCall('terminal.resources', {}, 30_000)
+      await runtime.interrupt()
+      before()
+      await native.session.reload({ beforeSessionStart: async () => {
+        native.session.extensionRunner.setUIContext(currentUi(), 'tui')
+        observeSession()
+        await announce()
+      } })
+      host.changed()
+    }),
+    async interrupt() {
+      // Socket-backed questions and approvals must settle before Pi can finish aborting tools.
+      await controlCall('terminal.interrupt', {}, 15_000).catch(() => {})
+      await native.session.abort()
+    },
+    async dispose() {
+      if (disposed) return
+      disposed = true
+      try {
+        await runtime.interrupt()
+        await native.dispose()
+      } finally {
+        unsubscribe?.()
+        listeners.clear()
+        changes.clear()
+        beforeChanges.clear()
+      }
+    }
+  }
+  const observeSession = () => {
+    unsubscribe?.()
+    unsubscribe = native.session.subscribe(event => {
+      for (const listener of listeners) listener(event)
+      host.changed()
+    })
+  }
+  const bind = async () => {
+    const session = native.session
+    observeSession()
+    await session.bindExtensions({
+      uiContext: currentUi(), mode: 'tui', shutdownHandler: () => host.shutdown(),
+      abortHandler: () => { void runtime.interrupt().catch((error) => host.notify(error instanceof Error ? error.message : String(error))) },
+      onError: (error) => host.notify(`${error.event}: ${error.error}`),
+      commandContextActions: {
+        waitForIdle: () => native.session.waitForIdle(),
+        newSession: (options) => runtime.newSession(options),
+        switchSession: (path, options) => runtime.switchSession(path, options),
+        fork: (entryId, options) => runtime.fork(entryId, options),
+        navigateTree: (targetId, options) => runtime.navigateTree(targetId, options),
+        reload: () => runtime.reload()
+      }
+    })
+    await announce()
+    if (native.modelFallbackMessage) host.notify(native.modelFallbackMessage)
+  }
+  native.setBeforeSessionInvalidate(before)
+  native.setRebindSession(bind)
+  try {
+    await bind()
+  } catch (error) {
+    await runtime.dispose()
+    throw error
+  }
+  return runtime
+}

package/src/terminal/tui/sessionUi.ts

@@ -0,0 +1,24 @@
+import type { ExtensionUIContext } from '@earendil-works/pi-coding-agent'
+
+const dialogs = new Set(['select', 'input', 'editor', 'custom'])
+
+/** Retained UI methods belong to the resource generation that received them. */
+export function sessionUiContext(ui: ExtensionUIContext, current: () => boolean): ExtensionUIContext {
+  return new Proxy(ui, {
+    get(target, key, receiver) {
+      const value = Reflect.get(target, key, receiver)
+      if (typeof value !== 'function') return value
+      return (...args: unknown[]) => {
+        if (current()) return Reflect.apply(value, target, args)
+        if (key === 'confirm') return Promise.resolve(false)
+        if (dialogs.has(String(key))) return Promise.resolve(undefined)
+        if (key === 'onTerminalInput') return () => {}
+        if (key === 'setTheme') return { success: false, error: 'This terminal session has ended.' }
+        if (key === 'getEditorText') return ''
+        if (key === 'getToolsExpanded') return false
+        if (key === 'getAllThemes') return []
+        return undefined
+      }
+    }
+  })
+}

package/src/terminal/tui/settings.test.ts

@@ -0,0 +1,150 @@
+import type { Theme } from '@earendil-works/pi-coding-agent'
+import { CURSOR_MARKER, stripTerminalSequences, visibleWidth, type TUI } from '@earendil-works/pi-tui'
+import { describe, expect, it, vi } from 'vitest'
+
+import { SettingsPanel, type TerminalSettingItem } from './settings'
+import { createHarnessTheme } from './theme'
+
+const theme = createHarnessTheme({ getColorMode: () => 'truecolor' } as Theme)
+const items: TerminalSettingItem[] = [
+  { id: 'theme', tab: 'appearance', group: 'Theme', label: 'Dark Theme', value: 'Titanium', description: 'Theme used with dark terminal backgrounds.' },
+  { id: 'composer', tab: 'appearance', group: 'Composer', label: 'Composer Shape', value: 'Band', description: 'Choose the terminal input layout.' },
+  { id: 'expanded', tab: 'appearance', group: 'Display', label: 'Expand Tool Output', value: 'Off', description: 'Expand actual output from tools.' },
+  { id: 'thinking', tab: 'model', group: 'Thinking', label: 'Thinking Level', value: 'High', description: 'Control reasoning effort for the current model.' },
+  { id: 'input', tab: 'interaction', group: 'Input', label: 'Autocomplete', value: 'On' },
+  { id: 'compact', tab: 'context', group: 'Compaction', label: 'Auto Compact', value: 'On', description: 'Compact the context when the supported token threshold is reached.' }
+]
+function setup(initialId?: string, rows = 30, source = items) {
+  const terminal = { rows }
+  const done = vi.fn()
+  const panel = new SettingsPanel({ terminal } as unknown as TUI, () => theme, source, done, initialId)
+  panel.focused = true
+  return { panel, done, terminal }
+}
+const plain = (panel: SettingsPanel, width = 100) => panel.render(width).map(stripTerminalSequences)
+
+describe('the supported settings terminal panel', () => {
+  it('fills the terminal with the upstream rounded settings frame, supported tabs and group rail', () => {
+    const { panel } = setup()
+    const rows = plain(panel)
+    expect(rows).toHaveLength(30)
+    expect(rows[0]).toMatch(/^╭─ Settings /)
+    expect(rows[0]).toMatch(/╮$/)
+    expect(rows.at(-1)).toMatch(/^╰─.*╯$/)
+    expect(rows[1]).toContain('🎨 Appearance')
+    expect(rows[1]).toContain('Model')
+    expect(rows[1]).toContain('Interaction')
+    expect(rows[1]).toContain('Context')
+    expect(rows.join('\n')).not.toMatch(/Providers|Advisor|Preview:|Tasks|Memory/)
+    expect(rows.some(row => row.includes('│   Theme') && row.slice(25).includes('│'))).toBe(true)
+    expect(rows.join('\n')).toContain('❯ Dark Theme')
+    expect(rows.join('\n')).toContain('Titanium')
+    expect(rows.join('\n')).toContain('Theme used with dark terminal backgrounds.')
+    expect(panel.render(100).join('')).toContain(theme.getBgAnsi('selectedBg'))
+    const compactTabs = plain(panel, 40)[1]
+    for (const icon of ['🎨', '🤖', '⌨', '📋']) expect(compactTabs).toContain(icon)
+  })
+
+  it('uses flat rows at 80 columns and a section rail only when the value pane fits', () => {
+    const { panel } = setup()
+    const narrow = plain(panel, 80).find(row => row.includes('❯ Dark Theme'))!
+    const wide = plain(panel, 100).find(row => row.includes('❯ Dark Theme'))!
+    expect(narrow.match(/│/g)).toHaveLength(2)
+    expect(wide.match(/│/g)).toHaveLength(3)
+  })
+
+  it('moves through tabs and items and resolves only an actual selected setting id', () => {
+    const { panel, done } = setup()
+    panel.handleInput('\x1b[B')
+    expect(panel.selectedId).toBe('composer')
+    panel.handleInput('\r')
+    expect(done).toHaveBeenLastCalledWith('composer')
+    panel.handleInput('\x1b[C')
+    expect(panel.selectedId).toBe('thinking')
+    panel.handleInput(' ')
+    expect(done).toHaveBeenLastCalledWith('thinking')
+    panel.handleInput('\x1b[D')
+    expect(panel.selectedId).toBe('composer')
+    panel.handleInput('\x1b')
+    expect(done).toHaveBeenLastCalledWith(undefined)
+  })
+
+  it('moves group focus through the rail and returns to item editing without triggering an action', () => {
+    const { panel, done } = setup()
+    panel.handleInput('\t')
+    panel.handleInput('\x1b[B')
+    expect(panel.selectedId).toBe('composer')
+    expect(plain(panel).join('\n')).toContain('❯ Composer')
+    panel.handleInput('\r')
+    expect(done).not.toHaveBeenCalled()
+    panel.handleInput('\r')
+    expect(done).toHaveBeenCalledWith('composer')
+  })
+
+  it('restores the last selected tab, group and item from initialId', () => {
+    const { panel } = setup('compact')
+    expect(panel.selectedId).toBe('compact')
+    expect(plain(panel)[1]).toContain('Context')
+    expect(plain(panel).join('\n')).toContain('❯ Auto Compact')
+    expect(plain(panel).join('\n')).not.toContain('Dark Theme')
+    expect(setup('missing').panel.selectedId).toBe('theme')
+  })
+
+  it('searches across supported tabs using labels, values and descriptions with a visible cursor', () => {
+    const { panel, done } = setup()
+    panel.handleInput('reasoning')
+    const rows = plain(panel).join('\n')
+    expect(rows).toContain('1 match')
+    expect(rows).toContain('Thinking Level')
+    expect(rows).not.toContain('Dark Theme')
+    expect(panel.render(100).join('')).toContain(CURSOR_MARKER)
+    panel.handleInput('\r')
+    expect(done).toHaveBeenCalledWith('thinking')
+    panel.handleInput('\x1b')
+    expect(done).toHaveBeenLastCalledWith(undefined)
+  })
+
+  it('renders explicit empty search results and never selects a hidden item', () => {
+    const { panel, done } = setup()
+    panel.handleInput('zzzzzzzzzzz')
+    expect(plain(panel).join('\n')).toContain('No matching settings')
+    expect(panel.selectedId).toBeUndefined()
+    panel.handleInput('\r')
+    panel.handleInput(' ')
+    expect(done).not.toHaveBeenCalled()
+    panel.handleInput('\x7f')
+    expect(panel.selectedId).toBeUndefined()
+  })
+
+  it('keeps the selected setting visible as lists grow and the terminal resizes', () => {
+    const source = Array.from({ length: 100 }, (_, index) => ({ id: `item${index}`, tab: 'appearance', group: 'Display', label: `Setting ${index}`, value: String(index) }))
+    const { panel, terminal } = setup('item85', 20, source)
+    for (const height of [40, 20, 10, 7]) {
+      terminal.rows = height
+      expect(plain(panel).join('\n'), `height ${height}`).toContain('❯ Setting 85')
+      expect(panel.render(80)).toHaveLength(height)
+    }
+    expect(panel.selectedId).toBe('item85')
+  })
+
+  it('bounds every row and terminal height for narrow Unicode labels and descriptions', () => {
+    const source = [{ id: 'cjk', tab: 'appearance', group: '日本語 🧠', label: '知識設定 日本語', value: '🧠 有効', description: '日本語の説明を長く表示します。'.repeat(20) }]
+    const { panel, terminal } = setup('cjk', 30, source)
+    for (const height of [0, 1, 3, 6, 10, 20, 40]) {
+      terminal.rows = height
+      for (let width = 0; width <= 130; width++) {
+        const rows = panel.render(width)
+        expect(rows.length, `${width}x${height}`).toBeLessThanOrEqual(height)
+        for (const row of rows) expect(visibleWidth(row), `${width}x${height}`).toBeLessThanOrEqual(width)
+      }
+    }
+    expect(panel.selectedId).toBe('cjk')
+  })
+
+  it('does not expose unsupported categories or mutate caller setting data', () => {
+    const source = Object.freeze([...items, Object.freeze({ id: 'fake', tab: 'tasks', group: 'Agents', label: 'Invented feature', value: 'Off' })])
+    const { panel } = setup(undefined, 30, source as unknown as TerminalSettingItem[])
+    expect(plain(panel).join('\n')).not.toContain('Invented feature')
+    expect(source[0].value).toBe('Titanium')
+  })
+})